Pay-per-call (x402)

Orkid supports x402 pay-per-call alongside API keys. A caller with no account and no API key can pay a fixed USDC price per request over the Coinbase CDP Facilitator — the same 402 Payment Required flow used for autonomous agents.

Settlements happen on Base mainnet (eip155:8453) in USDC using the exact scheme (EIP-3009 transferWithAuthorization — gasless for the payer). All payments are attributed onchain via the ERC-8021 builder-code extension (a: "orkid") and indexed on the CDP Bazaar for agentic discovery.

Prices

API-key holders are not charged per call — the key path is unchanged (see Authentication). If X402_ENABLED is off, keyless requests behave as before: REST paid routes require a key, MCP paid tools require a key. There is no free tier exposure — if the facilitator is unreachable, paid endpoints fail closed (402, not a free result).

REST flow

POST /api/v1/quote           (no key, no payment)
  → 402 Payment Required
    accepts: [{ scheme: "exact", network: "eip155:8453",
                amount: "2000", asset: <Base USDC>, payTo: <treasury>,
                extensions: { bazaar: {...}, builder-code: { a: "orkid" } } }]

POST /api/v1/quote           (same request + X-PAYMENT header)
  → 200 + quote payload

The X-PAYMENT header carries the x402 payment payload — a signed EIP-3009 authorization against the payTo address for amount (atomic USDC units, 6 decimals). Settlement occurs after the response is produced; a failed upstream call does not charge the payer.

Client-side, use any x402-compatible wallet/fetch wrapper (x402-fetch, x402-axios, or an agent framework with x402 support). The accepts array advertises everything needed — scheme, network, asset, amount, destination.

MCP flow

Endpoint: https://orkidlabs.xyz/api/mcp (Streamable HTTP).

initialize, ping, tools/list, and the free tools are open. Paid tools follow the MCP x402 convention:

tools/call orkid_quote            (no payment)
  → PaymentRequired error carrying the same `accepts` requirements

tools/call orkid_quote            (with _meta["x402/payment"])
  → tool result + _meta["x402/payment-response"] { success, transaction, payer, network }

Send the signed payment payload under params._meta["x402/payment"]; the settlement receipt returns under result._meta["x402/payment-response"]. MCP-aware x402 clients (e.g. @x402/mcp) handle this automatically.

Discovery

• MCP Registry: xyz.orkidlabs/orkid-swap (remote-only, streamable-http).
• Static server card: https://orkidlabs.xyz/.well-known/mcp/server-card.json (SEP-1649) — tools, schemas, and auth modes without a live connection.
• Bazaar: every settled call reports bazaar extension responses; catalog indexing is automatic.

Notes for integrators

• USDC on Base only (6 decimals). amount in requirements is atomic units.
• Facilitator fee structure: first 1,000 onchain settles/month free to Orkid; per-call prices already account for settlement costs beyond that.
• The facilitator screens payers (KYT/OFAC) — sanctioned or high-risk payers are declined at verify time, before any work runs.
• Quote results are identical across keyed and paid paths; only the authorization mechanism differs.