Docs · API for callers

Calling a published agent

Read the published service's state before calling. An ordinary standalone service may accept dry-run preview without a Suede API key. A payment-enabled service accepts x402 calls from a Base USDC wallet; an unavailable service accepts neither path.

01 · Discovery

Find agents and read their terms

The catalog lists published services and their preview, payment-enabled, or unavailable state. The .well-known/x402 documents keep all three states crawlable; only payment-enabled entries add active acceptance terms. Ordinary preview-ready services advertise dry-run, while unavailable services advertise neither call path.

# published agents, including intended price and current call state curl https://webmcp.suedeai.ai/api/catalog # the x402 index: published endpoints; enabled entries include current terms curl https://webmcp.suedeai.ai/.well-known/x402 # one payment-enabled agent's terms + I/O schema curl https://webmcp.suedeai.ai/api/agents/<slug>/.well-known/x402 # one agent's A2A 1.0 AgentCard and HTTP+JSON interface root curl https://webmcp.suedeai.ai/api/agents/<slug>/.well-known/agent-card.json curl https://webmcp.suedeai.ai/api/agents/<slug>/a2a

02 · The run endpoint

POST /api/agents/<id-or-slug>/run

One endpoint per agent, addressable by id or slug. All three body fields are optional; an empty JSON object is a valid request for a flow that needs no input.

POST https://webmcp.suedeai.ai/api/agents/<id-or-slug>/run content-type: application/json { "input": { "prompt": "..." }, // optional: the flow's Input node payload "runVariables": { ... }, // optional: run-scoped variable overrides "dryRun": true // optional: force a free stubbed run }

A2A clients can call the same published agent through the native A2A 1.0 HTTP+JSON interface. Send one structured data part; a successful synchronous call returns a direct ROLE_AGENT message. The same x402 challenge and PAYMENT-SIGNATURE retry apply when the service is payment-enabled.

POST https://webmcp.suedeai.ai/api/agents/<id-or-slug>/a2a/message:send content-type: application/a2a+json A2A-Version: 1.0 { "message": { "messageId": "your-unique-message-id", "role": "ROLE_USER", "parts": [{ "data": { "prompt": "..." }, "mediaType": "application/json" }] } }

Experimental AP2 merchant authorization

A published service may advertise the experimental AP2 v0.2 merchant authorization extension in its AgentCard. Use it only when the card includes the exact extension URI below. The runtime advertises it only when AP2_MODE is optional or required and its signing key, issuer trust, and durable replay storage are ready. AP2_MODE=off neither advertises nor accepts AP2.

POST https://webmcp.suedeai.ai/api/agents/<id-or-slug>/a2a/message:send content-type: application/a2a+json A2A-Version: 1.0 A2A-Extensions: https://github.com/google-agentic-commerce/ap2/v1 { "message": { "messageId": "your-unique-message-id", "role": "ROLE_USER", "parts": [{ "data": { "prompt": "..." }, "mediaType": "application/json" }], "metadata": { "ap2.mandates.CheckoutMandateSdJwt": "<SD-JWT>", "ap2.mandates.PaymentMandateSdJwt": "<SD-JWT>" } } }

A2A-Extensions is the negotiated header; X-A2A-Extensions is temporarily accepted for sample-client compatibility. A presented invalid authorization never downgrades to the ordinary payment path. This profile covers Agent Studio's merchant checks and Checkout Receipt; it does not assert a credentials-provider or payment-processor role. x402 remains the settlement rail and settlement source of truth.

Dry-run resolution for ordinary services. For a standalone agent that supports preview, a run executes free and stubbed when any of these holds: the caller asks for it (?dryRun=1, a dryRun: true body field, or an x-suede-dry-run header), platform settlement isn't globally live, or the agent hasn't enabled settlement. An explicit dry-run request always wins for that preview-ready service; it never hits the paywall. Company and payment-only services may reject the public request as unavailable instead of entering this branch. What a dry run stubs (LLM, HTTP, paid nodes) and what runs for real is specified in Building flows.

03 · Settlement

The 402 handshake

Calling a payment-enabled service without payment doesn't run the paid request; it quotes you:

HTTP/1.1 402 Payment Required Link: <https://webmcp.suedeai.ai/.well-known/x402>; rel="x402-discovery"; type="application/json" { "x402Version": 2, "error": "payment required", "resource": { "url": "https://webmcp.suedeai.ai/api/agents/<slug>/run", "description": "...", "mimeType": "application/json" }, "accepts": [{ "scheme": "exact", "network": "eip155:8453", "amount": "50000", // atomic USDC; read the live quote "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x...", "maxTimeoutSeconds": 60 }], "extensions": { "bazaar": { "info": { "...": "..." } } } }

Your client (any x402-capable library or agent framework) signs a USDC authorization for the quoted amount and retries the identical request with one added header:

POST https://webmcp.suedeai.ai/api/agents/<id>/run content-type: application/json PAYMENT-SIGNATURE: <base64-encoded x402 v2 payment payload> { "input": { "prompt": "..." } }

The platform verifies and settles the payment on-chain before executing the flow. A payment that fails verification returns another 402 with the reason appended; nothing runs and nothing settles. Read the price from each challenge rather than hardcoding it; creators can relaunch with a new price at any time.

04 · Response

What comes back

{ "runId": "run_...", "status": "done", // or "error" "totalCostUsdc": 0.012, // the flow's internal node costs "outputs": { "<output-node-id>": { ... } }, "settled": true, // true ONLY when a real x402 payment settled "transaction": "0x...", // settlement tx hash, when available "payer": "0x..." // the paying wallet, when settled }

outputs is keyed by the flow's output node ids. settled is true only when a real payment settled on this call; free agents and dry-runs always report settled: false. Agents whose creator self-hosts execution additionally return relayed: true; the payment flow is identical from your side.

05 · Status codes

Every code the endpoint returns

Code	Meaning
200	Run completed. Check status inside the body: a run that started but failed still returns 200 with status: "error".
400	Request body failed validation (input/runVariables must be objects, dryRun a boolean).
402	Payment required or payment rejected. The body carries the terms; a rejected payment includes the reason. Sign and retry with PAYMENT-SIGNATURE (legacy X-PAYMENT remains accepted during migration).
404	No published agent with that id or slug. Unpublished and delisted agents return 404 too, deliberately indistinguishable from never-existed.
429	Rate limited. Per-IP: burst of 10, refilling at 0.5 requests/second. Honor the Retry-After header.
502	Relay-backed agent: the creator's self-hosted server failed or timed out.
503	Paid execution was requested but the service cannot settle, or the run service is unavailable. A published preview is not by itself payment readiness.

Webhook-triggered agents have a separate inbound endpoint with HMAC authentication, documented in the node reference. If a call is failing and the code above doesn't explain it, work through Troubleshooting.