---
title: "Mint an x402 payment credential for an upstream agent (mode A)"
method: POST
path: "/router/payments"
tags: ["Router"]
---

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

`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

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

## Request body

- CreatePaymentDto
  - `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` '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 }`.
  - `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.
  - `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 `201`

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

- MintPaymentResponseDto
  - `paymentId` string, required: Router payment record id (use it with `POST /router/payments/{id}/settled`).
  - `protocol` 'x402' | 'mpp', required: Payment protocol used.
  - `x402Version` number: Negotiated x402 version (1 or 2).
  - `credential` PaymentCredentialDto, required
    - `transport` 'header', required: How the credential is delivered to the upstream. Always `header`.
    - `name` 'PAYMENT-SIGNATURE' | 'X-PAYMENT' | 'Authorization', required: The exact HTTP header name to set on your request to the upstream agent. `PAYMENT-SIGNATURE` for x402 v2, `X-PAYMENT` for x402 v1, `Authorization` for mpp.
    - `value` string, required: The header VALUE to set. For x402 a base64-encoded signed payment payload; for mpp a `Payment <base64url>` credential. Opaque — attach it verbatim; do not modify.
  - `settlement` SettlementDescriptorDto, required
    - `recipient` string, required: The on-chain recipient (the agent’s `payTo` address from its 402).
    - `amount` string, required: Amount in the asset’s smallest unit (USDC/EURC = 6 decimals).
    - `asset` string: For x402 the asset symbol (`USDC`/`EURC`); for mpp the tempo payment token contract address (mpp carries no on-wire symbol).
    - `network` string, required: Network the payment settles on (name or CAIP-2).
    - `approxCents` string, required: The MERCHANT leg in cents (rounded up) — what this credential pays the upstream agent. This is not necessarily the whole cap charge: Nevermined’s routing fee is reserved on top, so the whole-cent total debited from the delegation is `approxCents + fee.cents` (also reported directly as `fee.capChargedCents`; the exact sub-cent debit is `fee.capChargedMicros`). With no fee configured the two are equal.
    - `scheme` 'exact' | 'charge' | 'spt': Ledger settlement scheme: `exact` for x402 (EIP-3009), `charge` for MPP-tempo (a native Tempo transaction), `spt` for MPP-stripe (a Shared Payment Token). Omitted (defaults to `exact`) on the x402 path.
  - `fee` RouterFeeDto, required
    - `bps` number, required: Rate applied to this payment, in basis points over a 10,000 denominator (e.g. `200` = 2%). `0` means no routing fee was charged.
    - `amount` string, required: The fee in the settlement asset’s smallest unit — the same unit as `settlement.amount`. Reported atomically rather than in cents because cents are ceiling-rounded and cannot express a sub-cent fee.
    - `cents` string, required: Cents this fee added to the delegation-cap reserve, i.e. `capChargedCents - settlement.approxCents`.
    - `capChargedCents` string, required: The delegation-cap debit for this payment (merchant leg + routing fee), rounded UP to a whole cent. The cap itself accrues at sub-cent resolution, so the exact debit is `capChargedMicros`; this figure is the per-call price guard that `maxTotalCents` is compared against.
    - `capChargedMicros` string, required: The exact delegation-cap debit for this payment (merchant leg + routing fee), in micros — millionths of the currency unit, i.e. 1/10,000 of a cent. It is a ceiling of the true price at that resolution, never below it. It is the debit AT MINT: if the routing fee or the merchant leg is later found uncollected, that part is given back to the cap while this figure stays as minted.
  - `delegationId` string, required: The delegation this spend was reserved against.
  - `resourceUrl` string, nullable: The upstream resource URL recorded with the payment.
  - `requestId` string, nullable: Your idempotency id, echoed back.
  - `status` 'Issued', required: Record status at mint time.

## Other responses

- `400`: Invalid request, no fundable option in `target`, or a malformed 402 (BCK.ROUTER.0001).
- `401`: Missing/invalid Nevermined API key.
- `402`: Delegation budget exceeded, expired, or inactive (BCK.ROUTER.0003).
- `403`: Credential barred from the Router spend rails — an OAuth-minted key (device/auth-code ceremony) may not spend here; use a plain account key (BCK.OAUTH.0030). Permanent, do not retry.
- `409`: The `requestId` was already used — idempotency conflict (BCK.ROUTER.0002).

---

[API](https://skmtc.dev/nevermined/apis/nevermined-api.md) · [All operations](https://skmtc.dev/nevermined/apis/nevermined-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nevermined/apis/nevermined-api/revisions/cabbe618c80b?raw)