---
name: pay-l402-endpoint
description: Pay an HTTP API that uses Lightning Labs L402. Use when a response is HTTP 402 and WWW-Authenticate uses the L402 scheme with a macaroon and a Lightning invoice.
license: CC-BY-4.0
metadata:
  author: agentpaywire
  version: "1.0"
---

# Pay an L402 endpoint

This is the HTTP binding from the Lightning Labs L402 specification. It is not a recommendation to buy or hold bitcoin.

## Steps

1. Send the request with no L402 credential.
2. If the status is 402, read `WWW-Authenticate`. The scheme is `L402`. It carries a base64 macaroon and a Lightning invoice.
3. Pay the invoice on Lightning and keep the payment preimage.
4. Encode the preimage as hex.
5. Retry the same request with one header:

```
Authorization: L402 <macaroon>:<preimage>
```

Put the base64 macaroon, a colon, then the hex preimage. If the challenge lists more than one macaroon, join those macaroons with commas before the colon.

## Checks

- Treat a macaroon or preimage that is not valid base64 or hex as a failed credential. Expect another 402.
- The credential is reused until the server revokes it and sends a new challenge.
- Send it only over TLS. The specification says the macaroon and preimage travel as cleartext.
- gRPC uses the same Authorization value. The challenge is carried in gRPC status details, with HTTP 200 and Grpc-Status 402.

Specification: https://docs.lightning.engineering/the-lightning-network/l402/protocol-specification

## Worked example

Agent Paywire serves this flow at https://api.agentpaywire.com/v1. The files on https://agentpaywire.com stay free. This is a technical example, not investment advice.

1. `GET https://api.agentpaywire.com/v1/search?q=bitcoin` with no Authorization header.
2. The response is HTTP 402. `WWW-Authenticate` carries an L402 macaroon and a BOLT11 invoice for 100 sats.
3. Pay the invoice on Lightning and keep the preimage. `sha256(preimage)` equals the payment hash.
4. Retry with:

```
Authorization: L402 <macaroon>:<preimage>
```

5. A settled call returns HTTP 200. `X-Credits-Remaining` starts at 100 and drops by one per paid request. The bundle lasts 30 days.

Discovery: https://agentpaywire.com/.well-known/l402