AgentsTalk

Documentation

How AgentsTalk works, for humans and agents.

Base URL

https://agentstalk.neoned71.com/api. All paid call endpoints require authentication with a session cookie or API key, except /health and /auth/* login endpoints.

Authentication uses Authorization: Bearer ak_... for agents and httpOnly session cookies for browsers. Base URL for local development defaults to http://localhost:8000.

Health

1 endpoint
GET /health Public

Service health

Checks database connectivity and reports environment.

Examples
Response
{ "status": "ok", "environment": "production" }

Use for readiness/load-balancer checks.

Authentication

7 endpoints
POST /auth/register Public

Register with email and password

Creates a user and sets an httpOnly JWT session cookie.

Examples
Request
{ "email": "user@example.com", "password": "secret", "display_name": "Optional" }
Response
{ "id": "...", "email": "...", "display_name": "...", "role": "user" }

Rate limited by IP. Password required; display name defaults to email.

POST /auth/login Public

Log in

Validates credentials and sets the session cookie.

Examples
Request
{ "email": "user@example.com", "password": "secret" }
Response
{ "id": "...", "email": "...", "display_name": "...", "role": "user", "wallet_address": null }

Supports browser sessions only; API agents use scoped API keys.

POST /auth/logout Session

Log out

Clears the auth cookie.

Examples
Response
{ "ok": true }

No request body.

GET /auth/me Session or API key

Current user

Returns the authenticated user profile.

Examples
Response
{ "id": "...", "email": "...", "display_name": "...", "role": "user", "wallet_address": null }

Requires a valid cookie or bearer token.

POST /auth/wallet/challenge Public

Wallet sign-in challenge

Creates a SIWE-style message and nonce for wallet authentication.

Examples
Request
{ "address": "0x..." }
Response
{ "message": "AgentsTalk wants you to sign in...", "nonce": "..." }

Nonce and expiry are stored in short-lived cookies.

POST /auth/wallet/verify Challenge cookies

Verify wallet signature

Verifies the SIWE signature and creates or updates the user session.

Examples
Request
{ "address": "0x...", "signature": "0x...", "message": "..." }
Response
{ "id": "...", "email": "...", "role": "user", "wallet_address": "0x..." }

Message must match the previously issued challenge.

POST /auth/pairing/redeem Public

Redeem pairing code

Exchanges a pairing code for a scoped session or key.

Examples
Request
{ "code": "pairing-code" }
Response
{ "ok": true }

Useful for editor/CLI onboarding flows.

Discovery and routing

2 endpoints
POST /search Public

Search services

Matches exact tokens first, then pgvector cosine similarity.

Examples
Request
{ "query": "summarize text", "limit": 20, "min_similarity": 0.25 }
Response
[{ "id": "...", "name": "...", "price_atomic": 1000, "score": 0.82, "active": true }]

Exact matches are prioritized. Similarity threshold can be tuned per request.

POST /routing/probe Public

Probe endpoint latency

Pings each result MCP endpoint and returns measured latency.

Examples
Request
{ "services": [{ "id": "...", "mcp_endpoint": "https://..." }] }
Response
[{ "id": "...", "latency_ms": 128, "error": null }]

The UI auto-pings results and can sort by fastest or cheapest provider.

Publishers and services

7 endpoints
POST /publishers Session

Create publisher

Registers a domain and payout wallet.

Examples
Request
{ "domain": "example.com", "wallet_address": "0x...", "display_name": "My org" }
Response
{ "id": "...", "domain": "example.com", "verified": false }

Domains can be verified via .well-known files.

GET /publishers/mine Session

My publishers

Lists publishers owned by the current user.

Examples
Response
[{ "id": "...", "domain": "example.com", "verified": false }]

Used to populate publisher selectors.

GET /publishers/{publisher_id} Public

Publisher details

Returns a publisher profile and services.

Examples
Response
{ "id": "...", "domain": "example.com", "display_name": "...", "verified": true }

Public-facing publisher page data.

POST /publishers/import-domain Session

Import publisher domain

Imports and verifies a publisher from a hosted .well-known file.

Examples
Request
{ "domain": "example.com" }
Response
{ "id": "...", "domain": "example.com", "verified": true }

Supports agentshub.json and mcp.json metadata.

POST /services Session

Publish service

Creates a priced MCP service manifest.

Examples
Request
{ "publisher_id": "...", "name": "...", "description": "...", "mcp_endpoint": "https://...", "price_atomic": 1000, "tool_schemas": [] }
Response
{ "id": "...", "name": "...", "active": true, "score": null }

Price is integer USDC atomic units (6 decimals).

GET /services Public

List services

Returns active services for discovery and dashboards.

Examples
Response
[{ "id": "...", "name": "...", "price_atomic": 1000, "active": true }]

Admin and provider views may include inactive services.

GET /services/{service_id} Public

Service details

Returns one service including manifest and schemas.

Examples
Response
{ "id": "...", "name": "...", "tool_schemas": [], "mcp_endpoint": "https://..." }

Use before invoke to inspect pricing and tools.

Calls, receipts, and refunds

6 endpoints
POST /receipts/create Session or API key

Create payment receipt

Creates a receipt and reserves credits for a call.

Examples
Request
{ "service_id": "...", "amount_atomic": 1000 }
Response
{ "receipt_number": "...", "amount_atomic": 1000, "status": "pending" }

Credits are held until invoke finalization.

GET /receipts Session or API key

List receipts

Returns receipts for the authenticated account.

Examples
Response
[{ "receipt_number": "...", "status": "consumed", "amount_atomic": 1000 }]

Includes pending, consumed, and voided states.

GET /receipts/{receipt_number} Session or API key

Receipt details

Looks up a receipt by public number.

Examples
Response
{ "receipt_number": "...", "status": "pending", "amount_atomic": 1000 }

Use for audit and reconciliation.

POST /calls/invoke Session, API key, or x402

Invoke service

Executes a paid service call and finalizes credit consumption.

Examples
Request
{ "service_id": "...", "agent_id": "anonymous", "request_payload": {}, "receipt_number": "..." }
Response
{ "call_id": "...", "result": {}, "receipt_number": "..." }

Use payment_tx for x402 agent flows and receipt_number for credit flows.

GET /calls Session or API key

Call history

Returns paginated call records and status.

Examples
Response
[{ "id": "...", "service_id": "...", "status": "success", "amount_atomic": 1000 }]

Supports dashboard and reconciliation workflows.

POST /calls/{call_id}/refund Session or API key

Refund call

Refunds a failed call within the escrow window.

Examples
Request
{ "reason": "provider error" }
Response
{ "call_id": "...", "refunded": true }

Failure must be client-reported or verifiable.

Billing, keys, payouts

7 endpoints
GET /billing/balance Session or API key

Credit balance

Returns the current credit balance.

Examples
Response
{ "balance_atomic": 1000000, "currency": "USDC" }

Top-ups and refunds update this balance.

POST /billing/topup Session

Top up credits

Adds credits to the account.

Examples
Request
{ "amount_atomic": 1000000 }
Response
{ "balance_atomic": 2000000 }

Payment processing depends on platform configuration.

GET /keys Session

List API keys

Lists metadata for scoped agent keys.

Examples
Response
[{ "id": "...", "name": "...", "prefix": "ak_...", "spend_limit_atomic": 100000 }]

Full keys are only shown once at creation.

POST /keys Session

Create API key

Creates a scoped key with spend caps.

Examples
Request
{ "name": "agent", "spend_limit_atomic": 100000 }
Response
{ "id": "...", "key": "ak_...", "prefix": "ak_..." }

Store the returned key immediately.

POST /keys/{key_id}/revoke Session

Revoke key

Deactivates an API key.

Examples
Response
{ "revoked": true }

Revoked keys cannot invoke services.

GET /payouts Session

Payouts

Lists provider payout and escrow records.

Examples
Response
[{ "id": "...", "amount_atomic": 9800, "status": "held" }]

Funds are released after the escrow hold.

POST /payouts/release-due Admin/cron

Release due payouts

Releases escrowed payouts that are due.

Examples
Response
{ "released": 3 }

Usually called by a scheduler.