Calling a published agent
Any HTTP client can call any live agent: no account, no API key issued by Suede. Free and dry-run calls need nothing at all; priced live calls need a wallet that can sign a USDC payment on Base. This page is the complete caller-side reference.
Find agents and read their terms
Three machine-readable surfaces list what's for sale. The catalog is the friendly JSON feed; the .well-known/x402 documents follow the x402 discovery convention so agent frameworks can read payment terms without custom integration.
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.
Dry-run resolution. 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; it never hits the paywall, which is what makes integrate-first-pay-later possible. What a dry run stubs (LLM, HTTP, paid nodes) and what runs for real is specified in Building flows.
The 402 handshake
Calling a priced, live agent without payment doesn't error; it quotes you:
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:
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.
What comes back
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.
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 X-PAYMENT. |
| 404 | No live 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 | Agent is live but cannot serve: payouts not configured for a priced agent, or the run service is unavailable. |
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.