Skip to main content
POST
Quote a Router call from your commerce grant, without paying (OAuth)
Rolling out. This route ships in the first API release after 1.49. Until your environment runs it, the route answers 404: bound the price with maxTotalCents on POST /router/commerce/route instead.

Authorizations

​
Authorization
string
header
required

Your Nevermined API Key (starts with 'nvm:'). Get one at nevermined.app under Settings > API Keys.

Body

application/json
​
url
string

Absolute upstream URL to route to (http/https only). Provide EXACTLY ONE of url or slug — both together is a 400. Use slug for a cataloged service (the opaque broker); url is for an off-catalog target you already hold the URL of.

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.

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). An @ is allowed (e.g. an /inbox/foo@bar.com route) — it stays in the path and the composed origin is re-asserted against the resolved host. Ignored when url is used.

Example:

"scrape"

​
search
string

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.

​
credentialHeader
string

Header the Router should carry the minted payment credential in on the paid hop. Send this only when the service needs its own auth AND a payment: the MPP rails carry their credential in Authorization, which is also where your merchant auth goes, and rather than silently replacing yours the Router refuses the call with BCK.ROUTER.0021. Naming the header the service documents for its credential (a separate Payment header is the common one) leaves your Authorization untouched. It is honoured on every rail, so do not set it by default: putting the credential somewhere the service does not read makes the paid hop fail.

Maximum string length: 64
Example:

"Payment"

​
delegationId
string

Must NOT be sent. The quote prices the delegation your grant is pinned to — the one the user consented to and capped. Supplying one is refused rather than ignored; use POST /api/v1/router/quote with a plain API key to price a delegation of your choice.

​
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

Response

The quote. paymentRequired: false means the upstream did not ask for payment; otherwise settlement and fee are what /commerce/route would pay and reserve against the grant.

​
paymentRequired
boolean
required

Whether the upstream asked for payment (answered 402). false means the call is free, or the upstream answered with an error before any payment challenge: read upstreamStatus, and expect every priced field below to be absent.

Example:

true

​
upstreamStatus
number
required

The status the upstream answered the unpaid probe with — 402 when paymentRequired is true. The upstream body and headers are never returned.

Example:

402

​
optionSet
enum<string>

Which set of payment options was priced. delegation: the options the supplied delegationId would select. deployment: no delegation was supplied, so the options a personal crypto (erc4337) delegation would select on this deployment. Present when paymentRequired is true.

Available options:
delegation,
deployment
Example:

"deployment"

​
delegationId
string | null

The delegation whose options were priced, or null for the deployment option set. Present when paymentRequired is true.

Example:

null

​
protocol
enum<string>

The payment protocol the Router would pay with — the same auto-detection as /route (MPP first, then x402). Present when paymentRequired is true.

Available options:
x402,
mpp
Example:

"x402"

​
x402Version
number

The x402 version that would be used, on the x402 rail.

Example:

2

​
settlement
object

What the payment would pay the merchant: the rail (scheme), network, asset, the merchant leg in atomic units (amount) and in cents (approxCents). The same descriptor /route returns as payment.settlement. Present when paymentRequired is true.

​
fee
object

The Router fee and the fee-inclusive total the payment would reserve against the delegation cap — capChargedMicros exactly, capChargedCents rounded up to a whole cent, which is the figure maxTotalCents is compared against. The same object /route returns as payment.fee. Present when paymentRequired is true.

​
sessionDeposit
object

What the call would move into a deposit, when the merchant is paid over an MPP session (settlement.scheme is session): a one-way payment channel whose deposit leaves the wallet at the first call, however small the call, and pays for the calls out of it. Absent on every other rail.