> ## Documentation Index > Fetch the complete documentation index at: https://nevermined.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # 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: 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`). ## OpenAPI ````yaml POST /router/payments openapi: 3.1.0 info: title: Nevermined API description: >- API for managing AI agents, payment plans, and x402 payments in the Nevermined ecosystem. ## Prerequisites You need a Nevermined API Key to authenticate. Get one at [nevermined.app](https://nevermined.app) under **Settings > API Keys**. See the [5-Minute Setup Guide](/docs/integrate/quickstart/5-minute-setup) for detailed instructions. license: name: MIT version: 1.0.0 servers: - url: https://api.sandbox.nevermined.app/api/v1 description: Sandbox (Testing) - Base Sepolia - url: https://api.live.nevermined.app/api/v1 description: Live (Production) - Base Mainnet security: - bearerAuth: [] tags: - name: Protocol - Agents description: Endpoints for registering and managing AI agents - name: Protocol - Plans description: Endpoints for creating and managing payment plans - name: Protocol - Credits description: Endpoints for minting and redeeming credits - name: Protocol - Access description: Endpoints for access tokens and request validation - name: X402 - Permissions description: Endpoints for x402 delegated permissions paths: /router/payments: post: tags: - Router summary: Mint an x402 payment credential for an upstream agent (mode A) description: >- 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`). operationId: mintX402PaymentCredential parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentDto' examples: x402-v1: summary: Pay a v1 (x402-express) agent value: 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' mpp-tempo: summary: Pay an MPP (tempo charge) merchant value: delegationId: 5e7481c3-e972-45bd-bdc5-a0b99c4de4a1 protocol: mpp resourceUrl: https://merchant.example/paid requestId: order-5678 target: challenge: >- Payment id="ch_abc", realm="merchant.example", method="tempo", intent="charge", request="" responses: '201': description: >- A signed credential + settlement descriptor + record id. Attach `credential.value` under header `credential.name` to your request to the agent. content: application/json: schema: $ref: '#/components/schemas/MintPaymentResponseDto' '400': description: >- Invalid request, no fundable option in `target`, or a malformed 402 (BCK.ROUTER.0001). content: application/json: schema: $ref: '#/components/schemas/RouterErrorResponseDto' '401': description: Missing/invalid Nevermined API key. content: application/json: schema: $ref: '#/components/schemas/RouterErrorResponseDto' '402': description: Delegation budget exceeded, expired, or inactive (BCK.ROUTER.0003). content: application/json: schema: $ref: '#/components/schemas/RouterErrorResponseDto' '403': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/RouterErrorResponseDto' '409': description: >- The `requestId` was already used — idempotency conflict (BCK.ROUTER.0002). content: application/json: schema: $ref: '#/components/schemas/RouterErrorResponseDto' components: schemas: CreatePaymentDto: type: object properties: delegationId: type: string description: >- 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: type: string description: >- Payment protocol. `x402` (EIP-3009 exact) or `mpp` (Merchant Payment Protocol, tempo `charge`). The `target` shape depends on this: x402 → `{ accepts, x402Version? }`; mpp → `{ challenge }`. enum: - x402 - mpp example: x402 target: type: object description: >- 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=""`. 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: type: string description: >- Upstream resource URL (absolute http(s)) — recorded with the payment. requestId: type: string description: >- Caller correlation / idempotency id — at most one credential is minted per requestId; recorded. required: - delegationId - protocol - target MintPaymentResponseDto: type: object properties: paymentId: type: string description: >- Router payment record id (use it with `POST /router/payments/{id}/settled`). example: b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13 protocol: type: string description: Payment protocol used. enum: - x402 - mpp example: x402 x402Version: type: number description: Negotiated x402 version (1 or 2). example: 2 credential: description: The credential to attach to your upstream request. allOf: - $ref: '#/components/schemas/PaymentCredentialDto' settlement: description: What this credential pays. allOf: - $ref: '#/components/schemas/SettlementDescriptorDto' fee: description: >- 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. allOf: - $ref: '#/components/schemas/RouterFeeDto' delegationId: type: string description: The delegation this spend was reserved against. example: 5e7481c3-... resourceUrl: type: string description: The upstream resource URL recorded with the payment. nullable: true requestId: type: string description: Your idempotency id, echoed back. nullable: true status: type: string description: Record status at mint time. enum: - Issued example: Issued required: - paymentId - protocol - credential - settlement - fee - delegationId - status RouterErrorResponseDto: type: object properties: code: type: string description: >- Router error code. `BCK.ROUTER.0001` invalid request / no fundable option / bad 402 (400); `BCK.ROUTER.0002` requestId already used — idempotency conflict (409); `BCK.ROUTER.0003` delegation budget exceeded, expired, or inactive (402); `BCK.ROUTER.0004` payment record not found (404); `BCK.ROUTER.0005` payment not in a settleable state (409). Framework-level `BCK.HTTP.*` codes (e.g. `BCK.HTTP.400` request validation, `BCK.HTTP.429` throttling) may also appear — see the base `code` field. example: BCK.ROUTER.0003 httpStatus: type: number description: HTTP status code example: 500 message: type: string description: Error message for Router operations. example: delegation budget exceeded, expired, or inactive examples: - >- delegationId is required — create one via POST /api/v1/delegation/create - 'no fundable option; offered: [...]' - >- upstream pay-to address is not in this delegation's allowed recipients - delegation budget exceeded, expired, or inactive - payment already settled with a different txHash details: type: string description: >- Throw-site detail string supplementing the canonical message. Only set when the call site supplied an opts.message; absent otherwise. example: Hash JWT is not signed by the node account error: type: string description: >- RFC 6749 §5.2 / RFC 8628 §3.5 top-level OAuth error string. Present only on the OAuth device-polling responses from `POST /oauth/token` (`authorization_pending`, `slow_down`, `expired_token`, `access_denied`), so a standards-compliant OAuth/device client can branch on it directly instead of on the Nevermined `code`. Absent on every other error. example: authorization_pending hint: type: string description: >- Actionable remediation hint, sourced from the catalogue or supplied at the throw site. Tells the caller what to fix or where to look. example: >- Verify the wallet has sufficient balance and that the plan is active. docsUrl: type: string description: Permalink to the docs page describing this error code. example: >- https://nevermined.ai/docs/development-guide/api-errors/codes#bck-x402-0008 category: type: string description: >- Coarse classification of the failure, useful for client-side branching without parsing the message. enum: - validation - auth - business - integration - internal example: integration retryable: type: boolean description: >- Whether the failure is transient and the same call can be retried with identical inputs. Absent when the catalogue does not assert either way. example: true correlationId: type: string description: >- Request-scoped correlation id stamped by the global filter. Echoed in the x-correlation-id response header. Quote this when reporting issues. example: a3f6b1c4-7d2e-4a9b-8e0c-12f4d8e6c5b9 uuid: type: string description: >- Per-error UUID generated at construction. Useful for log correlation. example: e-550e8400-e29b-41d4-a716-446655440000 date: type: string description: ISO timestamp at which the error was constructed. example: '2026-05-09T12:34:56.789Z' format: date-time params: type: string description: >- JSON-stringified contextual parameters supplied at the throw site (e.g. IDs, state). Always a string in the wire format — parse with JSON.parse if needed. example: '{"planId":"43298432984329","reason":"Invalid configuration"}' required: - code - httpStatus - message PaymentCredentialDto: type: object properties: transport: type: string description: How the credential is delivered to the upstream. Always `header`. enum: - header example: header name: type: string description: >- 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. enum: - PAYMENT-SIGNATURE - X-PAYMENT - Authorization example: PAYMENT-SIGNATURE value: type: string description: >- The header VALUE to set. For x402 a base64-encoded signed payment payload; for mpp a `Payment ` credential. Opaque — attach it verbatim; do not modify. example: eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0ZWQiOnsuLi59LCJwYXlsb2FkIjp7Li4ufX0= required: - transport - name - value SettlementDescriptorDto: type: object properties: recipient: type: string description: The on-chain recipient (the agent’s `payTo` address from its 402). example: '0x209693Bc6afc0C5328bA36FaF03C514EF312287C' amount: type: string description: Amount in the asset’s smallest unit (USDC/EURC = 6 decimals). example: '1000' asset: type: string description: >- For x402 the asset symbol (`USDC`/`EURC`); for mpp the tempo payment token contract address (mpp carries no on-wire symbol). example: USDC network: type: string description: Network the payment settles on (name or CAIP-2). example: base-sepolia approxCents: type: string description: >- 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 total debited from the delegation is `approxCents + fee.cents` (also reported directly as `fee.capChargedCents`). With no fee configured the two are equal. example: '1' scheme: type: string description: >- Ledger settlement scheme: `exact` for x402 (EIP-3009), `charge` for mpp (native Tempo tx). Omitted (defaults to `exact`) on the x402 path. enum: - exact - charge example: exact required: - recipient - amount - network - approxCents RouterFeeDto: type: object properties: bps: type: number description: >- Rate applied to this payment, in basis points over a 10,000 denominator (e.g. `200` = 2%). `0` means no routing fee was charged. example: 0 amount: type: string description: >- 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. example: '0' cents: type: string description: >- Cents this fee added to the delegation-cap reserve, i.e. `capChargedCents - settlement.approxCents`. example: '0' capChargedCents: type: string description: >- Total debited from the delegation cap for this payment (merchant leg + routing fee), in cents. example: '1' required: - bps - amount - cents - capChargedCents securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Nevermined API Key (starts with 'nvm:'). Get one at [nevermined.app](https://nevermined.app) under **Settings > API Keys**. ```` ## Related topics - [API error codes](/docs/development-guide/api-errors/codes.md) - [The x402 rail](/docs/products/router/rails-x402.md) - [Authentication & Identity](/docs/integrate/authentication/overview.md) - [Embed Nevermined Widgets](/docs/integrations/organization-widgets.md) - [White-label Customer Onboarding](/docs/solutions/organizations/white-label-onboarding.md)