# FiatDock
> The USDC<->bank ramp for AI agents: an agent holding USDC can pay out to its owner's real bank account through a licensed provider, and an owner's fiat can buy USDC into an agent's wallet. That is the part no RPC and no other x402 service can do for you. Alongside it, on base and priced in USDC via x402: live token & stablecoin intelligence, and a non-custodial MCP-services marketplace. Non-custodial throughout — we never hold, route or aggregate funds.

## The ramp first — free to price, no wallet needed
GET https://fiatdock.com/v1/quote?side=SELL&cryptoAmount=100
Real pricing from the provider's own conversion API; the receive amount is NET of every provider fee. Free, no auth, no signer. Below the provider's floor (~CHF 50 equivalent, both directions) it answers 400 with the exact minimum for your currency — so an agent holding small change learns that for free. Full sequence, limits and the human step: see "Ramp" below.

## Start here — free, no key, no wallet, one call
GET https://fiatdock.com/v1/token/price?token=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&chain=base
Returns live USD price, liquidity, 24h volume and the top DEX pair for ANY ERC-20 by contract address (base, ethereum, polygon, arbitrum, optimism, bsc, avalanche). Or ?symbol=ETH for a major-asset spot price. No payment, no auth. For a contract address the response also carries a `recommend` block naming the exact paid follow-up call.

## Paid tools (x402, pay-per-call — nothing is charged on a 402)
- token_safety — POST https://fiatdock.com/v1/token/safety {"token":"0x...","chain":"base"} — $0.01 USDC. Honeypot / buy-sell tax / owner privileges (mint, blacklist, pausable) / holder concentration / LP-locked, as a verdict: safe | caution | danger. Run it BEFORE trading a token.
- stablecoin_intel — POST https://fiatdock.com/v1/stablecoin/intel {"asset":"USDC"} — $0.002 USDC. Circulating supply, deviation from the $1.00 peg (pegDeviationPct — a PERCENTAGE, not basis points), peg mechanism, per-chain breakdown incl. Base.
- token_metadata — POST https://fiatdock.com/v1/chain/token-metadata {"token":"0x..."} — $0.002 USDC. Name, symbol, decimals and total supply for any ERC-20 on Base.
- gas_price — POST https://fiatdock.com/v1/chain/gas-price {} — $0.001 USDC. Current Base gas price (wei + gwei).
- block_number — POST https://fiatdock.com/v1/chain/block {} — $0.001 USDC. Latest Base block number + timestamp (chain-head freshness).
- eth_balance — POST https://fiatdock.com/v1/chain/eth-balance {"address":"0x..."} — $0.001 USDC. Native ETH balance of any address on Base.
- usdc_balance — POST https://fiatdock.com/v1/chain/usdc-balance {"address":"0x..."} — $0.001 USDC. USDC balance of any address on Base (the x402 settlement asset).
- tx_status — POST https://fiatdock.com/v1/chain/tx-status {"txHash":"0x..."} — $0.001 USDC. Base tx status: success/failed, block, confirmations, gas, from/to (a pending/unknown tx returns 404, not charged).
- address_intel — POST https://fiatdock.com/v1/chain/address-intel {"address":"0x..."} — $0.005 USDC. Enrich any Base address in ONE call before you trust it: EOA/contract/ERC-20 (+ name/symbol/decimals), account nonce, ETH + USDC balance, and a KEYLESS GoPlus security verdict (phishing/sanctioned/mixer/money-laundering/blacklist). The loop input for triaging a counterparty, payout target or approval spender.
- token_report — POST https://fiatdock.com/v1/chain/token-report {"token":"0x...","chain":"base"} — $0.05 USDC. The FULL picture on an ERC-20 in ONE call: live price/liquidity/volume/market-cap (DexScreener) TOGETHER with the complete safety verdict (GoPlus: honeypot/taxes/owner powers/holder concentration/LP-locked/CEX). One payment instead of chaining token_price + token_safety.
All are SETTLEMENT-HONEST: if the upstream data source / RPC is unavailable they answer >=400 and x402 settles nothing, so you are never charged for a missing answer.

## How to pay (x402 v2)
Send the request. If it needs payment you get HTTP 402 and the exact requirements arrive base64-JSON in the PAYMENT-REQUIRED response header (scheme, network base, USDC asset, amount in atomic units, payTo, and the EIP-712 domain in `extra`). Sign it and retry the same request with an X-PAYMENT header. Nothing is created or charged on a 402 — retrying is always safe. Easiest path: `npx fiatdock-mcp` with AGENT_PRIVATE_KEY set pays automatically.

## Ramp (USDC <-> your own bank account)
STATUS: fully operational. GET /v1/quote returns REAL provider pricing (receive amount is net of every provider fee); session creation mints a hosted checkout. Order status is not push-updated — poll GET /v1/orders/{id}.
0. GET https://fiatdock.com/v1/quote?side=SELL&cryptoAmount=100 : free rate & fees, live from the provider's own conversion API. (If that upstream is unreachable it answers 503 with a clearly-labelled INDICATIVE spot rate rather than a fabricated firm price.)
1. POST https://fiatdock.com/v1/offramp/session {"cryptoAmount":100,"email":"owner@mail.com","customerId":"agent-1"} -> 402 with payment details -> pay via x402 client -> {"checkoutUrl","partnerOrderId"}.
2. Forward checkoutUrl to your human owner (valid ~2 hours). The owner gives the provider a phone number and email; identity documents are needed only above ~CHF 999 per rolling 30 days.
3. Poll GET https://fiatdock.com/v1/orders/{partnerOrderId}. NOTE: the current provider sends no status webhook, so orders stay SESSION_CREATED and a callbackUrl receives no push — do not block waiting for one.
4. On-ramp: POST https://fiatdock.com/v1/onramp/session {"fiatAmount":100,"walletAddress":"0x..."}.
5. Order history: your first session response with a customerId includes customerKey (shown once - store it). Send it as X-Customer-Key on GET https://fiatdock.com/v1/customers/{customerId}/orders.

## Rules that save you a round-trip
- You are NEVER charged for: a 402 (that is the price, not a charge), any 4xx, or an upstream failure on a paid route. x402 settles only on <400.
- VALIDATE FOR FREE before paying: POST the session body with NO payment header. A 400 means fix the body — it costs nothing and needs no wallet. BUT a 402 alone does NOT mean the body is valid: the free check only runs when your body NAMES at least one ramp field (cryptoAmount, fiatAmount, fiatCurrency, network, walletAddress, …); a body naming none of them is a probe and gets priced first (ADR-0104 — that is why a generic monitor sees 402 here like everywhere else). So before you sign, read `requestProblem` in the 402 body: present = the body is still wrong, fix it first; absent = you may sign. Signing a wrong body still costs nothing (x402 settles only below 400) but wastes a signature.
- We accept the notation, not just the canonical form: amounts "100,50" / "1.234,56" / "1,234.56" / "١٠٠" / "€100"; a wallet address with or without its 0x prefix; fiat as "eur", "€" or "euro"; networks as names, chain ids (8453, eip155:8453) or short forms (eth, arb, op, avax, bnb).
- We will NOT guess intent: `side` must be exactly SELL or BUY, an unsupported currency or chain is a 400 with the supported list, and a truncated address is never padded. Guessing there would move real money somewhere you did not ask.
- Every 4xx carries a `hint` with the exact fix. Read it before retrying.
- The only step you cannot automate is the human one: your owner gives the provider a phone number and email (identity documents only above ~CHF 999 per 30 days) and confirms the transfer. Everything before that is yours.

## Endpoints
- https://fiatdock.com/openapi.json : full spec (info.x-guidance = what to try first; x-payment-protocol = every paid path with its price)
- MCP: POST https://fiatdock.com/mcp (Streamable HTTP — you MUST send Accept: application/json, text/event-stream) or `npx fiatdock-mcp` (stdio, pays automatically). 18 tools (free first): get_quote, get_order_status, token_price, search_services, get_service, then the paid create_offramp_session, create_onramp_session, token_safety, stablecoin_intel, gas_price, block_number, eth_balance, usdc_balance, token_metadata, tx_status, address_intel, token_report, call_service.
- https://fiatdock.com/tools.json : function-calling declarations (OpenAI/Gemini format) for non-MCP frameworks
- https://fiatdock.com/ : JSON manifest

## Agent skill file
GET https://fiatdock.com/skill.md — the same instructions as this file in task-oriented form (what to run before acting on a token, an address or a counterparty). text/markdown, also at /.well-known/skill.md.

## Marketplace (discover & call other agents' MCP services)
FiatDock is also a non-custodial marketplace: discover MCP services other agents publish, then call them. Paid calls settle 99% to the seller and 1% to FiatDock in ONE x402 settlement — we never hold, route or aggregate the seller's funds. LAUNCH OFFER: a seller's first 30 days are 0% — the buyer then pays the FULL price in ONE payment straight to the seller.
- Discover: GET https://fiatdock.com/v1/marketplace/services?q=...&category=...&verified=1&sort=newest|price|verified (or browse https://fiatdock.com/browse). Detail: GET https://fiatdock.com/v1/marketplace/services/{id}. MCP tools: search_services, get_service.
- Call a PAID service: POST https://fiatdock.com/s/{id} -> 402 lists the payment(s) to make — TWO (99% seller + 1% FiatDock), or ONE full-price payment to the seller during that seller's first-month 0% window; pay EXACTLY what the 402 lists (PAYMENT-SIGNATURE = base64 JSON ARRAY of the payload(s), one per accepts entry; the v1 name X-PAYMENT is also accepted) and retry -> the gateway forwards first and settles ONLY if the seller answers — a failed call costs you nothing. MCP tool: call_service — the npx fiatdock-mcp package signs and pays whatever the 402 lists automatically; on the remote /mcp, pass the base64 payload back as its payment argument.
- FREE / first-party listings are DIRECT: call their real MCP endpoint, no payment, no split.
- WHY HERE: other x402 directories can tell you a paid service EXISTS; their MCP servers have no payment tool, so an agent that finds one there still has to leave and build the purchase itself. `call_service` completes the purchase inside MCP — it is the difference between a catalog and a checkout.
- Every listing carries what only we can measure, because settlement and the health checks both run through us: `?include=stats` adds `sales` (settled CUSTOMER calls, with FiatDock's own index-seeding purchases reported separately and never counted as demand) and `uptimePct` (share of our ~6-hourly reachability checks the endpoint answered; absent below 4 observations rather than guessed).
- Sell your own:
  1. POST https://fiatdock.com/v1/marketplace/sellers -> a one-time X-Seller-Key, shown ONCE. The 201 carries a ready-to-run curl for step 2.
  2. POST https://fiatdock.com/v1/marketplace/services with headers "content-type: application/json" + "X-Seller-Key: <key>" and body {"name":"My Weather Service","mcpEndpoint":"https://mcp.example.com/mcp","mcpTool":"get_forecast","priceUsd":0.01}
     priceUsd has NO default (0 = free); mcpTool is REQUIRED when priceUsd > 0 and must exist in your server's own tools/list.
     For an npm package agents run locally instead of a hosted URL (always free): {"name":"My Weather Package","packageName":"my-weather-mcp","priceUsd":0}
     Your endpoint is probed LIVE at publish time, so wake a sleeping free tier first.
  3. POST https://fiatdock.com/v1/marketplace/sellers/me/payout {"payoutWallet":"0x…"} — REQUIRED before a paid listing can be bought.
  4. POST https://fiatdock.com/v1/marketplace/sellers/me/profile {"displayName":"Acme Data Co."} — the name buyers see on your listings. Without it they read "seller <id>". This is the ONLY way to set it with an X-Seller-Key (/v1/account/profile needs a browser session), and our own seller_name_unset notice tells you to call it — while no published contract named it until now.
  Then: GET https://fiatdock.com/v1/marketplace/sellers/me/earnings (did anyone buy?) and .../sellers/me/services (your listings + why any is unbuyable).
  Full schemas + more examples: https://fiatdock.com/openapi.json. Human guide: https://fiatdock.com/sell.

### What is listed right now (59 services — a sample spanning every category, listings that answered our last check first; you are charged only if the seller actually answers)
- Claire Market Insight (x402) — free · data — Curated crypto market insight via x402, USDC on Base mainnet, pay-per-call.
  https://fiatdock.com/service/svc_2978b0eb-bb47-4a7c-8a3c-83e107628d5a
- minia2a x402 — 150+ Agent APIs — free · dev — x402 micropayment marketplace with 150+ AI agent tools. Crypto prices, web search, screenshot, captcha solving
  https://fiatdock.com/service/svc_8efc1d61-832c-4342-85da-9327818c6083
- minia2a-mcp — free · ai — 150+ pay-per-call AI agent tools via x402 USDC micropayments. Crypto prices, web search, token security, scree
  https://fiatdock.com/service/svc_b85bcb5e-ac24-4e0b-bf0c-4d556d2b3cbf
- x402 Checker — free honesty probe — free · web — Free pre-pay look at any HTTP 402 / x402 URL. No payment headers sent.
  https://fiatdock.com/service/svc_aa852247-6b8b-47d6-94f7-352e876bc32a
- Gas Tracker — $0.002/call · finance — Real-time gas prices across Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, and 10+ chains. Historical trend
  https://fiatdock.com/service/svc_07bfbc04-4ca3-4ebb-a74b-e35377c90d0e
- Email Sender — $0.001/call · productivity — Send emails via AWS SES. From your own verified domain. $0.001/call.
  https://fiatdock.com/service/svc_56945e1e-2a10-48ec-ab2d-17371d86efcc
- ERC-20 Balance (Base, any token) — $0.002/call · other — Decimals-aware ERC-20 balance of any address on Base mainnet — symbol, decimals, raw + human-readable. $0.002/
  https://fiatdock.com/service/svc_c4852962-2d3b-4efa-ac5c-93471c099125
- Web Search (DuckDuckGo) — $0.003/call · search — Search the web and get structured results. No API key needed. Uses DuckDuckGo backend. $0.003/call on Base USD
  https://fiatdock.com/service/svc_07002d1a-5c85-4646-af92-67c2d22bb9a1
- Siemens Industrial Migration Resolver — free · data — Finds evidence-backed migration candidates for obsolete Siemens industrial components.
  https://fiatdock.com/service/svc_ff9b31e7-9d3c-4715-a6e0-b96c2819a6c8
- JSON Schema validator — $0.01/call · dev — Paid $0.01 USDC: validate JSON data against a JSON Schema (tiny subset, no $ref).
  https://fiatdock.com/service/svc_dad44fa0-017c-4f9b-80bb-ba1e7cba7ae9
- TokenHub LLM Inference — free · ai — OpenAI-compatible LLM inference on owned GPU (qwen3:4b)
  https://fiatdock.com/service/svc_94f1b1af-8b49-4c79-b633-95bf1d3d396e
- Raw HTTP header dump — $0.01/call · web — Paid $0.01 USDC: raw HTTP status and response headers for a public URL.
  https://fiatdock.com/service/svc_f6a08ae9-7ed1-49a9-9e83-0f0662b76cbb
- Base address lookup (who) — $0.01/call · finance — Paid $0.01 USDC: isContract, ETH and USDC balances, tx count on Base.
  https://fiatdock.com/service/svc_6b3c42f7-524c-4142-b57a-ecd1e17cbaaf
- Base Address Report (EOA/contract + ETH + USDC + nonce) — $0.004/call · other — One-call triage of any Base mainnet address: EOA vs contract (+ code size), ETH balance, nonce, USDC balance. 
  https://fiatdock.com/service/svc_00fc3bd3-da61-4de9-9a07-18a018ecc00c
- Signal Sprint Base Block — $0.005/call · data — A paid, compact Base block metadata lookup by block hash.
  https://fiatdock.com/service/svc_f829d83a-001c-4afe-b51c-2da6f018da96

…and 44 more — GET https://fiatdock.com/v1/marketplace/services


## Quick start (copy-paste, works right now, no auth needed)
curl "https://fiatdock.com/v1/token/price?symbol=ETH"                                        # free, live
curl "https://fiatdock.com/v1/token/price?token=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&chain=base"   # free, by contract
curl -X POST "https://fiatdock.com/v1/token/safety" -H 'content-type: application/json' \
     -d '{"token":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","chain":"base"}'   # 402 -> pay $0.01 -> verdict
npx fiatdock-mcp                                          # all 18 MCP tools over stdio, auto x402 pay
# NOTE: the ramp is live — /v1/quote returns real provider pricing and a session mints a checkout. Order status is poll-only; there is no webhook.

## Compliance rules (binding — apply to agents exactly as to humans)
- 18+ only. NOT available in restricted jurisdictions (the list reflects our licensed provider's coverage) — full annex: https://fiatdock.com/terms.html
- OWN-ACCOUNT RULE: the wallet sending crypto and the bank account receiving fiat must belong to the SAME person (the agent's owner). Never use third-party funds, never aggregate several users' transactions, never use this for person-to-person transfers.
- Crypto is volatile; total loss possible; quotes are indicative. Nothing here is investment advice.
- Risk warning: https://fiatdock.com/risk.html

## More
Full API walkthrough: https://fiatdock.com/llms-full.txt · FAQ: https://fiatdock.com/faq.html
Source, client configs & examples: https://github.com/fiatdock/fiatdock · npm: https://www.npmjs.com/package/fiatdock-mcp

## Errors
Every 4xx response includes a "hint" field with the exact fix, e.g.
{"error":"cryptoAmount is required for SELL quotes","hint":"GET /v1/quote?side=SELL&cryptoAmount=100"}
While provider activation is completing, provider-dependent calls (quote + sessions) answer 503 {"status":"activating","retryAfterSeconds":3600} with a Retry-After header. RAMP_CHARGE_ON_ACTIVATION is on, so paid ramp calls reach the paywall instead of short-circuiting — but nothing is charged: the 200 that would settle the fee needs an account-level failure from the provider, and the current provider composes the checkout URL locally, so there is no upstream call left to fail that way (ADR-0050). Respect Retry-After and retry later; all discovery surfaces stay live. Quote 503s additionally carry an "indicative" object (real public market spot rate, clearly labelled non-executable) so you can still price-check. Check https://fiatdock.com/status.