Router

Quote a Router call: the fee-inclusive price, rail and network, without paying

Ask what POST /route would charge for this call, WITHOUT paying it. The Router makes the same unpaid probe /route makes, reads the 402, selects the payment option exactly as a payment would (MPP first, then x402) and prices it with the Router fee — then stops. Nothing is signed, no credential is minted, no payment is recorded and no delegation budget is reserved, so no money moves. A quote is not free of consequence, though: the unpaid probe reaches the service (one that does not charge for the request performs it), and a quote spends the same per-key and per-service rate limit as a payment — so quote once per decision rather than repeating it.

Use it to decide whether ONE call fits the allocation you planned for it: compare fee.capChargedMicros (exact) or fee.capChargedCents (rounded up, the figure maxTotalCents is compared against) with what you want to spend, then call /route with maxTotalCents set to that figure so a price change between quote and call is refused rather than paid.

delegationId is optional. With it, the quote prices the options that delegation would select (an organization-wallet delegation pays only in its own currency, a card delegation pays over MPP-stripe, a recipient allowlist is enforced); without it, the options a personal crypto delegation would select. optionSet says which. A quote checks neither the remaining cap nor the wallet balance — those are the payment’s checks (BCK.ROUTER.0003, BCK.ROUTER.0009).

Provide the target url OR a catalog slug (+ optional path, search, method, headers, body), as on /route. A non-402 answer returns paymentRequired: false with the upstream status only — the upstream body and headers are never returned.

post/router/quote

Request

  • Base URL: https://api.sandbox.nevermined.app/api/v1
  • URL: https://api.sandbox.nevermined.app/api/v1/router/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

The delegation you would pay with. Optional. When given, the quote prices the options that delegation would select: an organization-wallet delegation pays only in its own currency, a card delegation pays over the MPP-stripe rail, and a recipient allowlist refuses a pay-to address it would refuse. Without it, the quote prices what a personal crypto (erc4337) delegation would select. optionSet in the response says which was used. Either way the quote checks neither the remaining cap nor the wallet balance.

Example request

{
  "url": "https://agent.example/api/resource",
  "slug": "webscrape-pro",
  "path": "scrape",
  "search": "flight_iata=AA217&limit=1",
  "credentialHeader": "Payment",
  "delegationId": "5e7481c3-e972-45bd-bdc5-a0b99c4de4a1"
}

Response

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

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.