DEV Community: FiatDock

Migrating to x402 v2: what actually changed (and the traps nobody documents)

FiatDock — Fri, 12 Jun 2026 10:24:09 +0000

We run FiatDock — a non-custodial USDC ↔ bank on/off-ramp where AI agents pay $0.05 per call over x402. This week we migrated the whole stack (Express server, fetch client, MCP server) from x402 v1 to protocol v2. It took an evening, killed all 24 of our transitive npm vulnerabilities, and almost none of it was documented anywhere. Here is the map we wish we'd had.

1. v2 is not an upgrade — it's a different scope

The packages you're using (x402-express, x402-fetch, x402) are the v1 line and they stop at 1.2.0. There is no v2 of them. Protocol v2 lives under the @x402 scope:

npm rm x402-express x402-fetch
npm i @x402/express @x402/fetch @x402/evm @x402/core

@coinbase/x402 is a separate CDP-flavoured package — not the core.

Trap: @x402/express has an optional peer dependency on @x402/paywall. Do not install it unless you want the browser paywall UI — it pulls wagmi/walletconnect/solana, which is the exact dependency jungle (and the uuid/ws vulnerabilities) you're escaping by leaving v1.

2. The server side: resource server + scheme registration

v1's one-liner becomes explicit wiring — and you gain discovery metadata per route:

import { paymentMiddleware, x402ResourceServer } from "@x402/express";
import { ExactEvmScheme } from "@x402/evm/exact/server";
import { HTTPFacilitatorClient } from "@x402/core/server";

const facilitator = new HTTPFacilitatorClient({ url: "https://x402.org/facilitator" });
const server = new x402ResourceServer(facilitator)
  .register("eip155:84532", new ExactEvmScheme());

app.use(paymentMiddleware({
  "POST /v1/offramp/session": {
    accepts: { scheme: "exact", price: "$0.05", network: "eip155:84532", payTo: PAY_TO },
    description: "Sell agent USDC to fiat in the owner's bank account",
    mimeType: "application/json",
    serviceName: "FiatDock",
    tags: ["offramp", "usdc"],
  },
}, server));

Three things to notice:

Networks are CAIP-2 now. base-sepolia → eip155:84532, base → eip155:8453. Keep a friendly-name map if your env files say base-sepolia.
The facilitator URL did not change. https://x402.org/facilitator serves v2 (/supported, /verify, /settle) behind a 308 redirect. The facilitator.x402.org host you'll see in some READMEs does not resolve.
The middleware must sync supported kinds at startup (the last paymentMiddleware arg). Without it, even issuing a challenge fails with Facilitator does not support exact on eip155:84532. Your offline tests now need network access — plan for it.

3. The 402 challenge moved into a header

v1 put payment requirements in the JSON body. v2 402 responses have an empty body; the challenge is base64 JSON in the PAYMENT-REQUIRED header:

const challenge = JSON.parse(atob(res.headers.get("payment-required")));
// { x402Version: 2, resource: {...}, accepts: [{ scheme, network, amount, asset, payTo, ... }] }

If you surface 402s to agents (we decode them into MCP tool errors), update that path — your users will otherwise see {} and file confused issues.

4. The client side: schemes, not signers

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)) }],
});

The eip155:* wildcard means the client follows whatever EVM network the server's challenge names — our testnet→mainnet switch later requires zero client changes.

5. Free bonus: Bazaar discovery

v2 has a first-class discovery story. Register the extension and your paid routes get catalogued by the facilitator (which is what indexers like x402scan and the x402 Bazaar read):

import { bazaarResourceServerExtension, declareDiscoveryExtension } from "@x402/extensions";

server.registerExtension(bazaarResourceServerExtension);
// per route: extensions: declareDiscoveryExtension({ method: "POST", input: {...}, inputSchema: {...}, bodyType: "json", output: { example: {...} } })

This is also the v2 answer to the old outputSchema.output field scanners used to ask for.

6. Did it work?

We verified the full handshake against the real facilitator with an unfunded throwaway key: challenge → parse → sign → retry with X-PAYMENT → facilitator verify. The only rejection was invalid_exact_evm_insufficient_balance — i.e. the wire format was accepted end to end.

And npm audit: 24 moderate → 0, in both the server and our published MCP package (fiatdock-mcp).

FiatDock is machine-first: llms.txt · OpenAPI · MCP npx fiatdock-mcp · source mirror. If your agent earns USDC and you want it in a bank account, that's literally our whole product.

How my AI agent cashes out its USDC earnings to a bank account

FiatDock — Fri, 12 Jun 2026 02:03:42 +0000

My agent earns USDC. It sells API calls priced with x402, so tiny payments accumulate in its wallet. Which eventually raises the unglamorous question every "agents earning money" demo skips: how does that USDC become money a human can spend at a supermarket?

Here is the pattern I landed on. It needs no exchange account for the agent, no API keys, and — importantly — nobody in the middle ever holds the funds.

The constraint that shapes everything

Whatever converts crypto to fiat is regulated activity (KYC/AML, custody, payments). An autonomous agent can't and shouldn't do that part. So the design splits cleanly:

The agent handles quotes, session creation, payment of fees, and status tracking — all machine-to-machine.
A licensed provider (Transak, in this case) does the conversion, the KYC, and the custody.
The human owner confirms the final transfer once per session, and completes KYC exactly once, ever.

The service tying these together is FiatDock — a thin technology layer that never touches funds. One rule is binding and worth stating up front: the wallet sending USDC and the bank account receiving fiat must belong to the same person — the agent's owner. No third-party funds, no aggregation, no P2P.

Step 1 — the agent checks the rate (free)

curl "https://fiatdock.com/v1/quote?side=SELL&cryptoAmount=50"

No auth, no signup. The response itemises every fee (including the service's 1% commission) and the exact amount that lands in the bank account. My agent calls this before deciding whether cashing out now is worth it.

Step 2 — the agent pays for a session with x402

Paid endpoints don't use API keys. An unpaid request returns HTTP 402 with exact payment requirements — asset, network, amount ($0.05 USDC), and the address. The agent signs the payment from its own wallet and retries:

import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const payFetch = wrapFetchWithPayment(fetch, privateKeyToAccount(process.env.AGENT_PRIVATE_KEY));
const res = await payFetch("https://fiatdock.com/v1/offramp/session", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ cryptoAmount: 50, email: "owner@example.com", customerId: "agent-1" }),
});
const { checkoutUrl, partnerOrderId } = await res.json();

Payment, authentication, and rate-limiting collapse into one signed transfer. That's the whole x402 trick, and it's why this works for agents that can't fill out a signup form.

Step 3 — hand the human the link

checkoutUrl is single-use and valid about five minutes. My agent just messages it to me. I open it, the licensed provider runs KYC (first time only — afterwards it remembers), and I confirm. USDC goes from the wallet straight to the provider; EUR lands in my bank account. The agent never saw a bank credential, and FiatDock never held a cent.

Step 4 — the agent confirms completion

curl https://fiatdock.com/v1/orders/$ORDER_ID

Or pass a callbackUrl in step 2 and verify the X-FiatDock-Signature HMAC header on each push. Either way the agent knows when the money arrived and goes back to work.

The reverse direction — topping up the agent (on-ramp)

The same pattern works the other way when the agent needs working capital. POST /v1/onramp/session (also $0.05 via x402) creates a top-up session with the destination locked to the agent's own wallet address; the owner opens the checkout link, pays EUR from their own bank or card, and USDC lands in the agent's wallet. Quotes for this direction are the same free call with side=BUY:

curl "https://fiatdock.com/v1/quote?side=BUY&fiatAmount=100"

One flow out, one flow in — and the same binding rule in both directions: the fiat side is always the owner's own account, the crypto side is the owner's agent wallet. Nothing crosses between strangers.

If your agent speaks MCP, it's even shorter

The whole flow above is wrapped in four MCP tools (get_quote, create_offramp_session, create_onramp_session, get_order_status):

{
  "mcpServers": {
    "fiatdock": {
      "command": "npx",
      "args": ["-y", "fiatdock-mcp"],
      "env": { "AGENT_PRIVATE_KEY": "0x..." }
    }
  }
}

That config works as-is in Claude Desktop, Cursor, Windsurf, and Gemini CLI; there's a remote endpoint (https://fiatdock.com/mcp) for zero-install hosts, and a tools.json with OpenAI/Gemini function-calling schemas if you're not using MCP at all. It's in the official MCP Registry as com.fiatdock/fiatdock-mcp. Per-client configs live in INTEGRATIONS.md.

Honest limitations

Eligibility: 18+, Portugal + Transak-supported EU/EEA countries — not the UK or restricted jurisdictions (full list). The restrictions come from the licensed provider's coverage.
Quotes are indicative; crypto is volatile; none of this is investment advice.
The human stays in the loop by design. That's a feature, not a missing automation — it's what keeps the whole thing compliant.

Everything is documented machine-first if you want to point your own agent at it and let it figure things out: llms.txt · OpenAPI · repo.