FiatDock Marketplace API

openapi: 3.2.0
info:
  title: FiatDock Marketplace API
  version: 1.16.1
  contact:
    name: FiatDock
    email: osama@fiatdock.com
    url: https://fiatdock.com
  description: 'A marketplace where AI agents discover and pay each other per call in USDC over x402 — settlement goes DIRECTLY to the seller, non-custodial, no accounts and no API keys. POST /s/{id} invokes any listed MCP service at that seller''s own price; GET /v1/marketplace/services is the catalog. Also first-party: free token prices, on-chain Base reads (gas, blocks, ETH/USDC balances, tx status, token metadata), token-safety and address-risk screening, and a non-custodial USDC on/off-ramp (x402 + a licensed payment partner). COMPLIANCE (binding, ramp only): 18+ only; served worldwide via our licensed provider across ~160 countries (EUR/SEPA in the EU/EEA incl. Portugal, card elsewhere; NOT the UK, US persons, or sanctioned countries); own-account rule — the sending wallet and the receiving bank account must belong to the same person (the agent''s owner), no third-party funds, no aggregation, no P2P transfers. Crypto is volatile; quotes indicative; nothing here is investment advice. RETRIES: GET endpoints are idempotent — repeat freely. Session POSTs are NOT idempotent (each success creates a new order and costs the x402 fee), but any non-2xx means nothing was created or charged, and an unanswered request at worst leaves an unused checkout link that expires in ~2 hours — no funds move until the human owner completes checkout. Pass the same customerId on retries and check /v1/customers/{customerId}/orders for duplicates. On 429, sleep Retry-After seconds.'
  termsOfService: https://fiatdock.com/terms.html
  x-guidance: 'Start FREE: GET /v1/token/price?token=0x…&chain=base (no payment, no key) — for a contract address it also returns a `recommend` object handing you the exact paid token_safety call. Paid calls use x402 v2: send the request, read the base64-JSON PAYMENT-REQUIRED response header on the 402, sign, and retry with X-PAYMENT. Nothing is charged on a 402. Cheapest paid calls: POST /v1/stablecoin/intel and POST /v1/token/safety — both answer >=400 (and settle nothing) if the upstream data is unavailable, so you are never charged for a missing answer. Everything here is also exposed as MCP tools at https://fiatdock.com/mcp (Streamable HTTP) or `npx fiatdock-mcp` (stdio, pays automatically).'
  x-agent-rules:
    neverChargedFor:
    - A 402 — that is the price quote, not a charge. Retrying is always safe.
    - Any 4xx. A ramp body that names a real ramp field is validated BEFORE the paywall, so that typo costs nothing and needs no wallet.
    - A 5xx or an upstream failure on a paid data route — x402 settles only on <400.
    beforeYouPayAnything:
    - GET /v1/quote?side=SELL&cryptoAmount=100 (or side=BUY&fiatAmount=100) is FREE and returns the real net amount.
    - 'POST the session body with no payment header. A 400 means fix the body. A 402 does NOT by itself mean the body is valid — the free check runs only when the body names a ramp field (cryptoAmount, fiatAmount, fiatCurrency, network, walletAddress, …); otherwise read `requestProblem` in the 402 body: present = still invalid, absent = you may sign.'
    inputWeAccept:
      amounts: Numbers or strings. "100,50", "1.234,56", "1,234.56", "١٠٠", "€100" are all understood.
      walletAddress: 0x + 40 hex. A bare 40-hex string (no 0x) and surrounding whitespace are accepted.
      fiatCurrency: 'ISO code, any case. "eur", "€", "euro" → EUR. 18 supported: AUD CAD CHF CZK DKK EUR GBP HKD HUF JPY MXN NOK NZD PLN SEK SGD USD ZAR.'
      network: base | ethereum | polygon | arbitrum | optimism | avalanche | bsc. Chain ids (8453, eip155:8453) and short forms (eth, arb, op, avax, bnb) also work.
      side: Exactly "SELL" or "BUY". Anything else is a 400 — we will not guess, because guessing the direction would price the opposite trade.
    knownLimits:
      offRampMinimum: The provider's floor is CHF 50 equivalent (~54 EUR). A smaller SELL quote answers 400 with the exact `minimum` — size up and retry.
      orderStatus: Orders stay SESSION_CREATED. The current provider sends no status webhook, so `callbackUrl` receives no push — poll GET /v1/orders/{id} and expect it to be static for now.
      checkoutTtl: checkoutUrl is valid ~2 hours. Forward it to the human owner promptly.
      humanStep: Session creation is fully automatable; the fiat transfer is not. A human gives the provider a phone number and email (identity documents only above ~CHF 999 per 30 days) and confirms the transfer.
    ifSomethingLooksWrong: 'Every 4xx carries a `hint` with the exact fix — read it before retrying. Live health: GET https://fiatdock.com/status. If a paid call fails after settlement the response names the settled transactions and says whether retrying is safe.'
servers:
- url: https://fiatdock.com
tags:


# --- truncated at 32 KB (61 KB total) ---
# Full source: https://artifacts.apis.io/fiatdock-com/openapi/fiatdock-com-marketplace-api-openapi.yml