Skip to main content
POST

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<uuid>
required

Delegation id (a capped spend authority) to spend against — created via POST /api/v1/delegation/create. It must be the caller’s own erc4337 delegation, a delegation funded by an organization wallet that funds a group the caller is an active member of (while the wallet, the group and the organization’s plan allow that spend), or the caller’s own card (stripe) delegation, which pays only mpp (see protocol).

protocol
enum<string>
required

Payment protocol. x402 (EIP-3009 exact) or mpp (Machine Payments Protocol). With a crypto delegation, mpp pays a method="tempo" charge, or a method="evm" charge, which is recorded with scheme exact. A card (stripe) delegation pays only mpp, and only a method="stripe" challenge (MPP-stripe: the Router issues a Stripe Shared Payment Token). Any other card payment, and every card payment on a deployment that does not enable that rail, is refused with 400 BCK.ROUTER.0001. 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. Pass extra through verbatim: the Router signs under the EIP-712 domain it holds for the settlement token, and checks the advertised extra.name/extra.version against it byte for byte — an agent that publishes a domain its own token does not sign under is rejected with BCK.ROUTER.0012 (nothing is signed, charged or reserved).

• 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. A challenge offering method="evm" (and no tempo offer) is paid as an EIP-3009 authorization in USDC/EURC on Base or Base Sepolia, under the same funded-network and token rules as x402 (the ledger scheme is exact). An evm merchant accepts only a plain ECDSA signature that recovers to the paying address, so a wallet that signs through an EIP-7702 smart account cannot pay it. This route first makes your own wallet an EIP-7702 account wherever EIP-7702 is enabled, so on such a deployment a personal delegation (one that spends from your own wallet) cannot pay an evm charge here. A delegation that spends from an organization wallet is refused the same way once that wallet’s walletMode is eip7702. Such a call is refused with 400 BCK.ROUTER.0001, whose details names the reason, before the payment is signed, reserved or charged. Mode A pays only the target you pass and never switches to another offer: if the service also offers x402, pay that offer instead (protocol: "x402" with its accepts), or call POST /api/v1/router/route, which pays such a 402 on its x402 offer itself unless requireProtocol pins it to mpp.

Example:
maxTotalCents
integer

Per-call ceiling, in whole cents, on the fee-inclusive price: the merchant’s price plus any collectable Router fee. The price is compared with it at micro resolution (1/10,000 of a cent), so a call is refused only when its price is above maxTotalCents cents, never because rounding to whole cents pushed it over. A call above it is refused with 402 BCK.ROUTER.0018 before anything is signed and before a payment record or delegation reserve is written.

Required range: 0 <= x <= 9007199254740991
Example:

5

resourceUrl
string

Upstream resource URL (absolute http(s)), recorded with the payment. A URL on the host of a cataloged Nevermined service is refused with 409 BCK.ROUTER.0014: invoke that service by its catalog slug through POST /api/v1/router/route instead.

Pattern: ^https?://.+
requestId
string

Caller correlation / idempotency id, recorded verbatim and looked up byte for byte. The Router hands out at most one credential per id: once a payment is recorded under the id, a retry gets 409 BCK.ROUTER.0002 instead. A refused call records nothing, so the id stays free and the next attempt with it mints again; after a 500 BCK.ROUTER.0010 that attempt fails the same way, so report it rather than retrying. An id is unique per account, across every Router route and every delegation, and never expires: two different purchases that derive the same id collide, and the second is refused. An empty string is the same as omitting it (no id).

Maximum string length: 256

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.

settlement
object
required

What this credential pays.

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.

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.