# FiatDock — complete API walkthrough for AI agents
> Non-custodial USDC <-> bank. Conversion/KYC/custody by Transak (licensed provider). You pay $0.05 USDC per paid call via x402 on base-sepolia. Quotes/status/discovery are free.

## 0. Discovery & integration paths (pick ONE)
- GET https://fiatdock.com/             -> this service as a JSON manifest (agents get JSON, browsers get HTML)
- GET https://fiatdock.com/openapi.json  -> OpenAPI 3.1 (plain REST — works from any language)
- GET https://fiatdock.com/tools.json    -> the same 4 tools as ready-made function-calling declarations (OpenAI tools / Gemini functionDeclarations) mapped 1:1 to REST — for frameworks WITHOUT MCP
- MCP local:  npx fiatdock-mcp (stdio; env: FIATDOCK_URL, AGENT_PRIVATE_KEY for x402 auto-pay) — works in Claude Desktop/Code, Cursor, VS Code Copilot, Windsurf, Gemini CLI, OpenAI Agents SDK, LangChain (mcp adapters), CrewAI
- MCP remote: POST https://fiatdock.com/mcp (Streamable HTTP, stateless, CORS-enabled, protocol versions 2024-11-05..2025-11-25; paid tools return the 402 challenge — remote cannot sign payments)
Both MCP servers also expose 2 RESOURCES — fiatdock://fees (full fee schedule) and fiatdock://coverage (networks, service area, restricted jurisdictions, own-account rule) — and 1 PROMPT, cash-out-usdc, a guided compliance-first cash-out flow (args: amount, fiatCurrency).
- GET https://fiatdock.com/.well-known/agent-card.json -> A2A-format agent card (also at /.well-known/agent.json); /.well-known/mcp/server-card.json -> MCP server card
- GET https://fiatdock.com/status        -> service trust page: uptime, version, coarse upstream provider state (ok/limited/unreachable)
- Human-readable guides index: https://fiatdock.com/guides.html (6 articles: off-ramp API, agent cash-out, x402 explained x2, MCP server, widget vs custodial exchanges)
Per-client copy-paste configs (all of the above): docs/INTEGRATIONS.md in the GitHub repo (https://github.com/fiatdock/fiatdock) or the npm README (https://www.npmjs.com/package/fiatdock-mcp)

## 1. Quote (free, cached 10s — header X-Cache: HIT|MISS)
GET https://fiatdock.com/v1/quote?side=SELL&cryptoAmount=50
GET https://fiatdock.com/v1/quote?side=BUY&fiatAmount=100
Optional: fiatCurrency (default EUR), network (default base), paymentMethod.
Returns: rate, youSend, youReceive, totalFee, feeBreakdown[] (includes the 1% partner commission). Quotes are indicative.

## 2. Pay-per-call via x402
Call a paid endpoint without payment -> HTTP 402 with exact requirements (amount=$0.05 USDC, payTo address, network=base-sepolia).
Sign with your wallet and retry with the X-PAYMENT header. Libraries: x402-fetch (JS). The SDK and MCP tools do this automatically.

## 3. Create a session (paid, $0.05)
POST https://fiatdock.com/v1/offramp/session  {"cryptoAmount":50, "customerId":"agent-1", "email":"owner@mail.com", "callbackUrl":"https://your-agent.example/hooks", "ref":"optional-referral"}
POST https://fiatdock.com/v1/onramp/session   {"fiatAmount":100, "walletAddress":"0xAgentWallet", ...same optional fields}
Returns:
- partnerOrderId  -> track id
- checkoutUrl     -> branded page, valid ~5 minutes, SINGLE USE. Forward to your human owner. KYC happens once, ever, at the provider.
- customerKey     -> ONLY on the first session with a new customerId. Shown once — store it securely.
- callbackSecret  -> ONLY when callbackUrl is set. Shown once — used to verify our pushes.
On-ramp wallet address is locked: funds can only go to the wallet you specified.

## 4. Track the order
Poll:  GET https://fiatdock.com/v1/orders/{partnerOrderId}   (free) -> status: SESSION_CREATED -> ... -> COMPLETED | FAILED | CANCELLED | EXPIRED. Includes fiat/crypto amounts, partnerFeeInLocalCurrency, ref.
Push:  if you set callbackUrl we POST on every status change with header
       X-FiatDock-Signature: sha256=HMAC_SHA256(rawBody, callbackSecret)
       Verify before trusting (timing-safe compare). https callbacks only in production; private/internal hosts are rejected (SSRF guard).

## 5. Order history per customer
GET https://fiatdock.com/v1/customers/{customerId}/orders  with header X-Customer-Key: <customerKey from step 3>
Returns the customer's most recent 200 orders. 401 without the key.

## 6. Errors, limits & safe retries
Every 4xx is JSON {"error","hint"} — the hint is the exact fix; repair and retry.
Codes: 400 validation · 402 payment required · 404 unknown · 410 checkout expired · 413 body > 10kb · 429 rate limited (global 120/min/IP; stricter buckets on auth + webhook + /mcp).
503 activating: while the provider account completes activation, quote + session calls answer {"status":"activating","error":"Service is completing provider activation — launching very soon","retryAfterSeconds":3600} with a Retry-After header. Paid calls short-circuit BEFORE the 402 challenge — you are never charged for a guaranteed failure — and the normal 402 flow resumes automatically once the provider is active. Respect Retry-After or watch https://fiatdock.com/status.
Retries: GETs are idempotent — repeat freely. Session POSTs are NOT (each success = new order + $0.05 fee), but any non-2xx means nothing was created or charged, and a lost response at worst leaves an unused checkout link that expires in ~5 min — no funds move until the owner completes checkout. Use the same customerId on retries and check /v1/customers/{customerId}/orders for duplicates. 429 responses carry Retry-After + RateLimit-* headers — sleep exactly Retry-After seconds.

## 7. Compliance (binding — applies to agents exactly as to humans)
- 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 aggregation of multiple users, no person-to-person transfers.
- 18+ only. NOT available in restricted jurisdictions — the restrictions reflect our licensed provider's coverage; full annex at https://fiatdock.com/terms.html.
- Crypto is volatile; total loss is possible; nothing here is investment advice. Risk: https://fiatdock.com/risk.html