FiatDock S API

openapi: 3.2.0
info:
  title: FiatDock S 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:
- name: S
paths:
  /s/{id}:
    post:
      operationId: callService
      description: 'Paid gateway invoke (mirrors the call_service tool; alias of POST /v1/marketplace/services/{id}/invoke). NON-CUSTODIAL: the buyer makes DIRECT x402 payments — ONE leg — the full price straight to the seller (the gateway commission is currently waived). The 402 is authoritative on the leg count. Both legs are verified BEFORE the call is forwarded, and settle only once the seller has actually answered (ADR-0107) — a call that produces no answer returns 502 and settles nothing. A settled invoke returns X-FiatDock-Receipt, which is the only way to earn the right to review the listing.'
      parameters:
      - name: id
        in: path
        required: true
        example: svc_9d23b934-382d-4ce0-91ce-ee6be34c7cfc
        schema:
          type: string
          example: svc_9d23b934-382d-4ce0-91ce-ee6be34c7cfc
        description: 'A marketplace listing id. The example is a LIVE payable listing, resolved from the registry at request time — probe it to see the real 402. An unknown id is 404, not 402: the challenge names the seller''s own wallet as payTo, so it cannot be issued for a listing that does not exist.'
      - name: PAYMENT-SIGNATURE
        in: header
        required: false
        schema:
          type: string
        description: Base64 of the signed x402 v2 PaymentPayload for each entry in the 402's `accepts` — one payload as a plain JSON object (what every standard x402 client sends), or a JSON ARRAY of one per entry (ONE leg — the full price straight to the seller (the gateway commission is currently waived) — read `accepts.length`, do not assume). Omit it to receive the 402 and learn the price; send it to complete the call. The gateway verifies every leg and forwards the call, and settles ONLY once the seller has answered (ADR-0107) — a call that produces no answer returns 502 and settles nothing. Nothing is charged for a 402 either — it is the price, not a bill.
      - name: X-PAYMENT
        in: header
        required: false
        schema:
          type: string
        description: The x402 v1 spelling of PAYMENT-SIGNATURE, still accepted and translated server-side (ADR-0077/0078). Send ONE of the two, not both; PAYMENT-SIGNATURE is canonical and wins if both are present.
      requestBody:
        required: true
        content:
          application/json:
            example: {}
            schema:
              type: object
              description: forwarded verbatim to the seller's MCP endpoint
      responses:
        '200':
          description: the seller's response, plus X-FiatDock-Settlement (tx hashes), X-FiatDock-Fee-Bps and X-FiatDock-Receipt
        '402':
          description: x402 v2 Payment Required — `accepts` lists EVERY leg you must pay; PAYMENT-SIGNATURE (x402 v2; X-PAYMENT also accepted) is a base64 JSON ARRAY of one payload per leg. Nothing is charged on a 402.
        '403':
          description: listing suspended
        '409':
          description: not a paid gateway service (free/first-party — call its endpoint directly; or a stdio package — run it locally), or the seller has set no payout wallet so no payment can be routed
        '424':
          description: WITHDRAWN (ADR-0107) — the gateway no longer refuses any call. It used to turn away a listing whose last scan said it could not answer, because it settled BEFORE forwarding and the buyer would otherwise pay for the failure. It now settles only after the seller delivers, so every live listing answers a real 402 and a call that produces no answer returns 502 UNCHARGED. The same verdicts (`listing_tool_missing`, `listing_tool_unset`) still ride the catalog as `callable`/`callableReason` — advice for choosing a service, not a wall.
        '429':
          description: Rate limited (global 120/min/IP; stricter buckets on /mcp, webhook, auth). Sleep exactly Retry-After seconds, then retry.
          headers:
            Retry-After:
              schema:
                type: integer
              description: Seconds until the window resets — sleep this long, then retry
            RateLimit-Limit:
              schema:
                type: integer
              description: Requests allowed per window in this bucket
            RateLimit-Remaining:
              schema:
                type: integer
              description: Requests left in the current window (0 on 429)
            RateLimit-Reset:
              schema:
                type: integer
              description: Seconds until the window resets
        '502':
          description: 'the seller did not deliver an answer — you have NOT been charged (ADR-0107: nothing settles until the seller answers, and MCP reports failure at HTTP 200, so the body is read too). `reason` and `sellerSaid` name the cause; retrying is safe. RARE EXCEPTION: if the body carries a `settled` array, the legs really did settle before the failure and retrying re-issues the FULL price — do not blindly retry.'
      x-payment-info:
        price:
          mode: dynamic
          currency: USD
          min: '0.001000'
          max: '749.000000'
        protocols:
        - x402: {}
      tags:
      - S
      summary: Call service
      x-summary-source: derived
externalDocs:
  description: Agent skill file — what to run before acting on a token, an address or a counterparty (text/markdown, live prices and catalog)
  url: https://fiatdock.com/skill.md
x-payment-protocol:
  protocol: x402
  version: 2
  network: base
  asset: USDC
  payTo: '0xeB12bB2f52EeD33DBa6A00774E48324032Fd87C6'
  mode: per-call
  paid:
  - path: /v1/offramp/session
    method: POST
    priceUsd: 0.01
  - path: /v1/onramp/session
    method: POST
    priceUsd: 0.01
  - path: /v1/token/safety
    method: POST
    priceUsd: 0.0045
  - path: /v1/stablecoin/intel
    method: POST
    priceUsd: 0.002
  - path: /v1/chain/token-metadata
    method: POST
    priceUsd: 0.002
  - path: /v1/chain/gas-price
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/block
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/eth-balance
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/usdc-balance
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/tx-status
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/address-intel
    method: POST
    priceUsd: 0.0045
  - path: /v1/chain/token-report
    method: POST
    priceUsd: 0.0045
  - path: /v1/web/read
    method: POST
    priceUsd: 0.0018
  - path: /v1/email/check
    method: POST
    priceUsd: 0.001
  - path: /v1/market/perp
    method: POST
    priceUsd: 0.001
  - path: /v1/markets/prediction
    method: POST
    priceUsd: 0.0045
  - path: /v1/defi/yields
    method: POST
    priceUsd: 0.001
  - path: /v1/fx/rates
    method: POST
    priceUsd: 0.001
  - path: /v1/chain/portfolio
    method: POST
    priceUsd: 0.0045
  - path: /v1/token/holders
    method: POST
    priceUsd: 0.0027
  - path: /v1/domain/intel
    method: POST
    priceUsd: 0.0045
  - path: /v1/web/contacts
    method: POST
    priceUsd: 0.0027
  - path: /v1/news/crypto
    method: POST
    priceUsd: 0.001
  - path: /v1/sec/filings
    method: POST
    priceUsd: 0.0027
  - path: /v1/text/prompt-check
    method: POST
    priceUsd: 0.0045
  - path: /v1/token/screener
    method: POST
    priceUsd: 0.009
  - path: /v1/papers/search
    method: POST
    priceUsd: 0.009
  - path: /v1/geo/satellite
    method: POST
    priceUsd: 0.009
  - path: /v1/web/seo-audit
    method: POST
    priceUsd: 0.009
  - path: /v1/x402/top
    method: POST
    priceUsd: 0.009
  - path: /v1/chain/ens
    method: POST
    priceUsd: 0.0027
  - path: /v1/time/convert
    method: POST
    priceUsd: 0.001
  - path: /v1/calendar/holidays
    method: POST
    priceUsd: 0.001
  - path: /v1/weather/forecast
    method: POST
    priceUsd: 0.0018
  - path: /v1/wiki/summary
    method: POST
    priceUsd: 0.0018
  - path: /v1/news/hackernews
    method: POST
    priceUsd: 0.0027
  - path: /v1/feed/read
    method: POST
    priceUsd: 0.0022
  - path: /v1/dev/package
    method: POST
    priceUsd: 0.0027
  - path: /v1/sec/financials
    method: POST
    priceUsd: 0.0045
  - path: /v1/token/verdict
    method: POST
    priceUsd: 0.009
  - path: /v1/market/backtest
    method: POST
    priceUsd: 0.009
  - path: /s/{id}
    method: POST
    priceUsd: null
    note: per-listing price; the 402 is authoritative
  free:
  - /v1/quote
  - /v1/token/price
  - /v1/orders/{partnerOrderId}
  - /v1/marketplace/services
  - /v1/marketplace/services/{id}
  - /v1/marketplace/demand
  - /v1/x402/search
  relay:
  - path: /v1/x402/call
    method: POST
    priceUsd: null
    note: carries the caller's PAYMENT-SIGNATURE to an index-listed x402 endpoint; that endpoint's 402 is authoritative and its payTo receives the money — FiatDock charges nothing here