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.01 USDC payment and retries with the PAYMENT-SIGNATURE header. The @x402/fetch library, our SDK and the MCP tools all handle this automatically. FiatDock speaks x402 v2: install the @x402/* scope (@x402/fetch, @x402/evm) — the unscoped x402-fetch/x402-express/x402 packages are the older v1 line and sign a payload this API cannot read, so a funded wallet using them is refused.

Endpoints

GET /v1/quote free

Instant quote with an itemised fee breakdown. ?side=SELL&cryptoAmount=100 or ?side=BUY&fiatAmount=100, plus optional fiatCurrency, network, paymentMethod. Identical quotes are cached for 10s (X-Cache: HIT|MISS).

POST /v1/offramp/session

Sell the agent's USDC → the owner's own bank account. Body: cryptoAmount*, fiatCurrency, network, email, customerId, callbackUrl, ref. Returns checkoutUrl (valid ~2 hours) and partnerOrderId — and on the first session with a customerId, a one-time customerKey: store it.

POST /v1/onramp/session

The owner's own fiat → USDC to the agent's wallet (address locked). Body: fiatAmount*, walletAddress* + the same optional fields.

GET /v1/orders/{partnerOrderId} free

Order status: SESSION_CREATED → … → COMPLETED | FAILED. Includes partnerFeeInLocalCurrency and the ref code if one was set.

GET /v1/customers/{customerId}/orders free

The customer's most recent 200 orders. Requires the X-Customer-Key header (the key returned once on the first session).

Status updates (polling — no webhooks today)

Poll GET /v1/orders/{partnerOrderId} — polling is the only status channel. The current provider sends no order webhooks: a callbackUrl you pass is validated (https, SSRF-guarded) and stored for a future provider that supports pushes, but nothing is delivered to it now. Don't block waiting on a push.

Integration — pick your path

  1. MCP (best for AI agents): run npx fiatdock-mcp with FIATDOCK_URL and AGENT_PRIVATE_KEY — 18 ready tools with automatic payment (four ramp (get_quote, create_offramp_session, create_onramp_session, get_order_status); eleven crypto-data (token_price free, token_safety $0.01, stablecoin_intel $0.002, token_report $0.05, address_intel $0.005, and the Base chain reads gas_price, block_number, eth_balance, usdc_balance, tx_status, token_metadata from $0.001); three marketplace (search_services, get_service, call_service)). Remote, no-install: POST https://fiatdock.com/mcp (Streamable HTTP).
  2. SDK: sdk/fiatdock.js — quote/offramp/onramp/order/waitForCompletion. Examples in the examples folder.
  3. 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=100"   # 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 gives the licensed provider a phone number and email on first use (identity documents only above ~CHF 999 per 30 days) — 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.

Sell your MCP: host a stdio server to earn

List any MCP server on the marketplace. An npm (stdio) listing runs on the buyer's own machine (npx -y your-package), so it's free to discover — non-custodial means there's nothing in the request path to meter. To charge per call, host an HTTP version and list its https endpoint.

Wrap your stdio server as HTTP (no rewrite needed): npx -y mcp-proxy --port 8080 -- npx -y your-stdio-mcp or npx -y supergateway --stdio "npx -y your-stdio-mcp" --port 8080. Deploy it anywhere that gives a public https URL.

Then publish paid: on /sell/new paste your endpoint and press Test connection — we reach your server and list its tools; pick the tool agents should call. Set a price and a payout wallet. Agents call /s/:id; the gateway settles 99% directly to your wallet + 1% to FiatDock in one on-chain x402 payment (0% your first 30 days), then forwards to you — your raw endpoint stays private. Non-custodial throughout. Full guide: marketplace-hosting.md.

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