{"openapi":"3.1.0","info":{"title":"Universal 402 Gateway","summary":"Any wallet. Any paid API. Any rail.","description":"Pay for any 402-gated API with any agentic wallet. Pay the gateway over L402, x402 (USDC on Base/Solana), or MPP (Lightning or Tempo); it pays the upstream over whichever rail the upstream speaks and returns the response. See /docs for the full guide.","version":"1.0.0","x-guidance":"This is a payment-protocol gateway, not a fixed API: URL-encode any paid upstream API's full URL (encodeURIComponent, including its query string) and append it as one path segment — GET/POST /x402/{upstreamUrl} for x402 payment. Pay the 402 challenge and the gateway pays the upstream on your behalf and returns its response verbatim. GET /x402/ping is a fixed $0.01 test endpoint. Full guide: /docs.","contact":{"name":"Alby","email":"hello@getalby.com"}},"servers":[{"url":"https://l402.space"}],"paths":{"/{upstreamUrl}":{"description":"Shared gateway endpoint: offers L402 + x402 challenges plus a `paymentEndpoints` discovery map of every enabled rail's dedicated URL.","get":{"operationId":"shared_proxy_get","summary":"GET the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby"}],"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"security":[]},"post":{"operationId":"shared_proxy_post","summary":"POST the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fblockrun.ai%2Fapi%2Fv1%2Fchat%2Fcompletions"}],"requestBody":{"description":"Forwarded to the upstream byte-for-byte.","content":{"application/json":{"example":{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}}}},"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"security":[]}},"/l402/ping":{"get":{"operationId":"l402_ping","summary":"Paid ping — test that your l402 wallet can pay this gateway (~1 sat)","description":"Deterministic l402 endpoint: always returns a 402 challenge for a fixed minimum price. Settle it and receive {pong:true}. Ideal for wallet testing.","parameters":[{"name":"echo","in":"query","required":true,"description":"Any string; echoed back verbatim in the pong response.","schema":{"type":"string"},"example":"hello"}],"responses":{"200":{"description":"Payment settled/proven.","content":{"application/json":{"schema":{"type":"object","properties":{"pong":{"type":"boolean"},"rail":{"type":"string"},"echo":{"type":"string"},"network":{"type":"string"},"priceUsd":{"type":"number"},"amountSats":{"type":"integer"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"security":[]}},"/x402/ping":{"get":{"operationId":"x402_ping","summary":"Paid ping — test that your x402 wallet can pay this gateway ($0.01)","description":"Deterministic x402 endpoint: always returns a 402 challenge for a fixed minimum price. Settle it and receive {pong:true}. Ideal for wallet testing and registry probing.","parameters":[{"name":"echo","in":"query","required":true,"description":"Any string; echoed back verbatim in the pong response.","schema":{"type":"string"},"example":"hello"}],"x-payment-info":{"price":{"mode":"fixed","currency":"USD","amount":"0.010000"},"protocols":[{"x402":{}}]},"responses":{"200":{"description":"Payment settled/proven.","content":{"application/json":{"schema":{"type":"object","properties":{"pong":{"type":"boolean"},"rail":{"type":"string"},"echo":{"type":"string"},"network":{"type":"string"},"priceUsd":{"type":"number"},"amountSats":{"type":"integer"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}}}},"/mpp-lightning/ping":{"get":{"operationId":"mpp_lightning_ping","summary":"Paid ping — test that your mpp-lightning wallet can pay this gateway (~1 sat)","description":"Deterministic mpp-lightning endpoint: always returns a 402 challenge for a fixed minimum price. Settle it and receive {pong:true}. Ideal for wallet testing.","parameters":[{"name":"echo","in":"query","required":true,"description":"Any string; echoed back verbatim in the pong response.","schema":{"type":"string"},"example":"hello"}],"responses":{"200":{"description":"Payment settled/proven.","content":{"application/json":{"schema":{"type":"object","properties":{"pong":{"type":"boolean"},"rail":{"type":"string"},"echo":{"type":"string"},"network":{"type":"string"},"priceUsd":{"type":"number"},"amountSats":{"type":"integer"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"security":[]}},"/mpp-tempo/ping":{"get":{"operationId":"mpp_tempo_ping","summary":"Paid ping — test that your mpp-tempo wallet can pay this gateway ($0.01)","description":"Deterministic mpp-tempo endpoint: always returns a 402 challenge for a fixed minimum price. Settle it and receive {pong:true}. Ideal for wallet testing.","parameters":[{"name":"echo","in":"query","required":true,"description":"Any string; echoed back verbatim in the pong response.","schema":{"type":"string"},"example":"hello"}],"responses":{"200":{"description":"Payment settled/proven.","content":{"application/json":{"schema":{"type":"object","properties":{"pong":{"type":"boolean"},"rail":{"type":"string"},"echo":{"type":"string"},"network":{"type":"string"},"priceUsd":{"type":"number"},"amountSats":{"type":"integer"},"message":{"type":"string"}}}}}},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}}},"security":[]}},"/l402/{upstreamUrl}":{"description":"Dedicated l402 endpoint — offers ONLY the l402 payment challenge (no header folding).","get":{"operationId":"l402_proxy_get","summary":"GET the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby"}],"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"security":[]},"post":{"operationId":"l402_proxy_post","summary":"POST the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fblockrun.ai%2Fapi%2Fv1%2Fchat%2Fcompletions"}],"requestBody":{"description":"Forwarded to the upstream byte-for-byte.","content":{"application/json":{"example":{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}}}},"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"security":[]}},"/x402/{upstreamUrl}":{"description":"Dedicated x402 endpoint — offers ONLY the x402 payment challenge (no header folding).","get":{"operationId":"x402_proxy_get","summary":"GET the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby"}],"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.000001","max":"10.000000"},"protocols":[{"x402":{}}]}},"post":{"operationId":"x402_proxy_post","summary":"POST the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fblockrun.ai%2Fapi%2Fv1%2Fchat%2Fcompletions"}],"requestBody":{"description":"Forwarded to the upstream byte-for-byte.","content":{"application/json":{"example":{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}}}},"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"x-payment-info":{"price":{"mode":"dynamic","currency":"USD","min":"0.000001","max":"10.000000"},"protocols":[{"x402":{}}]}}},"/mpp-lightning/{upstreamUrl}":{"description":"Dedicated mpp-lightning endpoint — offers ONLY the mpp-lightning payment challenge (no header folding).","get":{"operationId":"mpp_lightning_proxy_get","summary":"GET the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby"}],"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"security":[]},"post":{"operationId":"mpp_lightning_proxy_post","summary":"POST the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fblockrun.ai%2Fapi%2Fv1%2Fchat%2Fcompletions"}],"requestBody":{"description":"Forwarded to the upstream byte-for-byte.","content":{"application/json":{"example":{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}}}},"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"security":[]}},"/mpp-tempo/{upstreamUrl}":{"description":"Dedicated mpp-tempo endpoint — offers ONLY the mpp-tempo payment challenge (no header folding).","get":{"operationId":"mpp_tempo_proxy_get","summary":"GET the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby"}],"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"security":[]},"post":{"operationId":"mpp_tempo_proxy_post","summary":"POST the upstream URL through the gateway","description":"Forwards your request (method + body unchanged) to the decoded upstream URL. Free upstreams are proxied directly; paid upstreams return 402 until you pay the gateway over an offered inbound rail, after which the gateway pays the upstream on your behalf and returns its response. PUT/PATCH/DELETE/HEAD are forwarded the same way (omitted here so registry probes stick to method-appropriate examples).","parameters":[{"name":"upstreamUrl","in":"path","required":true,"description":"The FULL upstream URL (including query string), URL-encoded as one path segment with encodeURIComponent. Example: https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby","schema":{"type":"string"},"example":"https%3A%2F%2Fblockrun.ai%2Fapi%2Fv1%2Fchat%2Fcompletions"}],"requestBody":{"description":"Forwarded to the upstream byte-for-byte.","content":{"application/json":{"example":{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}}}},"responses":{"200":{"description":"The upstream's response, delivered after payment (or free passthrough).","content":{"application/json":{"schema":{"type":"object","description":"The upstream API's own response body, returned verbatim — its shape is whatever the upstream returns (JSON shown as the common case; non-JSON bodies pass through unchanged with the upstream's content-type).","additionalProperties":true}}}},"400":{"description":"Malformed target URL or payment credential."},"402":{"description":"Payment required. Challenge headers: `WWW-Authenticate` (L402 / MPP `Payment` schemes) and/or the base64-JSON `payment-required` header (x402). Pay over your rail and retry with the rail's credential header (`Authorization: L402 …`, `Authorization: Payment …`, or `payment-signature`).","headers":{"WWW-Authenticate":{"description":"L402 or MPP `Payment` challenge(s), when those rails are offered.","schema":{"type":"string"}},"payment-required":{"description":"Base64-encoded x402 v2 PaymentRequired JSON (accepts array), when x402 is offered.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequired"}}}},"503":{"description":"Gateway temporarily unable to issue a payment challenge."}},"security":[]}},"/docs":{"get":{"summary":"Agent-readable API docs (markdown)","responses":{"200":{"description":"Markdown documentation.","content":{"text/markdown":{"schema":{"type":"string"}}}}},"security":[]}},"/llms.txt":{"get":{"summary":"Quick-start guide for AI agents","responses":{"200":{"description":"Plain-text guide.","content":{"text/plain":{"schema":{"type":"string"}}}}},"security":[]}},"/openapi.json":{"get":{"summary":"This OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 spec.","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[]}},"/api/info":{"get":{"summary":"Service description, enabled inbound rails, funded outbound networks","responses":{"200":{"description":"Service info.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Info"}}}}},"security":[]}},"/api/services":{"get":{"summary":"Live directory of paid APIs seen by the gateway","description":"Per-host aggregates: docs URL, price range, transaction count, USD volume, last activity, and delivery reliability (2xx deliveries / payments received). No raw recorded URLs — hosts only.","responses":{"200":{"description":"Service directory.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Services"}}}}},"security":[]}},"/api/stats":{"get":{"summary":"Aggregate gateway statistics","responses":{"200":{"description":"Overall stats + 30-day daily series.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Stats"}}}}},"security":[]}},"/health":{"get":{"operationId":"health","summary":"Liveness check","responses":{"200":{"description":"OK.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}}},"security":[]}},"/health/balances":{"get":{"operationId":"health_balances","summary":"Spend-float monitor — 503 when any funded network's balance needs a topup","description":"Reads every spend float this deployment uses (per FUNDED_NETWORKS: Lightning send wallet, USDC on Base/Solana, Tempo USDC.e) and returns 503 with `reasons` (\"needs topup on <network>\") when any is below the minimum. Point an uptime monitor here. The per-network amounts (`floats`, `totalBalanceUsd`) are operator-only: included only with a valid `?key`.","parameters":[{"name":"key","in":"query","required":false,"description":"Operator access key (HEALTH_KEY). When valid, the response includes the per-network `floats` and `totalBalanceUsd`.","schema":{"type":"string"}}],"responses":{"200":{"description":"All monitored floats are above the minimum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalancesHealth"}}}},"503":{"description":"One or more floats need a topup (see `reasons`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalancesHealth"}}}}},"security":[]}}},"components":{"schemas":{"PaymentRequired":{"type":"object","properties":{"error":{"type":"string","const":"Payment required"},"amountSats":{"type":"integer","description":"Price in satoshis (Lightning rails)."},"priceUsd":{"type":["number","null"],"description":"Price in USD (on-chain rails)."},"rail":{"type":"string","description":"The OUTBOUND rail the gateway will pay the upstream over."},"network":{"type":["string","null"]},"upstream":{"type":"string","description":"The decoded upstream URL this challenge is bound to."},"paymentEndpoints":{"type":"array","description":"Shared endpoint only: every enabled inbound rail with its dedicated single-protocol URL and indicative price. A hint layer — wallets auto-pay off the challenge headers.","items":{"type":"object"}}}},"Info":{"type":"object","properties":{"service":{"type":"string"},"usage":{"type":"string"},"docs":{"type":"string"},"openapi":{"type":"string"},"inboundRails":{"type":"array","items":{"type":"string"}},"fundedNetworks":{"type":"array","items":{"type":"string"}},"spendWallet":{"type":"object"}}},"Services":{"type":"object","properties":{"services":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string"},"docs":{"type":["string","null"],"description":"The service's own API documentation URL (curated), null when unknown."},"desc":{"type":["string","null"],"description":"One-line description of the service (curated), null when unknown."},"network":{"type":["string","null"]},"networkLabel":{"type":["string","null"]},"txCount":{"type":"integer"},"volumeUsd":{"type":"number"},"priceMin":{"type":["number","null"]},"priceMax":{"type":["number","null"]},"lastActivity":{"type":["integer","null"]},"activity":{"type":"array","items":{"type":"integer"}},"paymentsReceived":{"type":"integer"},"deliveries":{"type":"integer"},"reliability":{"type":["number","null"],"description":"deliveries / paymentsReceived, null until any payment received."}}}}}},"BalancesHealth":{"type":"object","properties":{"ok":{"type":"boolean"},"minUsd":{"type":"number"},"reasons":{"type":"array","items":{"type":"string"},"description":"Present when ok=false: \"needs topup on <network>\" per low float."},"unreadable":{"type":"array","items":{"type":"string"},"description":"Networks whose balance could not be read (never fails the check)."},"totalBalanceUsd":{"type":"number","description":"Sum of all readable floats in USD. Only present with a valid ?key."},"floats":{"type":"array","description":"Per-network balances. Only present with a valid ?key.","items":{"type":"object","properties":{"network":{"type":"string"},"label":{"type":"string"},"usd":{"type":["number","null"]},"sats":{"type":["integer","null"]}}}}}},"Stats":{"type":"object","properties":{"transactions":{"type":"integer"},"volumeUsd":{"type":"number"},"sats":{"type":"integer"},"endpoints":{"type":"integer"},"domains":{"type":"integer"},"series":{"type":"object","properties":{"transactions":{"type":"array","items":{"type":"integer"}},"volumeUsd":{"type":"array","items":{"type":"number"}},"endpoints":{"type":"array","items":{"type":"integer"}},"domains":{"type":"array","items":{"type":"integer"}}}}}}}}}