curl --request POST \
  --url https://api.sandbox.nevermined.app/api/v1/router/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "delegationId": "5e7481c3-e972-45bd-bdc5-a0b99c4de4a1",
  "protocol": "x402",
  "resourceUrl": "https://agent.example/paid",
  "requestId": "order-1234",
  "target": {
    "x402Version": 1,
    "accepts": [
      {
        "scheme": "exact",
        "network": "base-sepolia",
        "maxAmountRequired": "1000",
        "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
        "maxTimeoutSeconds": 60,
        "extra": {
          "name": "USDC",
          "version": "2"
        }
      }
    ]
  }
}
'

{
  "paymentId": "b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13",
  "protocol": "x402",
  "credential": {
    "transport": "header",
    "name": "PAYMENT-SIGNATURE",
    "value": "eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0ZWQiOnsuLi59LCJwYXlsb2FkIjp7Li4ufX0="
  },
  "settlement": {
    "recipient": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "amount": "1000",
    "network": "base-sepolia",
    "approxCents": "1",
    "asset": "USDC",
    "scheme": "exact"
  },
  "fee": {
    "bps": 0,
    "amount": "0",
    "cents": "0",
    "capChargedCents": "1"
  },
  "delegationId": "5e7481c3-...",
  "status": "Issued",
  "x402Version": 2,
  "resourceUrl": "<string>",
  "requestId": "<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

Mint Payment Credential

Pay any x402-compatible agent WITHOUT that agent integrating Nevermined. Returns a signed credential you attach to your own request to the agent.

Prerequisite: a spending Delegation. Create one once via POST /api/v1/delegation/create with provider: 'erc4337', a spendingLimitCents, and a durationSecs; pass its id as delegationId here. The Router signs with your custodial wallet and enforces the cap.

Steps:

Call the agent once WITHOUT payment → it replies HTTP 402 with requirements. x402 v1 puts them in the JSON body { x402Version: 1, accepts: [...] }; x402 v2 puts them in a base64 PAYMENT-REQUIRED response header (decode to an object). Pass what you got as target.
POST here. The Router selects a fundable option, signs an x402 exact (EIP-3009) payment, reserves the amount against your Delegation, and returns credential + settlement.
Re-send your original request to the agent with the HTTP header named credential.name (PAYMENT-SIGNATURE for v2, X-PAYMENT for v1) set to credential.value. The agent verifies, settles on-chain, and returns the resource.

Optionally call POST /api/v1/router/payments/{id}/settled with the on-chain tx to complete the audit record. Pass a stable requestId for idempotency (one credential per id). Prefer POST /api/v1/router/route to have the Router call the agent and pay in one step (mode B).

MPP: set protocol: "mpp" and pass the raw WWW-Authenticate: Payment … header value as target.challenge to pay a Merchant-Payment-Protocol (tempo charge) merchant. The Router returns an Authorization: Payment <…> credential (attach it under header credential.name).

POST

router

payments

curl --request POST \
  --url https://api.sandbox.nevermined.app/api/v1/router/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "delegationId": "5e7481c3-e972-45bd-bdc5-a0b99c4de4a1",
  "protocol": "x402",
  "resourceUrl": "https://agent.example/paid",
  "requestId": "order-1234",
  "target": {
    "x402Version": 1,
    "accepts": [
      {
        "scheme": "exact",
        "network": "base-sepolia",
        "maxAmountRequired": "1000",
        "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
        "payTo": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
        "maxTimeoutSeconds": 60,
        "extra": {
          "name": "USDC",
          "version": "2"
        }
      }
    ]
  }
}
'

{
  "paymentId": "b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13",
  "protocol": "x402",
  "credential": {
    "transport": "header",
    "name": "PAYMENT-SIGNATURE",
    "value": "eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0ZWQiOnsuLi59LCJwYXlsb2FkIjp7Li4ufX0="
  },
  "settlement": {
    "recipient": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "amount": "1000",
    "network": "base-sepolia",
    "approxCents": "1",
    "asset": "USDC",
    "scheme": "exact"
  },
  "fee": {
    "bps": 0,
    "amount": "0",
    "cents": "0",
    "capChargedCents": "1"
  },
  "delegationId": "5e7481c3-...",
  "status": "Issued",
  "x402Version": 2,
  "resourceUrl": "<string>",
  "requestId": "<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

Delegation id (the caller's individual spend authority) to spend against — created via POST /api/v1/delegation/create and validated as the caller’s own erc4337 delegation.

protocol

enum<string>

required

Payment protocol. x402 (EIP-3009 exact) or mpp (Merchant Payment Protocol, tempo charge). The target shape depends on this: x402 → { accepts, x402Version? }; mpp → { challenge }.

Available options:

x402,

mpp

Example:

"x402"

target

object

required

The upstream's payment requirements, taken verbatim from its HTTP 402 response — its shape depends on protocol.

• x402 — pass { accepts: [...], x402Version? }: accepts is the array of payment options the agent advertised (each with scheme, network, asset, payTo, maxAmountRequired/amount, and extra.name/extra.version for the EIP-712 domain). Get it from the 402 body (x402 v1: { x402Version: 1, accepts }) or by base64-decoding the PAYMENT-REQUIRED response header (x402 v2). x402Version defaults to 2 when omitted — set it to 1 for x402-express agents.

• mpp — pass { challenge }, where challenge is the raw WWW-Authenticate: Payment … header value from the merchant’s 402, verbatim — e.g. Payment id="…", method="tempo", intent="charge", request="<base64url>". The Router decodes it, verifies the buyer wallet can fund the tempo charge, signs a native Tempo transaction, and returns an Authorization: Payment <…> credential (the ledger scheme is charge). The tempo payment currency (token address) must be on the operator’s per-chain allowlist.

Example:

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

resourceUrl

string

Upstream resource URL (absolute http(s)) — recorded with the payment.

requestId

string

Caller correlation / idempotency id — at most one credential is minted per requestId; recorded.

Response

A signed credential + settlement descriptor + record id. Attach credential.value under header credential.name to your request to the agent.

paymentId

string

required

Router payment record id (use it with POST /router/payments/{id}/settled).

Example:

"b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13"

protocol

enum<string>

required

Payment protocol used.

Available options:

x402,

mpp

Example:

"x402"

credential

object

required

The credential to attach to your upstream request.

Show child attributes

settlement

object

required

What this credential pays.

Show child attributes

fee

object

required

Nevermined’s routing fee charged on top of the merchant leg. The credential itself pays the merchant only — the fee never rides the merchant’s authorization.

Show child attributes

delegationId

string

required

The delegation this spend was reserved against.

Example:

"5e7481c3-..."

status

enum<string>

required

Record status at mint time.

Available options:

Issued

Example:

"Issued"

x402Version

number

Negotiated x402 version (1 or 2).

Example:

2

resourceUrl

string | null

The upstream resource URL recorded with the payment.

requestId

string | null

Your idempotency id, echoed back.

Overview

Agents

Plans

Access

x402

Credits

Delegation

Router

Payment Methods

Organizations

Authentication

Mint Payment Credential

Authorizations

Body

Response