The x402 rail

x402 is the HTTP-native payment protocol where a server answers an unpaid request with HTTP 402 and an accepts array describing what it will take. The Router reads that array, picks an option it can fund, signs the payment from your custodial wallet, and hands back a credential. You don’t need the service to know anything about Nevermined. If it speaks x402, it’s payable.

What a challenge looks like

The Router supports both protocol versions and works out which one it’s talking to.

x402 v2
x402 v1

Requirements arrive base64-encoded in a PAYMENT-REQUIRED response header. The credential goes back in a PAYMENT-SIGNATURE request header.

Requirements arrive in the JSON body of the 402. The credential goes back in an X-PAYMENT request header.

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "base-sepolia",
      "maxAmountRequired": "1000",
      "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
      "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "maxTimeoutSeconds": 60,
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}

In mode B you never see any of this — the Router probes, negotiates the version, and pays. You only need the shape above if you’re using mode A and passing the challenge yourself as target.

What’s supported

	Supported
Scheme	`exact` — an EIP-3009 `TransferWithAuthorization`, a single-use signed authorization the merchant redeems
Networks	`base` (chain `8453`) and `base-sepolia` (chain `84532`), by name or as CAIP-2 (`eip155:8453`)
Assets	`USDC` and `EURC` — 6-decimal stablecoins

Anything outside that isn’t payable on this rail today: other schemes, other chains, and non-EVM networks such as Solana.

A mixed-chain 402 still works as long as one option is fundable. If a service advertises both a Solana option and a Base option, the Router skips the one it can’t parse and pays the Base one. It only fails if no entry survives the filter — that’s 400 BCK.ROUTER.0001.

How an option gets chosen

Given several fundable entries, the Router filters to scheme: "exact" on a funded network with a funded asset, then prefers USDC. The asset symbol is read from the entry’s extra.name field — a service that omits it won’t match the symbol filter even if its asset address is USDC.

Money and budget

Amounts are in the asset’s smallest unit. USDC and EURC have 6 decimals, so:

1_000_000 atomic units = 1 USDC = 100 cents
    10_000 atomic units = 1 cent

Your Delegation cap is denominated in cents, so every payment is converted and rounded up to the next whole cent before it’s checked against the cap. A payment of 5,000 atomic units (half a cent) reserves 1 cent. Sub-cent calls therefore cost you a full cent of budget each — worth knowing if you’re planning a long loop of very cheap calls. The settlement.approxCents field on every response tells you exactly what was reserved.

Funding your wallet

The payment is a pull: your signature authorizes the merchant to take the amount from your own wallet. So the wallet must already hold that asset on that chain before you call. Get the address from your Delegation’s providerPaymentMethodId — see step 3 of the quickstart. If it’s short, the mint fails with 402 BCK.ROUTER.0009 and nothing is signed: no credential, no reserved budget, no partial state to clean up. The asset to send is the one the service’s 402 advertises — USDC or EURC, 6 decimals, on the network in that entry. Base mainnet USDC is 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

base is Base mainnet and moves real funds; base-sepolia is the testnet. Which of them your deployment will fund is decided by the environment you are pointed at, not by the service. A sandbox deployment funds testnets only and a live deployment funds mainnet only — that split is the real-money firewall and an operator cannot widen it. If you call a mainnet service from sandbox, no entry survives the filter and you get 400 BCK.ROUTER.0001. Read settlement.network on the response to be sure what just happened.

Authorization lifetime

The signed authorization carries a validity window, capped by the operator (one hour by default) with a small allowance for clock skew between you and the merchant. A merchant asking for a longer window than the operator permits gets the operator’s cap, not its own request. In practice this only matters in mode A: if you mint a credential and sit on it, it can expire before you redeem it. The budget stays reserved and the record stays Issued. Mint credentials when you’re about to use them.

Settling the record

When the merchant accepts the credential it returns a settlement reference in a PAYMENT-RESPONSE (or X-PAYMENT-RESPONSE) header — the on-chain transaction hash.

Mode B reads it and closes the record for you: status Settled, hash on the ledger.
Mode A leaves the record Issued until you report it with POST /api/v1/router/payments/{paymentId}/settled.

See the ledger for what those statuses mean and how to reconcile them.

Operator configuration

These are set per deployment, not per call. You only need them if you run your own Nevermined deployment.

Env var	Default	Purpose
`ROUTER_FUNDED_NETWORKS`	derived from `ENVIRONMENT`	Networks the Router will fund a payment on. Sandbox derives the testnets, live derives mainnet; only a local/dev instance falls back to the permissive `base,base-sepolia`. On a deployed instance this variable can only narrow the derived set — it can never add a network, so it cannot move a box across the sandbox/live firewall. Setting it to an empty string is an explicit “fund nothing”, not “use the default”.
`ROUTER_FUNDED_SYMBOLS`	`USDC,EURC`	Asset symbols it will pay in
`ROUTER_PREFER_SYMBOL`	`USDC`	Which symbol wins when a 402 offers several
`ROUTER_MAX_AUTH_TTL_SECS`	`3600`	Ceiling on the signed authorization’s validity window

The MPP rail

The other supported protocol, and how it differs.

Guardrails

Every check the Router runs before it signs.

Learn

Build

Payments

Nevermined Router

Solutions

Organizations

Integrations

Payment Patterns

Components

Specs

What a challenge looks like

What’s supported

How an option gets chosen

Money and budget

Funding your wallet

Authorization lifetime

Settling the record

Operator configuration

Next

The MPP rail

Guardrails

​What a challenge looks like

​What’s supported

​How an option gets chosen

​Money and budget

​Funding your wallet

​Authorization lifetime

​Settling the record

​Operator configuration

​Next

The MPP rail

Guardrails

What a challenge looks like

What’s supported

How an option gets chosen

Money and budget

Funding your wallet

Authorization lifetime

Settling the record

Operator configuration

Next