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
required

The caller's erc4337 delegation to spend against (as in POST /router/payments).

requestId
string
required

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"

url
string

Absolute upstream URL to route to (http/https only). Provide EXACTLY ONE of url or slug.

Example:

"https://agent.example/api/resource"

slug
string

Catalog slug to invoke via the opaque Router broker. The Router resolves the slug to the real upstream server-side, so the URL is never exposed. Mutually exclusive with url. Required to read the result of an async service (an endpoint the catalog marks auth: "siwx"): the Router answers its wallet challenge only on a slug call.

Example:

"webscrape-pro"

path
string

Optional subpath appended to the resolved upstream when slug is used (e.g. scrape → the merchant's /scrape). Path segments only — it may not change the host: //, .., a backslash and an embedded absolute URL are rejected (400). A catalog template placeholder ({jobId}, :id) must be filled with a real value, or the call is refused (400). Ignored when url is used.

Example:

"scrape"

Query string for a slug-routed request, without the leading ?. It is attached to the resolved merchant URL without changing its host. Use this instead of embedding ? in path. With a raw url, include the query in url; sending search with url is refused.

Maximum string length: 2048
Example:

"flight_iata=AA217&limit=1"

method
enum<string>
default:GET

HTTP method to use for the upstream request.

Available options:
GET,
POST,
PUT,
PATCH,
DELETE
headers
object

Headers to forward to the upstream (e.g. the agent’s own auth). Optional.

body
any

Request body to forward (JSON). Optional.

protocol
enum<string>
default:x402

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

Available options:
x402,
mpp
requireProtocol
enum<string>

Binding payment-rail pin (API v1.88.0+), unlike advisory protocol. Pay or quote only this rail, with no fallback. If unavailable, return 409 BCK.ROUTER.0045 before signing, reserving or charging. Omit to auto-select (MPP first). Quote and pay with the same pin; a quoteId bound to another rail is refused with BCK.ROUTER.0033. Never silently remove the pin.

Available options:
x402,
mpp
validateRequestBody
boolean

Opt-in request-body gate (default off). When true, a request body that provably fails the endpoint's published request schema is refused with 400 BCK.ROUTER.0046 before anything is signed, reserved or charged, so you are not billed for a call the merchant would reject. Only a provably-invalid body is refused; a missing or unverifiable schema still pays (fail-open). Honoured on the buffered pay routes /router/route, /router/commerce/route and /router/subscription/route (the Commerce MCP pay_service forwards it to them); the streaming /proxy and /svc/:slug surfaces do not apply it. Fix the body to match the endpoint's published requestSchema (catalog service detail, or Commerce MCP get_service), or omit the flag.

Response

The relayed upstream response (status + body) plus the payment that was made.

status
number
required

The upstream HTTP status code that was relayed.

Example:

200

body
any
required

The upstream response body (parsed JSON when the upstream returned JSON, else a string).

Example:
paid
boolean
required

Whether a payment was made (false = the upstream was free).

Example:

true

payment
object

The payment made, when paid is true.