Router

Quote a Router call from your commerce grant, without paying (OAuth)

The OAuth counterpart of POST /api/v1/router/quote, for a credential minted from a commerce authorization. Identical behaviour and identical response, with one difference: you do not choose the delegation. The quote prices the options the delegation your grant is pinned to would select, so it is what POST /api/v1/router/commerce/route would charge for the same call. Sending a delegationId is refused, not ignored.

Nothing is signed, no credential is minted, no payment is recorded and no budget is reserved. The Router still makes the unpaid request to the service, and the quote spends the same per-key and per-service rate budgets as a payment. Compare fee.capChargedCents with what you want to spend, then call /commerce/route with maxTotalCents set to that figure.

A plain (non-OAuth) API key cannot use this route: it has no grant to price. Use POST /api/v1/router/quote and name your own delegationId instead.

post/router/commerce/quote

Request

  • Base URL: https://api.sandbox.nevermined.app/api/v1
  • URL: https://api.sandbox.nevermined.app/api/v1/router/commerce/quote
  • Auth: HTTP bearer

Request body

urlstring

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.

slugstring

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.

pathstring

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.

searchstring

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.

method'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'

HTTP method to use for the upstream request.

headersobject

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

bodyunknown
credentialHeaderstring

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.

delegationIdstring

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.

Example request

{
  "url": "https://agent.example/api/resource",
  "slug": "webscrape-pro",
  "path": "scrape",
  "search": "flight_iata=AA217&limit=1",
  "credentialHeader": "Payment"
}

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.

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

upstreamStatusnumber required

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

optionSet'delegation' | 'deployment'

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.

delegationIdstring nullable

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

protocol'x402' | 'mpp'

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

x402Versionnumber

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

Example response

{
  "paymentRequired": true,
  "upstreamStatus": 402,
  "optionSet": "deployment",
  "protocol": "x402",
  "x402Version": 2,
  "settlement": {
    "recipient": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
    "amount": "1000",
    "asset": "USDC",
    "network": "base-sepolia",
    "approxCents": "1",
    "scheme": "exact"
  },
  "fee": {
    "amount": "0",
    "cents": "0",
    "capChargedCents": "1",
    "capChargedMicros": "2040"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.