Router

Mint an x402 payment credential for an upstream agent (mode A)

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:

  1. 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.
  2. 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.
  3. 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

Request

  • Base URL: https://api.sandbox.nevermined.app/api/v1
  • URL: https://api.sandbox.nevermined.app/api/v1/router/payments
  • Auth: HTTP bearer

Request body

delegationIdstring 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'x402' | 'mpp' 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 }.

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

resourceUrlstring

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

requestIdstring

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

Example request

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

Response

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

paymentIdstring required

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

protocol'x402' | 'mpp' required

Payment protocol used.

x402Versionnumber

Negotiated x402 version (1 or 2).

delegationIdstring required

The delegation this spend was reserved against.

resourceUrlstring nullable

The upstream resource URL recorded with the payment.

requestIdstring nullable

Your idempotency id, echoed back.

status'Issued' required

Record status at mint time.

Example response

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

Changes

No recorded changes to this operation across all 1 revision of this API.