Route a request through the Router, paying the agent’s 402 and relaying the reply (mode B)

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"
}
'

import requests

url = "https://api.sandbox.nevermined.app/api/v1/router/route"

payload = {
    "delegationId": "5e7481c3-e972-45bd-bdc5-a0b99c4de4a1",
    "url": "https://agent.example/paid",
    "method": "GET",
    "requestId": "order-1234"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    delegationId: '5e7481c3-e972-45bd-bdc5-a0b99c4de4a1',
    url: 'https://agent.example/paid',
    method: 'GET',
    requestId: 'order-1234'
  })
};

fetch('https://api.sandbox.nevermined.app/api/v1/router/route', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.nevermined.app/api/v1/router/route",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'delegationId' => '5e7481c3-e972-45bd-bdc5-a0b99c4de4a1',
    'url' => 'https://agent.example/paid',
    'method' => 'GET',
    'requestId' => 'order-1234'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.nevermined.app/api/v1/router/route"

	payload := strings.NewReader("{\n  \"delegationId\": \"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1\",\n  \"url\": \"https://agent.example/paid\",\n  \"method\": \"GET\",\n  \"requestId\": \"order-1234\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.nevermined.app/api/v1/router/route")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"delegationId\": \"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1\",\n  \"url\": \"https://agent.example/paid\",\n  \"method\": \"GET\",\n  \"requestId\": \"order-1234\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.nevermined.app/api/v1/router/route")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"delegationId\": \"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1\",\n  \"url\": \"https://agent.example/paid\",\n  \"method\": \"GET\",\n  \"requestId\": \"order-1234\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": 200,
  "body": {
    "ok": true,
    "data": "the paid resource"
  },
  "paid": true,
  "payment": {
    "paymentId": "b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13",
    "settlement": {
      "recipient": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "amount": "1000",
      "network": "base-sepolia",
      "approxCents": "1",
      "asset": "USDC",
      "scheme": "exact"
    },
    "fee": {
      "bps": 0,
      "amount": "0",
      "cents": "0",
      "capChargedCents": "1"
    },
    "status": "Settled",
    "txHash": "<string>"
  }
}

{
  "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\"}"
}

Router

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.

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.

POST

router

route

Route a request through the Router, paying the agent’s 402 and relaying the reply (mode B)

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"
}
'

import requests

url = "https://api.sandbox.nevermined.app/api/v1/router/route"

payload = {
    "delegationId": "5e7481c3-e972-45bd-bdc5-a0b99c4de4a1",
    "url": "https://agent.example/paid",
    "method": "GET",
    "requestId": "order-1234"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    delegationId: '5e7481c3-e972-45bd-bdc5-a0b99c4de4a1',
    url: 'https://agent.example/paid',
    method: 'GET',
    requestId: 'order-1234'
  })
};

fetch('https://api.sandbox.nevermined.app/api/v1/router/route', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.nevermined.app/api/v1/router/route",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'delegationId' => '5e7481c3-e972-45bd-bdc5-a0b99c4de4a1',
    'url' => 'https://agent.example/paid',
    'method' => 'GET',
    'requestId' => 'order-1234'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.nevermined.app/api/v1/router/route"

	payload := strings.NewReader("{\n  \"delegationId\": \"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1\",\n  \"url\": \"https://agent.example/paid\",\n  \"method\": \"GET\",\n  \"requestId\": \"order-1234\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.nevermined.app/api/v1/router/route")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"delegationId\": \"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1\",\n  \"url\": \"https://agent.example/paid\",\n  \"method\": \"GET\",\n  \"requestId\": \"order-1234\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.nevermined.app/api/v1/router/route")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"delegationId\": \"5e7481c3-e972-45bd-bdc5-a0b99c4de4a1\",\n  \"url\": \"https://agent.example/paid\",\n  \"method\": \"GET\",\n  \"requestId\": \"order-1234\"\n}"

response = http.request(request)
puts response.read_body

{
  "status": 200,
  "body": {
    "ok": true,
    "data": "the paid resource"
  },
  "paid": true,
  "payment": {
    "paymentId": "b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13",
    "settlement": {
      "recipient": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "amount": "1000",
      "network": "base-sepolia",
      "approxCents": "1",
      "asset": "USDC",
      "scheme": "exact"
    },
    "fee": {
      "bps": 0,
      "amount": "0",
      "cents": "0",
      "capChargedCents": "1"
    },
    "status": "Settled",
    "txHash": "<string>"
  }
}

{
  "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

Authorization

string

header

required

Your Nevermined API Key (starts with 'nvm:'). Get one at nevermined.app under Settings > API Keys.

Body

application/json

delegationId

string

required

The caller's erc4337 delegation to spend against (as in POST /router/payments).

url

string

required

Absolute upstream URL to route to (http/https only).

Example:

"https://agent.example/api/resource"

requestId

string

required

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.

Example:

"order-1234"

method

enum<string>

default:GET

HTTP method to use for the upstream request.

Available options:

GET,

POST,

PUT,

PATCH,

DELETE

headers

object

Headers to forward to the upstream (e.g. the agent’s own auth). Optional.

body

any

Request body to forward (JSON). Optional.

protocol

enum<string>

default:x402

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).

Available options:

x402,

mpp

Response

The relayed upstream response (status + body) plus the payment that was made.

status

number

required

The upstream HTTP status code that was relayed.

Example:

200

body

any

required

The upstream response body (parsed JSON when the upstream returned JSON, else a string).

Example:

{ "ok": true, "data": "the paid resource" }

paid

boolean

required

Whether a payment was made (false = the upstream was free).

Example:

true

payment

object

The payment made, when paid is true.

Show child attributes

Overview

Agents

Plans

Access

x402

Credits

Delegation

Router

Payment Methods

Organizations

Authentication

Route and Pay a Request

Authorizations

Body

Response