Networks & facilitators

Change the network and configure a remote facilitator to use a public network; the gateway code and pipeline stay the same.payments.x402 and experimental payments.mpp share the facilitator model and mainnet guardrails. MPP accepts only eip155:31337, Base Sepolia and Base.

#Supported networks

Every built-in EVM network is supported: the signing code is the same on each, and on 2026-10-10 each network's USDC signing domain matched the chain and Permit2 and its x402 proxy were deployed. Every network also needs a facilitator that lists it, or health fails. NEAR has settled on testnet and mainnet only through the SDK facilitator the test suite runs, so it stays partial. Other tokens on built-in EVM networks also remain partial: the settlement test uses a local chain with a built-in network's id (see the settlement asset). Solana and NEAR specifics are in Configuration.

#Declared networks

Declare another EVM network with kind for mainnet guardrails, displayName and rpcUrl:

payments:
  x402:
    networks:
      eip155:10: { kind: mainnet, displayName: OP Mainnet }

A declared network has no default asset: supply the token's address, decimals and, for EIP-3009, its EIP-712 domain. Support is partial because the chain and token are operator-supplied. A built-in network cannot be redeclared; its entry may set rpcUrl only. Any other unknown id is CONFIG_INVALID at load: the chain id is part of the buyer's signed EIP-712 domain and must resolve explicitly.

#Deployment mode

local, testnet or mainnet comes from the network: eip155:31337 is local, and every other network is the testnet or mainnet it names. Offers on several networks must share one mode. The mode is reported by doctor, by the payment provider's health check, and at /.well-known/agent-commerce. In local mode the health check also requires the RPC to answer Anvil's anvil_nodeInfo, because an RPC can report any chain id.

#The facilitator

A facilitator verifies the buyer's authorization and broadcasts the transfer, paying gas on EVM, transaction fees through its Solana fee payer, or gas through its NEAR relayer. With remote, the gateway holds no facilitator signing key.

A config that still pairs the local facilitator with eip155:84532, the local chain's id before 2.1, is refused with a pointer to eip155:31337.

Omitting auth is the same as type: none. Any other type is refused at config load, and so is cdp with any other url, since it signs each request for CDP's.

A facilitator cannot redirect your money: the buyer's signature fixes the token, amount and recipient. What it can do is see every authorization you handle, delay or drop a broadcast until the authorization expires, and stop answering. The gateway accepts its reported success once it names the offer's network and a transaction in that family's form, without reading the chain.

In remote mode, health checks require the facilitator to list the scheme on every offer's network. One failing offer fails the x402 provider and /ready. With several offers, /.well-known/agent-commerce publishes each status anddoctor names the failing offers.

#Configuration by network

payments:
  x402:
    enabled: true
    network: ${X402_NETWORK:-eip155:31337}   # CAIP-2; the local chain
    rpcUrl: ${X402_RPC_URL:-http://127.0.0.1:8545}
    asset: ${X402_ASSET}                # ERC-20 with EIP-3009
    assetName: ${X402_ASSET_NAME}       # EIP-712 domain name
    assetVersion: ${X402_ASSET_VERSION}
    assetDecimals: ${X402_ASSET_DECIMALS}
    payTo: ${MERCHANT_WALLET}           # merchant-controlled. NEVER the gateway's.
    maxTimeoutSeconds: 120
    paymentFlow: authorization          # default; or upfront
    facilitator:
      mode: local                       # eip155:31337 only
      signerPrivateKey: ${X402_FACILITATOR_PRIVATE_KEY}

payments:
  x402:
    enabled: true
    network: eip155:84532
    rpcUrl: https://base-sepolia-rpc.publicnode.com   # health checks and reconcile
    payTo: ${MERCHANT_WALLET}           # no asset fields: the network's USDC
    maxTimeoutSeconds: 300
    facilitator:
      mode: remote
      url: https://x402.org/facilitator
      auth: { type: none }

payments:
  x402:
    enabled: true
    network: eip155:8453
    rpcUrl: ${X402_RPC_URL:-https://base.drpc.org}      # health checks and reconcile
    payTo: ${MERCHANT_WALLET}           # no asset fields: USDC on Base
    maxTimeoutSeconds: 600
    allowMainnet: ${ALLOW_X402_MAINNET}   # must resolve to true
    facilitator:
      mode: remote
      url: ${X402_FACILITATOR_URL}        # https only
      auth:
        type: bearer                      # or: cdp, with apiKeyId and apiKeySecret (needs @coinbase/x402 and CDP's url)
        token: ${X402_FACILITATOR_TOKEN}

Solana and NEAR take the same shape with their own network id and payTo. To accept several networks at once, see Several options.

#Mainnet guardrails

All of these are refused at config load, before the gateway starts:

A declared mainnet has no default asset to check. The same rules apply to any non-local deployment where they make sense: plain HTTP is allowed only to a local or private host, and a development payTo is refused on testnet too.

#Recorded settlements

Each of these moved 0.01 USDC from a buyer to a merchant through a remote facilitator:

Facilitators broadcast these payments and paid their ETH, SOL or NEAR fees. Permit2 needs a one-time, gas-paying token approval from the buyer. The NEAR runs used the suite's SDK facilitator and relayer, so NEAR support stays partial until a hosted facilitator settles. Buyer and merchant keys stayed outside the gateway.

#Smoke tests

npm run test:testnet spends test USDC and npm run test:mainnet real USDC on public x402 payments, then verifies settlement on chain. Run them by hand on the wallet holder's machine, never in CI, where funded keys would enter repository secrets. Without settings, both skip and list what each target needs.

Set X402_SMOKE_TARGETS to a comma-separated list for a release check: an unknown target or a missing setting fails before signing, so the check cannot pass by skipping. Without it, test:testnet runs the configured targets marked “runs unnamed” and test:mainnet runs nothing. Mainnet also needs ALLOW_X402_MAINNET=true. Each target pays X402_SMOKE_AMOUNT USDC once, 0.01 by default, and the suite refuses a payment above 1.00 on testnet or 0.10 on mainnet.

For each target, a run proves in order:

1. on mainnet, the same config without allowMainnet is refused;
2. discovery reports the target's network and mode without the facilitator's URL, and the provider's health check passes;
3. the buyer holds enough USDC, and the target's preparation is in place: a Permit2 approval, the merchant's Solana token account or the NEAR buyer's full-access key;
4. the SDK client pays once, and the gateway answers 200 with a successful PAYMENT-RESPONSE on the target's network;
5. the chain shows the transfer the settlement reported: the token's Transfer on EVM, the token balances of the confirmed Solana transaction, or the buyer's ft_transfer and the token's successful receipt on NEAR;
6. exactly one gateway receipt names the transaction;
7. the same payment presented again gets 402 or 409, and the backend is not called again;
8. nothing the gateway logged contains a key or a credential.

Balance changes alone cannot prove settlement; an unrelated transfer could explain them. Each settled target prints an evidence record, and X402_SMOKE_EVIDENCE_FILE appends them as JSON lines. The full settings table is in docs/smoke-tests.md.

#Worked configurations

• Base Sepolia, Base mainnet and Base mainnet (PayAI), which uses an unauthenticated facilitator;
• Arbitrum Sepolia, not yet run;
• Solana devnet and NEAR testnet;
• Multi-network mainnet: Base and Solana, which have settled, with Polygon and Arbitrum One, which have not run.