# Universal 402 Gateway — API docs

**Any wallet. Any paid API. Any rail.**

This gateway lets you pay for any `402 Payment Required` API with whatever payment rail your
wallet speaks. You pay the gateway over YOUR rail; the gateway pays the upstream API on your
behalf over whichever rail THAT API speaks (x402/USDC, MPP Tempo, MPP Lightning, or L402), then
returns the upstream response to you.

No signup, no API key. The only interface is the URL scheme below plus standard 402 payment
protocols.

## URL scheme

```
https://l402.space/<url-encoded-upstream-url>              # shared endpoint (L402 + x402 challenges)
https://l402.space/<protocol>/<url-encoded-upstream-url>   # dedicated single-protocol endpoints
```

- URL-encode the FULL upstream URL including its query string (`encodeURIComponent`) and append
  it as one path segment.
- Your HTTP method and request body are forwarded to the upstream unchanged.
- Example: `https://l402.space/https%3A%2F%2Fx402.twit.sh%2Ftweets%2Fuser%3Fusername%3Dgetalby`
  proxies `https://x402.twit.sh/tweets/user?username=getalby`.
- If the upstream is FREE (no 402), the gateway simply proxies it — no payment involved.

## Payment flow

1. Send your request with no payment. If the upstream charges, you get `402` back with one or
   more payment challenges (headers below) and a JSON body stating the price
   (`amountSats`, `priceUsd`) and the `paymentEndpoints` discovery map (shared endpoint only) —
   every enabled inbound rail with its dedicated URL and indicative price.
2. Pay over your rail and retry the same URL with the rail's credential header.
3. The gateway pays the upstream and returns its response. Status/body are the upstream's own.

**Receipts are reusable.** One payment buys one upstream settlement, but the credential you
retried with keeps working for follow-up requests that the SAME upstream payment covers (e.g.
polling an async job, or a prepaid upstream's multiple queries) — replaying it never pays twice.
When the underlying upstream credential is spent, you get a clean `402` asking you to obtain a
new payment.

## Inbound rails enabled on this deployment: l402, x402, mpp-lightning, mpp-tempo

### l402 — Lightning (L402 protocol)

Dedicated endpoint: `https://l402.space/l402/<url-encoded-upstream-url>`

Challenge: `WWW-Authenticate: L402 token="<macaroon>", invoice="<bolt11>"`.
Pay the BOLT11 invoice with any Lightning wallet, then retry the SAME URL with
`Authorization: L402 <token>:<preimage>` (preimage = lowercase 64-char hex from the payment).

### x402 — USDC on Base and/or Solana

Dedicated endpoint: `https://l402.space/x402/<url-encoded-upstream-url>`

Challenge: the base64-JSON `payment-required` RESPONSE header (v2; `x-payment-required` is a v1 alias).
Its `accepts` array lists every network we accept (pick yours). Sign the payment and retry with the
base64 `payment-signature` REQUEST header (v1 alias: `x-payment`). Standard x402 clients handle this automatically.

### mpp-lightning — Lightning (MPP `Payment` scheme)

Dedicated endpoint: `https://l402.space/mpp-lightning/<url-encoded-upstream-url>`

Challenge: `WWW-Authenticate: Payment method="lightning", id="…", invoice="<bolt11>", request="<base64url>"`.
Pay the BOLT11 invoice, then retry with `Authorization: Payment <base64url(JSON{challenge, payload:{preimage}})>`,
echoing the challenge fields verbatim (including the raw `request` string).

### mpp-tempo — TIP-20 stablecoin on Tempo (MPP `Payment` scheme)

Dedicated endpoint: `https://l402.space/mpp-tempo/<url-encoded-upstream-url>`

Challenge: `WWW-Authenticate: Payment method="tempo" …` (MPP envelope, signed challenge).
Sign the Tempo transaction per the challenge and retry with `Authorization: Payment <base64url-credential>`.
Standard mppx clients handle this automatically.

## Pricing

The price quoted in the 402 challenge is the upstream's own price plus the gateway markup and a
routing fee, converted to your rail's currency. The quote in the challenge is authoritative —
you never pay more than it states.

## Machine-readable endpoints

| Endpoint | What it returns |
| --- | --- |
| `GET https://l402.space/docs` | This document (markdown) |
| `GET https://l402.space/openapi.json` | OpenAPI 3.1 spec for this gateway |
| `GET https://l402.space/llms.txt` | Quick-start guide for AI agents |
| `GET https://l402.space/api/info` | Service description, enabled rails, funded networks |
| `GET https://l402.space/api/services` | Live directory of paid APIs seen by the gateway (per-host docs URL, price range, volume, delivery reliability) |
| `GET https://l402.space/api/stats` | Aggregate gateway stats (transactions, volume, endpoints, domains) |
| `GET https://l402.space/<protocol>/ping` | PAID ping per rail (~1 sat on the Lightning rails, $0.01 on-chain): settle the challenge, get `{pong:true}` — test that your wallet can pay this gateway (e.g. `/x402/ping`, `/l402/ping`) |
| `GET https://l402.space/health` | Liveness check |
| `GET https://l402.space/health/balances` | Spend-float monitor: 503 + `"needs topup on <network>"` reasons when any funded float (Lightning, Base/Solana USDC, Tempo USDC.e) runs low |

## Errors

- `402` — payment required (or a previously used receipt is spent: pay again).
- `400` — malformed credential/target URL.
- `404`-`5xx` from the upstream are passed through after delivery.
- `503` — the gateway temporarily cannot issue a challenge; retry later.

## Contact

Questions, issues, or a service to list: hello@getalby.com