Home › Guides › The x402 off-ramp

The x402 off-ramp, explained

x402 revives HTTP status code 402 (Payment Required) as a machine-payable challenge: instead of API keys and billing dashboards, the server quotes an exact on-chain price in the response and the client pays it in-band. FiatDock uses it to price the off-ramp at $0.01 USDC per session — no signup, no subscription, no monthly minimum. The conversion has its own floor, set by the licensed provider: roughly the CHF 50 equivalent, enforced on both buy and sell. A below-floor amount is refused with the exact per-currency minimum in the response — free on GET /v1/quote, and uncharged on a session, because x402 settles only below HTTP 400.

See the challenge yourself (live)

curl -X POST https://fiatdock.com/v1/offramp/session \
  -H "Content-Type: application/json" -d '{"cryptoAmount": 50}'

The response is 402 with an accepts array: the asset (USDC), the network (Base), the exact amount, and the payTo address. Nothing is hidden — the challenge is the price list.

Paying it from code (x402 v2)

npm i @x402/fetch @x402/evm viem

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const payFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:*", client: new ExactEvmScheme(privateKeyToAccount(KEY)) }],
});

const r = await payFetch("https://fiatdock.com/v1/offramp/session", { method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ cryptoAmount: 100, email: "owner@example.com" }) });

@x402/fetch reads the challenge out of the PAYMENT-REQUIRED header, signs the $0.01 transfer from the agent's wallet, and retries with the PAYMENT-SIGNATURE header automatically. The eip155:* wildcard means the client follows whichever EVM network the challenge names. The paid response carries a one-time checkoutUrl + partnerOrderId. Prefer tools over code? npx fiatdock-mcp does the same via MCP, and needs no wallet for the free tools.

Use the @x402/* scope. The unscoped x402-fetch, x402-express and x402 packages are the older v1 line: they emit a v1 payload and the v1 X-PAYMENT header. A funded wallet signing that shape gets refused here even though the money is real. FiatDock speaks x402 v2 — @x402/fetch, @x402/evm, @x402/core.

What the $0.01 buys

A session at a licensed payment partner where the actual conversion happens: USDC from the sender's wallet → provider → fiat in the owner's own bank account. FiatDock never custodies funds. Quotes (GET /v1/quote) and order status are free, so agents can compare before spending anything.

Why x402 fits agents

Agents can't fill signup forms or store card numbers. With x402 the only credential is the wallet the agent already has — payment, authentication and rate-limiting collapse into one signed transfer. Discovery is machine-readable too: llms.txt, OpenAPI, tools.json.

More guides: x402 explained (general) · USDC to bank account API · Widget vs custodial exchanges · All guides

Eligibility: 18+, own-account rule (sender wallet and receiving bank account belong to the same person), 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 restricted jurisdictions (see Terms). Crypto is volatile; nothing here is investment advice.