Documentation
The full integration reference. AI agents usually prefer llms.txt or OpenAPI — this page is for human developers.
Payment: the x402 protocol
No API keys, no accounts. Paid requests return 402 with complete payment requirements (amount, address, network) — your client signs a $0.05 USDC payment and retries with the X-PAYMENT header. The x402-fetch library, our SDK and the MCP tools all handle this automatically.
Endpoints
Instant quote with an itemised fee breakdown. ?side=SELL&cryptoAmount=50 or ?side=BUY&fiatAmount=100, plus optional fiatCurrency, network, paymentMethod. Identical quotes are cached for 10s (X-Cache: HIT|MISS).
Sell the agent's USDC → the owner's own bank account. Body: cryptoAmount*, fiatCurrency, network, email, customerId, callbackUrl, ref. Returns checkoutUrl (valid ~5 minutes, single use) and partnerOrderId — and on the first session with a customerId, a one-time customerKey: store it.
The owner's own fiat → USDC to the agent's wallet (address locked). Body: fiatAmount*, walletAddress* + the same optional fields.
Order status: SESSION_CREATED → … → COMPLETED | FAILED. Includes partnerFeeInLocalCurrency and the ref code if one was set.
The customer's most recent 200 orders. Requires the X-Customer-Key header (the key returned once on the first session).
Push notifications (callbackUrl)
Pass a callbackUrl when creating a session and we POST on every status change, signed with X-FiatDock-Signature: sha256=HMAC(body, callbackSecret) — the callbackSecret is returned once in the session-creation response. Verify the signature before trusting any push. https is mandatory in production.
Integration — pick your path
- MCP (best for AI agents): run
npx fiatdock-mcpwithFIATDOCK_URLandAGENT_PRIVATE_KEY— seven ready tools with automatic payment (four ramp:get_quote,create_offramp_session,create_onramp_session,get_order_status; three marketplace:search_services,get_service,call_service). Remote, no-install:POST https://fiatdock.com/mcp(Streamable HTTP). - SDK:
sdk/fiatdock.js— quote/offramp/onramp/order/waitForCompletion. Examples in the examples folder. - Raw HTTP: any language — follow the 402 challenge.
Marketplace: beyond the cash-out ramp, FiatDock is an MCP-services marketplace — discover and call paid MCP services; the buyer pays the seller directly via x402 with a non-custodial 1% on-chain split (ADR-0006). Sellers create an account (email + password), set a public display name, pay the $20/mo Verified badge and complete KYC to earn trust and featured placement — see Sell.
The MCP package source, copy-paste configs for every client (docs/INTEGRATIONS.md) and SDK examples are open on GitHub: github.com/fiatdock/fiatdock · package: fiatdock-mcp on npm.
# A complete flow in three steps
curl "https://fiatdock.com/v1/quote?side=SELL&cryptoAmount=50" # 1) free quote
# 2) create the session (after x402 payment) -> checkoutUrl + partnerOrderId
# 3) track: curl "https://fiatdock.com/v1/orders/$ORDER_ID"Errors
Always JSON: {"error": "...", "hint": "the exact fix"}. Codes: 400 validation · 402 payment required · 404 unknown · 410 session expired · 413 body too large · 429 rate limited · 5xx internal.
KYC note
The human or company that owns the agent completes verification once, ever, at the licensed provider on first use — afterwards everything is near-automatic. Pass the same email and customerId on every session.
Compliance rules — they bind agents too
Own-account rule: the wallet sending crypto and the bank account receiving fiat must belong to the same person — the agent's owner. No third-party funds, no aggregating multiple users' transactions, no person-to-person transfers. Eligibility: 18+ only; not available in restricted jurisdictions (the restrictions reflect our licensed provider's coverage) — full list in the Terms, risks in the risk warning.
Guides
All guides · USDC to bank account API · How an AI agent cashes out crypto · x402 off-ramp explained · x402 explained · MCP payments server · Widget vs custodial exchanges