> ## 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. # Route and Pay a Request > Hand the Router the request you want made to an upstream x402 agent; it probes, pays any 402 with your Delegation (same engine as `POST /router/payments`), and relays the agent’s response in ONE call — you never see the 402 or handle the credential yourself. Prerequisite: a Delegation `id` (`POST /api/v1/delegation/create`, provider `erc4337`). Provide the target `url` (+ optional `method`, `headers`, `body`). A free (non-402) upstream is relayed unchanged with `paid=false` and no `payment`. `requestId` is REQUIRED (the Router pays automatically, so a retry must be idempotency-keyed); a duplicate returns 409 with the original paymentId. For LARGE or STREAMED responses, a transparent streaming variant exists at `ALL /api/v1/router/proxy`: point your HTTP client at it with headers `X-Router-Target-Url` and `X-Router-Delegation-Id` (optional `X-Router-Upstream-Authorization` for the agent’s own auth). Method/body/headers pass through and the response streams back, with payment metadata in `X-Router-Payment-Id`, `X-Router-Payment-Status`, and `X-Router-Tx-Hash` response headers. Use this JSON endpoint when you want a single structured result instead. ## OpenAPI ````yaml POST /router/route 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/route: post: tags: - Router summary: >- Route a request through the Router, paying the agent’s 402 and relaying the reply (mode B) description: >- Hand the Router the request you want made to an upstream x402 agent; it probes, pays any 402 with your Delegation (same engine as `POST /router/payments`), and relays the agent’s response in ONE call — you never see the 402 or handle the credential yourself. Prerequisite: a Delegation `id` (`POST /api/v1/delegation/create`, provider `erc4337`). Provide the target `url` (+ optional `method`, `headers`, `body`). A free (non-402) upstream is relayed unchanged with `paid=false` and no `payment`. `requestId` is REQUIRED (the Router pays automatically, so a retry must be idempotency-keyed); a duplicate returns 409 with the original paymentId. For LARGE or STREAMED responses, a transparent streaming variant exists at `ALL /api/v1/router/proxy`: point your HTTP client at it with headers `X-Router-Target-Url` and `X-Router-Delegation-Id` (optional `X-Router-Upstream-Authorization` for the agent’s own auth). Method/body/headers pass through and the response streams back, with payment metadata in `X-Router-Payment-Id`, `X-Router-Payment-Status`, and `X-Router-Tx-Hash` response headers. Use this JSON endpoint when you want a single structured result instead. operationId: routeAndPayRequest parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProxyRequestDto' examples: get-paid-resource: summary: GET a paid resource through the Router value: delegationId: 5e7481c3-e972-45bd-bdc5-a0b99c4de4a1 url: https://agent.example/paid method: GET requestId: order-1234 responses: '201': description: >- The relayed upstream response (`status` + `body`) plus the `payment` that was made. content: application/json: schema: $ref: '#/components/schemas/RouteResultDto' '400': description: >- Invalid request, no fundable option, or an upstream/402 error (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: ProxyRequestDto: type: object properties: delegationId: type: string description: >- The caller's erc4337 delegation to spend against (as in `POST /router/payments`). url: type: string description: Absolute upstream URL to route to (http/https only). example: https://agent.example/api/resource method: type: string description: HTTP method to use for the upstream request. enum: - GET - POST - PUT - PATCH - DELETE default: GET headers: type: object description: >- Headers to forward to the upstream (e.g. the agent’s own auth). Optional. body: description: Request body to forward (JSON). Optional. protocol: type: string description: >- Payment protocol. On the mode-B proxy (`/route`, `/proxy`) this is ADVISORY: the Router AUTO-DETECTS the protocol from the upstream 402 — `WWW-Authenticate: Payment` → `mpp`; `accepts` / `PAYMENT-REQUIRED` → `x402` — and the DETECTED protocol is authoritative for the mint (a mismatching hint here does not change what gets paid). enum: - x402 - mpp default: x402 requestId: type: string description: >- Idempotency key — REQUIRED for routed payments (mode B). The Router makes the upstream call and pays automatically, so a retry after a dropped connection must not double-spend. At most one payment is minted per (caller, requestId); a duplicate returns 409 (BCK.ROUTER.0002) carrying the original paymentId, rather than paying again. example: order-1234 required: - delegationId - url - requestId RouteResultDto: type: object properties: status: type: number description: The upstream HTTP status code that was relayed. example: 200 body: description: >- The upstream response body (parsed JSON when the upstream returned JSON, else a string). example: ok: true data: the paid resource paid: type: boolean description: Whether a payment was made (false = the upstream was free). example: true payment: description: The payment made, when `paid` is true. allOf: - $ref: '#/components/schemas/RouteResultPaymentDto' required: - status - body - paid 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 RouteResultPaymentDto: type: object properties: paymentId: type: string example: b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13 settlement: $ref: '#/components/schemas/SettlementDescriptorDto' fee: description: >- Nevermined’s routing fee for this payment. Mode B charges it exactly as mode A does, so it is disclosed here too — `settlement.approxCents` is only the merchant leg, and `fee.capChargedCents` is what the delegation cap was actually debited. allOf: - $ref: '#/components/schemas/RouterFeeDto' txHash: type: string description: On-chain settlement tx, if the upstream reported one. nullable: true status: type: string enum: - Issued - Settled example: Settled required: - paymentId - settlement - fee - status 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 - [Fiat Payments](/docs/integrate/patterns/fiat-payments.md) - [How the Router works](/docs/products/router/how-it-works.md) - [Nevermined Router Overview](/docs/products/router/overview.md) - [Router quickstart](/docs/products/router/quickstart.md) - [Mint Payment Credential](/docs/api-reference/router/mint-payment-credential.md)