{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/nevermined-app/json-schema/nevermined-app-commerce-route-request-dto-schema.json",
  "title": "CommerceRouteRequestDto",
  "x-generated": "2026-11-20",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/nevermined-app-openapi.json#/components/schemas/CommerceRouteRequestDto",
  "type": "object",
  "properties": {
    "revealBuyerIdentity": {
      "type": "boolean",
      "description": "Consent to reveal delegation, organization and buyer-declared agent attribution to an opted-in listing on this paid request. Plain API keys only.",
      "default": false
    },
    "quoteId": {
      "type": "string",
      "description": "Opaque id returned by POST /api/v1/router/quote for this exact call. While it is unexpired, the Router pays the sealed protocol challenge and fee-inclusive figure instead of accepting a changed merchant quote. The target, method, headers, body, credential header and delegation must match the quoted request. maxTotalCents remains an independent spend ceiling."
    },
    "url": {
      "type": "string",
      "description": "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."
    },
    "slug": {
      "type": "string",
      "description": "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`."
    },
    "path": {
      "type": "string",
      "description": "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."
    },
    "search": {
      "type": "string",
      "description": "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.",
      "maxLength": 2048
    },
    "method": {
      "type": "string",
      "description": "HTTP method to use for the upstream request.",
      "enum": [
        "GET",
        "POST",
        "PUT",
        "PATCH",
        "DELETE"
      ],
      "default": "GET"
    },
    "headers": {
      "type": "object",
      "description": "Headers to forward to the upstream (e.g. the agent’s own auth). Optional."
    },
    "body": {
      "type": "object",
      "description": "Request body to forward (JSON). Optional."
    },
    "credentialHeader": {
      "type": "string",
      "description": "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.",
      "maxLength": 64
    },
    "maxTotalCents": {
      "type": "number",
      "description": "Maximum whole cents this single call may reserve against the delegation cap, including the Router buyer fee and sub-cent rounding. A larger 402 quote is refused before anything is signed and before a payment record or cap decrement. 0 refuses positive quotes. Reuse the same requestId on retries.",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "protocol": {
      "type": "string",
      "description": "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).",
      "enum": [
        "x402",
        "mpp"
      ],
      "default": "x402"
    },
    "requireProtocol": {
      "type": "string",
      "description": "BINDING payment-rail pin (contrast the advisory `protocol` above). When set, the Router pays ONLY on this rail: if the service offers both rails it uses this one, and if the service does not offer it at all the call is REFUSED (409 BCK.ROUTER.0045) before anything is signed, minted or reserved — it never falls back to the other rail. Use it when funds must stay on one chain/rail (a buyer who holds only Base USDC, say). Omit it and the Router auto-detects the rail from the 402: MPP first, then x402 — and, for a crypto delegation, a 402 offering both rails whose MPP challenge's terms the Router does not accept (an unsupported method, intent or term), or that the paying wallet cannot sign (an MPP `evm` charge for an EIP-7702 wallet), is paid on its x402 offer; insufficient funds never switch rails. A `quoteId` that was quoted on the other rail is refused (409 BCK.ROUTER.0033); re-quote on the pinned rail.",
      "enum": [
        "x402",
        "mpp"
      ]
    },
    "validateRequestBody": {
      "type": "boolean",
      "description": "Opt-in request-body check (default false). When true, the Router validates your request body against the request schema the service published for the endpoint, and if the body PROVABLY fails that schema the call is REFUSED (400 BCK.ROUTER.0046) before anything is signed, minted, reserved or charged — so you are not billed for a call that would have failed. It only refuses on a definite mismatch against a well-sourced schema: an endpoint with no published schema (or only a weak/unreadable one) is never refused, and a body that matches pays as normal. Omit it (or set false) and the call is never refused on this basis.",
      "default": false
    },
    "requestId": {
      "type": "string",
      "description": "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). From API 1.48, the JSON route surfaces replay a retained ready JSON route response or return the same 202 while pending, without paying again. Replay matches the slug (not its path/search) or raw URL and the funding source (delegation versus subscription); it does not compare method, body or delegationId. Reuse an id only for the same purchase. With a pre-1.48 pin, a failed, expired or missing result, an unreadable stored response, a result from the other surface, or a different slug/raw URL or funding source, the retry follows normal validation and probing instead. If it reaches duplicate detection (usually after another merchant 402), it returns 409 BCK.ROUTER.0002 with the original `paymentId` in `params`. Other replies describe only this attempt, not the original payment. A missing result may mean the original call is still running. Read the durable record with `GET /api/v1/router/payments?requestId=<original-requestId>` (URL-encode the original key); do not change requestId to recover a missing response: a fresh id can pay again, including the routing fee. In particular, `paid: false` on a JSON retry does not mean the original call was unpaid. Before the sync budget (45 s) expires, a running JSON call may not have a retained row yet."
    },
    "delegationId": {
      "type": "string",
      "description": "Must NOT be sent. The delegation is derived from your grant — the one the user consented to and capped. Supplying one is refused rather than ignored; use POST /api/v1/router/route with a plain API key to choose a delegation per call."
    }
  },
  "required": [
    "requestId"
  ]
}