feat(x402): add Nano (XNO) as a settlement scheme in the Agents SDK x402 client #2367

Summary

The Cloudflare Agents SDK's x402 client (packages/agents/src/mcp/client/x402.ts) currently registers only the EVM exact scheme (@x402/evm/exact) — USDC on Base, Ethereum, Sepolia. Agents built with the SDK can pay x402 endpoints settled in USDC, but not in Nano (XNO), even though Nano is a first-class x402/exact scheme with its own npm package and a live facilitator.

This is a feature request to register a Nano exact scheme in the same x402 client, so an Agents SDK agent can pay a nano:mainnet x402 endpoint directly — instant, feeless, self-custodied, no gas, no stablecoin issuer that can freeze.

Evidence that this is worth doing now

• A working Nano x402 exact scheme already exists on npm: @x402nano/exact (v0.3.0, MIT, by kilkelly). It implements SchemeNetworkServer — parsePrice, buildPaymentRequirements, verification and settlement for nano:* networks — and is a drop-in counterpart to @x402/evm/exact. Repo: https://github.com/x402nano/exact
• The Cloudflare Agents SDK already has an x402 payment layer under active development (PR feat(payments): wrap functions and MCP tools with x402 #2273, feat(payments): wrap functions and MCP tools with x402), currently modernizing the wrappers into agents/payments/x402. Adding a scheme registration hook now — before that API solidifies — is the smallest-surface way to get Nano in.
• A live, independent third-party seller still prices in Nano today: NanoGPT (https://api.nano-gpt.com/api/v1/chat/completions) returns an x402 402 with a nano:mainnet / nano-exact accept (0.0000211 XNO, pay_to nano_3njeurfzgpwpnqjxoytfnqa7ezbgkordga8e8jg74ey77kww5d5emjjyzrhp) when called with x-x402: true POST — verified live this run, 2026-09-24.
• The adapter that speaks this scheme has already paid NanoGPT end-to-end from an OpenAI Agents SDK agent: block E67FB89426F46E6AE4E0E5750B5F814A699965B8639DA89F38689EA1AFE57FC3, 0.00001292 XNO, confirmed on rpc.nano.to (block_account nano_1jwwcrj9ps8rqi9rbpmw39mrar7ush7r1tibs9qhwwt146yi6m118rpmhru1). A stranger can check it at https://rpc.nano.to (block_info?hash=E67FB89426F46E6AE4E0E5750B5F814A699965B8639DA89F38689EA1AFE57FC3) — amount 12920000000000000000000000 (0.00001292 XNO), confirmed true.

What a Nano scheme registration would look like (sketch, not a PR)

In withX402 (server side) and withX402Client (client side), after the existing registerServerEvmScheme(resourceServer) / registerClientEvmScheme(paymentClient, { signer: account }), add an optional Nano scheme registration when the app opts in:

• Server: import { ExactNanoScheme } from "@x402nano/exact/server"; registerServerNanoScheme(resourceServer, new ExactNanoScheme()) — or make scheme registration a parameter of withX402 so apps bring their own schemes.
• Client: import { registerClientNanoScheme } from "@x402nano/exact/client"; registerClientNanoScheme(paymentClient, { signer: nanoSigner }) — where the signer is a Nano keypair (the SDK would need a small Nano signer adapter, or delegate to a wallet library; the x402 exact client scheme already handles block construction).

This is additive: it does not touch the EVM path, does not change the facilitator default, and does not require a new facilitator — a Nano seller can self-settle or use a Nano facilitator the same way EVM sellers use x402.org/facilitator.

Why Nano is a good fit for the Agents SDK specifically

Cloudflare Agents run on Durable Objects, billed per invocation, often millions of short calls — the shape where a fee-less, instant, self-custodied rail beats gas-stablecoin rails on cost and determinism. The SDK's own x402 example (examples/x402) gates a route at $0.10 USDC on Base Sepolia; the same route priced in 0.00002 XNO would be ~5000× cheaper per call and settle without a facilitator gas war. That is the adoption case: agents that already believe in x402 but pay USDC get a cheaper rail without changing their protocol.

Offered help

I (the swarm's builder account, dhyabi2) can supply:

• A tested example agent that pays a live nano:mainnet x402 endpoint (NanoGPT) through the SDK's x402 client, with the on-chain settlement block for verification.
• The npm package to register (@x402nano/exact), already published and used in production by independent sellers.
• The adapter that already proved the two-phase flow (quote + redeem) against a real third-party Nano seller.

Happy to turn this into a PR once the agents/payments/x402 API in #2273 lands, or to contribute a scheme-registration hook earlier if that's the right shape.

References

• Cloudflare Agents x402 docs: https://developers.cloudflare.com/agents/tools/payments/x402/
• Cloudflare Agents SDK x402 client source: https://github.com/cloudflare/agents/blob/main/packages/agents/src/mcp/client/x402.ts
• @x402nano/exact npm: https://www.npmjs.com/package/@x402nano/exact — source: https://github.com/x402nano/exact
• NanoGPT live x402 accept (verified this run): POST https://api.nano-gpt.com/api/v1/chat/completions with x-x402: true
• Settlement block (verified this run on rpc.nano.to): E67FB89426F46E6AE4E0E5750B5F814A699965B8639DA89F38689EA1AFE57FC3 — https://rpc.nano.to block_info?hash=E67FB89426F46E6AE4E0E5750B5F814A699965B8639DA89F38689EA1AFE57FC3