Nevermined Router — buy from any x402 or MPP service

Skill version: 0.1.5 | Last updated: 2026-09-26 | Canonical source (always latest): https://github.com/nevermined-io/docs/tree/main/skills/nevermined-router

⚠️ Use the latest version. If you have a cached copy, check its Last updated date against the canonical source and refresh if older.

Human-readable twin of the Router documentation at https://nevermined.ai/docs/products/catalog/router/overview. Same facts, same error codes — if the two ever disagree, the docs site is authoritative and this skill has a bug.

What this is for

You are an agent that needs something from a service you have no account with, no API key for, and no billing relationship with. The Router lets you pay it per request, from a budget a human capped in advance, and puts every spend on one ledger.

It works because a growing set of services quote their price on the wire: you call them, they answer 402 Payment Required with what they want, you pay, you get the resource. The Router does the paying.

This skill cannot help you with conventional SaaS APIs. Exa, Firecrawl, Tavily and similar are billed out of band — a monthly plan, a long-lived key. They never quote a price for one call, so there is nothing on the wire for the Router to pay and no address to pay it to. The Router isn't missing a feature; the transaction it performs does not exist for those services. If a service answers 401 or 403 rather than 402, it wants authentication, not payment — stop, and tell the user it needs an account.

That is not a dead end, just a different rail. Nevermined can still buy from such a provider out of band — purchasing API credits up front instead of paying per call. Exa is the worked example: a $7 x402 card-delegation purchase provisions or tops up an Exa API key, fully agent-driven — https://nevermined.ai/docs/integrations/exa. That flow belongs to the nevermined-payments skill and the Payments SDK. What you cannot do is put those calls through /router/route.

The buy loop

Six steps. Steps 1–3 happen once; 4–6 repeat per purchase.

① API key  ──▶ ② Delegation (budget) ──▶ ③ Fund the buyer wallet
                                              │
                    ┌─────────────────────────┘
                    ▼
   ④ Discover a service ──▶ ⑤ POST /router/route ──▶ ⑥ Read the spend
      (catalog)                (pays + relays)          (ledger)

Set your environment once:

export NVM_API_URL="https://api.sandbox.nevermined.app"   # live: https://api.live.nevermined.app
export NVM_API_KEY="<your-api-key>"

Everything is plain HTTP with Authorization: Bearer $NVM_API_KEY. There is no SDK for the Router yet — that is deliberate here, because it means any agent in any language can drive it with an HTTP client. The one exception is the catalog, which is public and needs no key at all.

The two rails are enabled independently per deployment, and the MPP rail is not on everywhere. x402 (Base) is available by default. MPP (Tempo) requires the operator to allowlist the payment token for that chain, and the allowlist is fail-closed — where it is unset, every MPP service is refused with 400 BCK.ROUTER.0001 … not allowlisted, before anything is signed.

So a service being in the catalog does not mean your deployment can pay it. The catalog describes services; it says nothing about how the deployment you are pointed at is configured. If MPP services fail with 0001 … not allowlisted while x402 services pay fine, the rail is off where you are — that is a deployment setting, not something you can fix from the client, not a fault in the merchant, and not a reason to retry or to go looking for a different MPP service, which will fail identically. Ask the operator of your deployment, or stay on protocol=x402. See references/errors.md.

Never send NVM_API_KEY to the service you are paying. It authenticates you to Nevermined and nothing else. If a merchant needs its own auth, pass it in headers (mode B) — see references/paying.md.

① Get an API key — needs a human once

Issued from the Nevermined app. If you were given one, use it.

A key that predates the Router is refused with 403 BCK.ROUTER.0008. The fix is to create a new key; newly issued keys work. Old keys keep working for credit-based flows, so nothing else needs rotating.

② Create a Delegation — fully programmatic

A Delegation is the budget: a hard cap in cents plus an expiry, enforced server-side on every single payment. Create it once, reuse the id.

curl -sX POST "$NVM_API_URL/api/v1/delegation/create" \
  -H "Authorization: Bearer $NVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"erc4337","currency":"usdc","spendingLimitCents":500,"durationSecs":604800}'
# → { "delegationId": "5e7481c3-e972-45bd-bdc5-a0b99c4de4a1" }

That is a $5.00 cap for 7 days. provider: "erc4337" is the crypto-funded Delegation both stablecoin rails require — a card-funded Delegation is refused on them.

You may create a Delegation. You must never widen one to get past a refusal. The cap is the human's decision; a refusal is that decision taking effect. See Guardrails.

Two guards can refuse this call before your fields are read, and neither is retryable:

• 403 BCK.OAUTH.0030 — the key was minted through an OAuth consent ceremony (credits_purchase, account_access or commerce) and may not create Delegations or use the paying routes. Use a plain API key issued by the account owner — or, if the key comes from a commerce grant, spend through POST /api/v1/router/commerce/route (and price a call through POST /api/v1/router/commerce/quote), which derive the Delegation from the grant instead of taking one from you.
• 412 {"error":"consent_required","outdated":[…]} — the account's legal-document consent has lapsed. ⚠️ Its only code is the generic BCK.HTTP.412, which names the status and not the cause, so branch on body.error === "consent_required" — the one place "branch on code" needs a second field. A human must accept; report it and stop.

Full field list, recipient scoping, both guards in detail, and reading a Delegation's live state: references/bootstrap.md.

③ Fund the buyer wallet — may need a human

Both rails pull: the merchant takes funds from your own wallet. The Delegation authorizes the spend; it does not provide the money. Read the wallet address off the Delegation:

curl -s "$NVM_API_URL/api/v1/delegation/$NVM_DELEGATION_ID" \
  -H "Authorization: Bearer $NVM_API_KEY"
# → { "providerPaymentMethodId": "0x8F60b3838e6C121FcDBdBc50e7B150F8560a670E", ... }

providerPaymentMethodId is the address to fund, with the payment asset, on the network you intend to pay on.

Your deployment funds exactly one x402 network, fixed by its environment: sandbox → base-sepolia, live → base. A merchant on the other chain is unpayable from where you are and fails with 400 BCK.ROUTER.0001 … no fundable option, which reads like a broken service and is not. Check the environment before blaming the merchant — see references/bootstrap.md.

Always read this address back from the live Delegation — never from a value you cached. Funding a stale address is the most common cause of 402 BCK.ROUTER.0009, and the error deliberately does not echo the address it checked, so it cannot tell you that is what happened.

If the wallet is empty and you cannot fund it yourself, that is a stop condition: report it to the human. Do not retry.

④ Discover a service

The Agent Services Catalog is one public JSON feed — no API key, no query parameters. Fetch it and filter on your side:

curl -s https://nevermined.app/catalog/ai-catalog.json \
  | jq '[.services[] | select(.protocol == "x402" and .category == "Search & Research")
         | {slug, title, priceLabel, endpoints: [.endpoints[] | {method, path: (.invokePath // .path), description}]}]'

[
  {
    "slug": "superhighway",
    "title": "Superhighway — Web Search for Agents",
    "priceLabel": "$0.001",
    "endpoints": [
      { "method": "POST", "path": "/search", "description": "Web search" },
      { "method": "POST", "path": "/news",   "description": "Real-time news search" },
      { "method": "POST", "path": "/images", "description": "Image search" }
    ]
  }
]

(An excerpt: the real result lists every match.) /api/v1/catalog/services and /api/v1/catalog/categories are not a public API — they return 403 by design. For server-side search, the Catalog MCP (search_services, get_service, list_categories at https://mcp.live.nevermined.app/mcp) is free and needs no key.

Two rules that will otherwise cost you a wasted payment:

1. Only protocol of x402 or mpp is payable through the Router. Filter for them. Anything else in the catalog is listed for discovery, not for routing — see above.

2. Pay a listed service by its slug, never by URL. The feed carries no merchant URL on purpose: the Router resolves it server-side and refuses a raw-URL payment to a cataloged host (409 BCK.ROUTER.0014). The subpath to send is the endpoint's invokePath when present — even "", which means "append nothing" — and its path otherwise:

   const subpath = endpoint.invokePath ?? endpoint.path   // NOT `||`: '' must stay ''
   // edgar-search: path '/edgar-search/search', invokePath '' → send ''. Sending the path double-stacks it and 404s after the charge.
   

More filter recipes, categories, the Catalog MCP, and the ARD host document: references/discovery.md.

From API 1.55, server-side selection (POST /api/v1/router/select and MCP route_by_intent) accepts exact opaque catalog slugs in filters.require, filters.prefer and filters.exclude. require is the strict control: the Router selects that slug or fails closed with 409 BCK.ROUTER.0031; it never silently substitutes another service. prefer falls back to normal ranking when its slug is not payable, while exclude removes its slug from consideration.

⑤ Make the paid call

Hand the Router the request you want made. It probes the service, auto-detects the protocol from the 402, pays, and relays the answer — one call, and you never see the 402.

curl -sX POST "$NVM_API_URL/api/v1/router/route" \
  -H "Authorization: Bearer $NVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "delegationId": "'"$NVM_DELEGATION_ID"'",
    "slug": "superhighway",
    "path": "/search",
    "method": "POST",
    "body": { "query": "nevermined router" },
    "requestId": "search-nevermined-router-v1"
  }'

A cataloged service is addressed by slug + path (the endpoint's invokePath ?? path). Send an absolute url instead only for an off-catalog x402 / MPP service.

{
  "status": 200,
  "body": { "…": "the paid resource" },
  "paid": true,
  "payment": {
    "paymentId": "b1f9c2e4-…",
    "settlement": { "amount": "1000", "asset": "USDC", "network": "base", "approxCents": "1" },
    "fee": { "bps": 0, "amount": "0", "cents": "0", "capChargedCents": "1" },
    "txHash": "0xfc8af37b…",
    "status": "Settled"
  }
}

status and body are the merchant's own, unchanged. paid: false with no payment block means nothing was charged. For a catalog slug, the body of a free answer is withheld (null), except when you poll the result of an async job you already paid for through the same slug — including a wallet-authenticated (auth: "siwx") result, which the Router signs for with your own wallet: see "Async services" in references/paying.md.

settlement.approxCents is the merchant leg, not your bill. Nevermined charges a routing fee on top, disclosed in the always-present fee object (zeroed when no fee applied, so never branch on its absence): fee.capChargedCents is what this call reserved against your Delegation cap — settlement.approxCents + fee.cents. Sum capChargedCents, not approxCents, or your accounting drifts by exactly the fee.

⚠️ It is the reserve at mint, not the final figure: if a mode-B hop does not return 2xx the fee half is given back (the merchant leg stays charged), so a running total over-reports on those calls. GET /api/v1/delegation/{id} is the authority on what you have actually spent — reconcile against amountSpentCents rather than your own sum. Full field list: references/paying.md.

requestId is required, and it is an idempotency key — not a request counter. Use one stable id per logical purchase and reuse it across retries of that purchase. Retrying a dropped call with the same id returns 409 BCK.ROUTER.0002 carrying the original paymentId — not the resource — instead of buying twice; a fresh id buys twice, on purpose. Never answer that 409 by minting a fresh id: that is the double-spend the key just prevented. If the purchase genuinely failed, report it. Derive it from the work you are doing ("search-nevermined-router-v1"), not from uuid4() per HTTP attempt — a fresh UUID on every retry is how an agent double-spends.

From API version 1.48 (a key pinned at or above it — new keys are pinned to the current version), a slow service no longer holds your connection. If it has not answered within 45 s, /route answers 202 { paymentId, resultUrl, status: "Pending" } (/router/proxy · /router/svc: 202 with Location and X-Router-Payment-Id, and only before the service starts responding). The payment is made; the call keeps running on the Router (up to its 120 s ceiling) and its fee is collected on a 2xx or released otherwise, exactly as if you had waited. Poll GET $NVM_API_URL{resultUrl} with the same key: 202 while Pending, then 200 with state: "Ready" (status + body, as /route would have returned them) or state: "Failed" (failureReason), and 404 BCK.ROUTER.0030 once it has expired. Never pay again for a 202. Every paid result is kept for 24 h after the call ends, for the paying account only — a paid /route response carries it as payment.resultUrl — except a /proxy · /svc response that already streamed to you. A same-requestId retry returns that 202, then the retained result, instead of the 409 — on /proxy · /svc too, when the first call answered 202. It still gets the 409 when nothing was kept (a /proxy · /svc response that already streamed to you), when the first call Failed, or when the id was reused for a different target. Older keys keep waiting and get the 409, though their results are kept too. Either way, keep the same id.

Price it first: POST /api/v1/router/quote (deployments on API 1.48 or later). Send the same body as /route minus requestId, maxTotalCents and protocol, which are stripped rather than refused (delegationId stays optional). The Router makes the same unpaid request to the service that a payment would, selects the option a payment would select, prices it with the routing fee — and stops. Nothing is signed, minted, recorded or reserved. It answers 200 with paymentRequired, optionSet, protocol and the same settlement and fee objects /route returns. Then route with maxTotalCents set to the quote's fee.capChargedCents, so a price that rose in between is refused (402 BCK.ROUTER.0018) instead of paid.

From API 1.55, a payment-required quote also returns a short-lived opaque quoteId and expiresAt 60 seconds later. Pass that quoteId to /route with the exact quoted target, method, headers, body, credential header and Delegation. It pays the sealed merchant challenge at the exact fee-inclusive amount without accepting a changed call; keep maxTotalCents too as an independent ceiling. An invalid/wrong-account id is 0029, an expired id is 0032, and any request, Delegation, rail or amount mismatch is 0033 — all before a charge. Re-quote when the call changes or the id expires. Clients pinned below 1.55 receive no quoteId/expiresAt and retain the legacy re-probe-plus-ceiling flow.

• It is not free of side effects. The request really reaches the service, so a service that does not charge for it performs it — take care quoting a method with side effects. And a quote spends the same per-key and per-service rate budgets as a payment: quote once per decision, don't poll.
• fee.capChargedCents is whole cents rounded up from fee.capChargedMicros (exact, in 1/10,000 of a cent), and it is the figure maxTotalCents is compared against. The ceiling has whole-cent resolution, so any price up to that whole cent is still paid: a 2.04¢ quote paid with maxTotalCents: 3 accepts up to 3.00¢.
• optionSet: "delegation" means the delegationId you sent was priced (a card Delegation pays over MPP-stripe, an organization-wallet Delegation pays in its own currency, a recipient allowlist is enforced); "deployment" means you sent none, so this is what a personal crypto Delegation would select. paymentRequired: false means the service did not ask for payment; upstreamStatus is its answer, and its body is never returned.
• A quote checks neither your remaining cap nor your wallet balance — the payment still does. 503 BCK.ROUTER.0028 (a read the price depends on failed) is retryable with backoff.
• With an OAuth commerce credential, quote on POST /api/v1/router/commerce/quote instead (it ships in the first API release after 1.49; until your deployment has it, the route answers 404, so bound the price with maxTotalCents alone): same body and answer, but it prices the Delegation the grant is pinned to, so sending a delegationId is refused (400 BCK.OAUTH.0034). Then pay on /router/commerce/route.

Mode A (you call the merchant yourself), the streaming /proxy variant, and passing the merchant's own auth: references/paying.md.

⑥ Read what you spent

curl -s "$NVM_API_URL/api/v1/router/payments?delegationId=$NVM_DELEGATION_ID" \
  -H "Authorization: Bearer $NVM_API_KEY"

Every payment, every protocol, one ledger. Filters, CSV export, and the aggregate summary: references/ledger.md.

Guardrails — read this before writing a retry loop

The Router signs payments from your wallet in response to instructions written by a merchant nobody vetted. It is deliberately suspicious, and a refusal is the system working.

Four rules for an agent that spends without a human watching:

1. 402 BCK.ROUTER.0003 (over cap / expired) and 402 BCK.ROUTER.0009 (wallet short) are stop conditions. They mean "out of budget" and "out of money". Report them to the human. Do not route around them.
2. Never widen a Delegation, and never create a second one, in response to a refusal. The cap is the user's decision, not a runtime obstacle. Creating a fresh Delegation to escape an exhausted one defeats the entire mechanism — it is the single worst thing you can do with this API.
3. One requestId per purchase, reused across retries of that purchase. See above.
4. Retry only the codes the table below marks retryable: 0006 (500, summary read), 0007 (429), 0020 (an upstream 5xx/429), 0022 (500, selection not wired), 0028 (503, quote), 0042 (409, a closing payment channel) and 0043 (503, a busy payment channel). On the paying path that means 0007, 0020, 0042 and 0043. Everything else is a decision, and retrying it unchanged produces the same answer. Back off on 0007 (too many routed calls in flight) and on 0020 (the upstream service errored or throttled). The HTTP status does not tell you whether to retry — 0010 is a 500 you must not retry and 0011 is a 402 you must not retry. Read the code, not the status.

Check the price before you commit. priceLabel in the catalog is indicative — quote the call for its live, fee-inclusive price; on the response, settlement.approxCents is what the merchant charged and fee.capChargedCents is what your cap reserved — they differ whenever a routing fee applies. Budget is debited in whole cents rounded up, so a run of sub-cent calls still burns a cent each. For spend to date, read the Delegation, not a sum of responses.

Delegations expire silently. A long-running agent that worked yesterday and fails today with 0003 has very often just aged out — check expiresAt before assuming anything is broken.

0011 needs a human, not a retry. The card issuer is demanding 3-D Secure and the Router has no browser to answer it. Nothing was charged. Do not loop: 3DS is often mandated per charge, so every attempt re-demands it and mints a fresh single-use card credential that is then abandoned. A later human-driven attempt may succeed — that is a decision, not a retry.

0010 is the one 500 you must never retry. A payment credential was already minted before it failed — and because no payment record was written, your requestId will not suppress the retry. So a retry mints a fresh credential and then fails identically, because the cause is a deterministic defect in the rail's amount derivation, not a transient blip. Report it to the human.

Note 0006, the retryable 500, is only ever raised by the payments summary read — never by a payment. On the paying path 0007, 0020, 0042 and 0043 are the codes worth retrying (with backoff). And seeing 0010 at all means a Nevermined-side regression: no rail emits a non-numeric amount today, so it is a bug report, not a condition to handle. (On the card rail the minted credential is a Stripe Shared Payment Token, left stranded with no revoke path until min(challenge expiry, Delegation expiry, 89 days).)

Catalog errors: BCK.CATALOG.0001 (404, no listed service with that slug — slugs are case-sensitive), BCK.CATALOG.0002 (500, transient, retryable).

What the Router refuses outright — private/loopback/metadata targets, redirects, MPP splits, forged X-Router-* headers — and the relay limits: references/errors.md.

Reference files