Skip to main content
Every Router payment follows the same five beats, whatever protocol the merchant speaks:
1

Probe

Someone requests the paid resource without payment. The merchant answers HTTP 402 with a payment challenge.
2

Detect

The Router reads the challenge and works out which protocol it is — an accepts array means x402, a WWW-Authenticate: Payment header means MPP.
3

Mint

The Router checks the spend against your Delegation, checks your wallet actually holds the funds, signs the payment from your custodial wallet, and reserves the amount — plus any routing fee — against the cap.
4

Pay

The credential goes to the merchant as an HTTP header. The merchant verifies it, settles, and returns the resource.
5

Record

The payment lands on your ledger with its settlement reference.
The only thing that changes between call modes is who performs steps 1 and 4 — you, or the Router. You hand the Router the request you want made. It probes, detects, mints, attaches, calls, and relays the answer. One call in, one answer out; you never see the 402 and never touch a credential.
status and body are the merchant’s, relayed unchanged. paid: false means the resource was free — the Router relayed it and there is no payment block.
requestId is required in mode B. Because the Router pays automatically, a retry after a dropped connection must not buy the same thing twice. At most one payment is minted per (caller, requestId); a duplicate returns 409 carrying the original paymentId instead of paying again. Use one stable id per logical purchase, not per HTTP attempt.

​
Streaming variant

For large or streamed responses, use ALL /api/v1/router/proxy instead. It’s the same engine, driven by headers rather than a JSON envelope, and the merchant’s response body streams straight back to you: Your method, body and headers pass through. Payment metadata comes back on the response: X-Router-Payment-Id, X-Router-Payment-Status (Issued / Settled / Failed), and X-Router-Tx-Hash. Use /route when you want one structured result; use /proxy when you want the bytes.

​
Mode A — you call the merchant yourself

Use mode A when your agent needs to make the upstream call itself — a client you don’t control, a transport the Router doesn’t proxy, or a request you want to shape by hand.
1

Probe the merchant yourself

Request the resource, get the 402, and keep the challenge exactly as it arrived — the accepts object for x402, or the raw WWW-Authenticate: Payment … header value for MPP.
2

Ask the Router for a credential

You get back a credential — { transport, name, value } — plus a settlement descriptor, a fee object, and a paymentId. The record is created Issued.
3

Attach it and re-request

Set the HTTP header named by credential.name to credential.value, and send your original request again. The merchant verifies, settles, and returns the resource.
4

Close the record

Report the settlement so the ledger entry completes:
Skip this and the record stays Issued — a valid state meaning “paid, settlement not yet observed”, not an error.
In mode A the Router only signs. It is not in the request path, so it cannot observe whether you ever redeemed the credential — which is why the ledger needs you to close the loop.
Prefer mode B unless you have a specific reason not to. It self-settles the ledger record, it’s one round trip instead of three, and it removes an entire class of “I minted a credential and forgot to use it” bugs.

​
Where custody sits

This is the part worth understanding properly, because it explains an error you will eventually hit. Both rails are pull-based. The credential the Router signs authorizes the merchant to take a specific amount from your own custodial wallet. Nevermined never holds your funds, never fronts them, and never moves them between users. Two independent things therefore have to be true for a payment to succeed:
  1. The Delegation authorizes the spend — enough cap remains and it hasn’t expired. Otherwise: 402 BCK.ROUTER.0003.
  2. The wallet actually holds the money — on the specific network and in the specific asset the merchant demanded.
A cap is permission, not funds. You can hold a $50 Delegation and still fail to buy something for a penny if your wallet is empty on that chain. What happens when you’re short differs by rail — and one 402 BCK.ROUTER.0009 covers two quite different things:
On x402 an underfunded wallet costs you budget. With no pre-check the Router signs and reserves your cap, the merchant’s transfer then fails on-chain, and the reserved merchant leg is not given back. Only a routing fee reserved on top can come back, and only on the closed list of paths that release one. Fund before you call; don’t rely on being stopped.

​
The routing fee

Nevermined charges a routing fee on each payment the Router makes for you. It’s quoted in basis points over the amount you’re paying the merchant — 100 basis points is 1% — and it’s disclosed on the payment response, alongside what the merchant charged.
The routing fee is 5% — 500 basis points — of the amount you pay the merchant. It is added on top, so a 1.00calldebitsyourDelegationcap1.00 call debits your Delegation cap 1.05 and the merchant still receives $1.00.The rate is resolved per payment and returned as fee.bps on every response, so read it from there rather than hard-coding it.
Three things are worth knowing about how a fee is applied. It’s a separate movement, not a bigger one. The credential the Router signs authorizes the merchant’s exact amount and nothing more — a fee never rides the merchant’s authorization, and a merchant is never paid more than it asked for. The fee is charged as its own movement. It’s reserved against your Delegation cap together with the merchant amount, as a single combined charge. So your cap headroom drains by merchant + fee, which is why the merchant amounts on your ledger won’t add up to the budget you’ve spent unless you count the fee too. fee.capChargedCents is the figure your cap was actually debited. The atomic fee rounds down; the cap charge rounds up. These are two different numbers, rounded in opposite directions, and conflating them will understate what a payment costs you:
  • fee.amount — the fee in the asset’s smallest unit — is rounded down, so a fee is never rounded up in Nevermined’s favour.
  • fee.capChargedCents — what your Delegation cap is debited — is a cents figure, and cents always round up.
How much that costs depends on what the rail can tell the Router about converting its asset to cents. When it can, the merchant amount and the fee are rounded up together, as one figure — so a sub-cent fee only costs you an extra cent when it tips the total across a cent boundary. When it can’t, the fee is rounded up on its own, and then any non-zero rate costs at least one whole cent of cap per payment — a 1-cent purchase at 2% is debited 2 cents. The one case that does not cost you a cent is a fee that truncates below a single atomic unit: it could never be transferred, so it is dropped outright rather than reserved, and you are charged the merchant amount alone. So don’t derive the cap charge from the amount and the rate. Read fee.capChargedCents — it’s the figure your budget actually moved by. Every mint response — POST /payments in mode A, POST /route in mode B — carries a fee object: settlement.approxCents remains the merchant leg throughout — it is not the whole cap charge. With no fee configured the two are equal. The streaming /proxy variant returns its payment metadata as response headers, and there is no fee header among them. For those calls, read the fee from the ledger record.

​
When a fee is not collected

A reserved fee isn’t always collected, and what happens to the reserve then differs by leg. The merchant leg is never given back. Once the credential is minted, the merchant may have taken the payment and then errored — so the reservation stands whatever the call did afterwards. The fee leg can come back — but only on a closed list of paths. A mode-B hop that never returned 2xx, a facilitator that adjudicated and refused, or a fee movement that couldn’t be signed: on each of those the fee’s cents are credited back to your Delegation cap and the ledger row reads feeStatus: "Released". Nothing else releases. A fee whose outcome is unknown stays Submitted and is resolved against the chain — and resolving is not releasing: a row the chain shows was never consumed becomes Failed with its reserve still charged. Read feeStatus for the credit; never infer it from a failure. Two preconditions decide whether the question is even asked, and both are easy to miss:
  • Only the x402 rail can collect a routing fee at all. MPP payments cannot produce a second settleable authorization, so they reserve the merchant leg alone.
  • Mode A collects only on calls that pass a requestId. Without one a retry cannot be deduplicated, so the fee is neither collected nor reserved (feeStatus: "None"). requestId is optional in mode A and required in mode B, so this is the common case rather than an edge one.
The mode then decides when the fee settles. Mode B settles it only after the merchant returns 2xx, so a hop that fails releases the fee. Mode A settles it at mint, before your credential is ever presented — so on mode A a wallet holding only the merchant’s price typically pays the fee and then loses the merchant leg on-chain, and there is nothing to release.

​
Fund for the amount plus the fee

Because the fee is its own movement, the merchant’s amount and the fee are two separate transfers pulled from the same wallet in the same asset. A wallet holding exactly the merchant’s quoted price does not cover both, and the two succeed or fail independently — one failing doesn’t roll the other back. So size your funding by amount + fee, not by the quoted price. On x402, where nothing checks your balance up front, that’s the difference between a shortfall being impossible and it being discovered after your budget is already committed.

​
How settlement gets recorded

When the merchant accepts the credential it returns a settlement reference — a PAYMENT-RESPONSE header on x402, a Payment-Receipt on MPP. In mode B the Router reads it and stores it on the record.
  • On success the record goes to Settled with the reference stored as txHash.
  • If the merchant paid but returned no usable reference, the record stays Issued — a normal state meaning “the hop succeeded, settlement is pending observation”. It is not an error and the Router will not fail an already-paid call over it.
  • If the merchant rejects the credential and returns another 402, the record is marked Failed.
The settlement reference is merchant-controlled and stored unverified. It’s bounded in length and character set, but the Router does not confirm on-chain that the referenced transaction exists or paid what it claims. Treat it as an anchor for reconciliation, not as proof of payment.

​
Next

Quickstart

Run the whole flow yourself.

Guardrails

Everything the Router checks before it signs.

Related topics

Nevermined CatalogHow the x402 Facilitator WorksOrganizations & WorkspacesMCP Point of SalesGet a Nevermined API Key