Router

Route a request through the Router, paying the agent’s 402 and relaying the reply (mode B)

Hand the Router the request you want made to an upstream x402 agent; it probes, pays any 402 with your Delegation (same engine as POST /router/payments), and relays the agent’s response in ONE call — you never see the 402 or handle the credential yourself.

Prerequisite: a Delegation id (POST /api/v1/delegation/create, provider erc4337).

Provide the target url (+ optional method, headers, body). A free (non-402) upstream is relayed unchanged with paid=false and no payment. requestId is REQUIRED (the Router pays automatically, so a retry must be idempotency-keyed); a duplicate returns 409 with the original paymentId (from API 1.48, the first purchase's retained result instead — see GET /router/payments/{id}/result).

For LARGE or STREAMED responses, a transparent streaming variant exists at ALL /api/v1/router/proxy: point your HTTP client at it with headers X-Router-Target-Url and X-Router-Delegation-Id (optional X-Router-Upstream-Authorization for the agent’s own auth). Method/body/headers pass through and the response streams back, with payment metadata in X-Router-Payment-Id, X-Router-Payment-Status, and X-Router-Tx-Hash response headers. Use this JSON endpoint when you want a single structured result instead.

post/router/route

Request

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

Request body

delegationIdstring required

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

urlstring

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

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

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). A catalog template placeholder ({jobId}, :id) must be filled with a real value, or the call is refused (400). 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
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",
  "search": "flight_iata=AA217&limit=1",
  "requestId": "order-1234"
}

Response

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

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.