curl --request POST \
--url https://api.sandbox.nevermined.app/api/v1/router/route \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"delegationId": "5e7481c3-e972-45bd-bdc5-a0b99c4de4a1",
"url": "https://agent.example/paid",
"method": "GET",
"requestId": "order-1234"
}
'{
"status": 200,
"body": {
"status": "complete",
"…": "the delivered result, exactly as the service returned it"
},
"paid": false
}{
"paymentId": "b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13",
"resultUrl": "/api/v1/router/payments/b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13/result",
"status": "Pending"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}Route and Pay a Request
Hand the Router the request you want made to an upstream x402 agent; it probes, pays any 402
with your Delegation (same engine as POST /router/payments), and relays the agent’s response in ONE
call — you never see the 402 or handle the credential yourself.
Prerequisite: a Delegation id (POST /api/v1/delegation/create, provider erc4337).
Provide the target url (+ optional method, headers, body). A free (non-402) upstream is
relayed unchanged with paid=false and no payment. requestId is REQUIRED (the Router pays automatically, so a retry must be idempotency-keyed); a duplicate returns 409 with the original paymentId (from API 1.48, the first purchase’s retained result instead — see GET /router/payments/{id}/result).
For LARGE or STREAMED responses, a transparent streaming variant exists at ALL /api/v1/router/proxy:
point your HTTP client at it with headers X-Router-Target-Url and X-Router-Delegation-Id
(optional X-Router-Upstream-Authorization for the agent’s own auth). Method/body/headers pass
through and the response streams back, with payment metadata in X-Router-Payment-Id,
X-Router-Payment-Status, and X-Router-Tx-Hash response headers. Use this JSON endpoint when
you want a single structured result instead.
curl --request POST \
--url https://api.sandbox.nevermined.app/api/v1/router/route \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"delegationId": "5e7481c3-e972-45bd-bdc5-a0b99c4de4a1",
"url": "https://agent.example/paid",
"method": "GET",
"requestId": "order-1234"
}
'{
"status": 200,
"body": {
"status": "complete",
"…": "the delivered result, exactly as the service returned it"
},
"paid": false
}{
"paymentId": "b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13",
"resultUrl": "/api/v1/router/payments/b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13/result",
"status": "Pending"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}{
"code": "BCK.ROUTER.0003",
"httpStatus": 500,
"message": "delegation budget exceeded, expired, or inactive",
"details": "Hash JWT is not signed by the node account",
"error": "authorization_pending",
"hint": "Verify the wallet has sufficient balance and that the plan is active.",
"docsUrl": "https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008",
"category": "integration",
"retryable": true,
"correlationId": "a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9",
"uuid": "e-550e8400-e29b-41d4-a716-446655440000",
"date": "2026-05-09T12:34:56.789Z",
"params": "{\"planId\":\"43298432984329\",\"reason\":\"Invalid configuration\"}"
}Authorizations
Your Nevermined API Key (starts with 'nvm:'). Get one at nevermined.app under Settings > API Keys.
Body
Idempotency key — REQUIRED for routed payments (mode B). The Router makes the upstream call and pays automatically, so a retry after a dropped connection must not double-spend. At most one payment is minted per (caller, requestId); a duplicate returns 409 (BCK.ROUTER.0002) carrying the original paymentId, rather than paying again.
"order-1234"
Catalog slug to invoke via the opaque Router broker. The Router resolves the slug to the real upstream server-side, so the URL is never exposed. Mutually exclusive with url. Required to read the result of an async service (an endpoint the catalog marks auth: "siwx"): the Router answers its wallet challenge only on a slug call.
"webscrape-pro"
Optional subpath appended to the resolved upstream when slug is used (e.g. scrape → the merchant's /scrape). Path segments only — it may not change the host: //, .., a backslash and an embedded absolute URL are rejected (400). A catalog template placeholder ({jobId}, :id) must be filled with a real value, or the call is refused (400). Ignored when url is used.
"scrape"
Query string for a slug-routed request, without the leading ?. It is attached to the resolved merchant URL without changing its host. Use this instead of embedding ? in path. With a raw url, include the query in url; sending search with url is refused.
2048"flight_iata=AA217&limit=1"
Payment protocol. On the mode-B proxy (/route, /proxy) this is ADVISORY: the Router AUTO-DETECTS the protocol from the upstream 402 — WWW-Authenticate: Payment → mpp; accepts / PAYMENT-REQUIRED → x402 — and the DETECTED protocol is authoritative for the mint (a mismatching hint here does not change what gets paid).
x402, mpp Binding payment-rail pin (API v1.88.0+), unlike advisory protocol. Pay or quote only this rail, with no fallback. If unavailable, return 409 BCK.ROUTER.0045 before signing, reserving or charging. Omit to auto-select (MPP first). Quote and pay with the same pin; a quoteId bound to another rail is refused with BCK.ROUTER.0033. Never silently remove the pin.
x402, mpp Opt-in request-body gate (default off). When true, a request body that provably fails the endpoint's published request schema is refused with 400 BCK.ROUTER.0046 before anything is signed, reserved or charged, so you are not billed for a call the merchant would reject. Only a provably-invalid body is refused; a missing or unverifiable schema still pays (fail-open). Honoured on the buffered pay routes /router/route, /router/commerce/route and /router/subscription/route (the Commerce MCP pay_service forwards it to them); the streaming /proxy and /svc/:slug surfaces do not apply it. Fix the body to match the endpoint's published requestSchema (catalog service detail, or Commerce MCP get_service), or omit the flag.
Response
The relayed upstream response (status + body) plus the payment that was made.
Was this page helpful?