Router

Route and pay using the delegation from your commerce grant (mode B, OAuth)

The OAuth counterpart of POST /api/v1/router/route, for a credential minted from a commerce authorization. Identical behaviour and identical response — with one difference: you do not choose the delegation. It is derived from your grant: the capped, expiring mandate the user approved when they connected you. Sending a delegationId is refused, not ignored.

The cap, its expiry, and the user revoking the grant are the boundary on what you can spend. The routing fee is drawn from that same cap, in addition to each merchant’s price.

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

post/router/commerce/route

Request

  • Base URL: https://api.sandbox.nevermined.app/api/v1
  • URL: https://api.sandbox.nevermined.app/api/v1/router/commerce/route
  • 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, so //, @, .. and an embedded absolute URL are rejected (400). Ignored when url is used.

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
protocol'x402' | 'mpp'

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

requestIdstring 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 request

{
  "url": "https://agent.example/api/resource",
  "slug": "webscrape-pro",
  "path": "scrape",
  "requestId": "order-1234"
}

Response

Upstream response, relayed.

statusnumber required

The upstream HTTP status code that was relayed.

bodyunknown required
paidboolean required

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

Example response

{
  "status": 200,
  "body": {
    "ok": true,
    "data": "the paid resource"
  },
  "paid": true,
  "payment": {
    "resultUrl": "/api/v1/router/payments/b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13/result",
    "paymentId": "b1f9c2e4-3d5a-4c7e-9f21-6a8b0c4d2e13",
    "settlement": {
      "recipient": "0x209693Bc6afc0C5328bA36FaF03C514EF312287C",
      "amount": "1000",
      "asset": "USDC",
      "network": "base-sepolia",
      "approxCents": "1",
      "scheme": "exact"
    },
    "fee": {
      "amount": "0",
      "cents": "0",
      "capChargedCents": "1",
      "capChargedMicros": "2040"
    },
    "status": "Settled"
  }
}

Changes

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