# Simple 402 Payments

Deggen (<d.kellenschwiler@bsvassociation.org>)

## Abstract

This BRC specifies a lightweight protocol for monetizing HTTP resources using the `402 Payment Required` status code and a set of custom HTTP headers. A server advertises a price and its identity key in the 402 response. A client constructs a [BRC-29](https://bsv.brc.dev/payments/0029) payment transaction, encodes it in [BRC-95 BEEF](https://bsv.brc.dev/transactions/0095) format, and retransmits the original request with payment headers. The server validates the transaction, internalizes the payment via its wallet, and serves the protected resource. The protocol is stateless from the server's perspective: each request is independently authorized by the presence or absence of valid payment headers.

## Motivation

HTTP 402 was reserved in the original HTTP/1.1 specification (RFC 7231) for future use in micropayment schemes, but no standard mechanism was adopted. Meanwhile, BSV transaction fees are low enough to make per-request payments practical for content such as articles, API calls, and media.

Existing BSV payment protocols ([BRC-27](https://bsv.brc.dev/payments/0027) Direct Payment Protocol, [BRC-105](https://bsv.brc.dev/payments/0105) HTTP Service Monetization Framework, [BRC-120](https://bsv.brc.dev/payments/0120) x402) each define comprehensive negotiation mechanisms. This BRC targets a simpler use case: a client that already holds a [BRC-42](https://bsv.brc.dev/key-derivation/0042)-compatible wallet pays for an HTTP resource in a single round-trip pair (one 402 response, one paid request) using only standard HTTP headers and [BRC-29](https://bsv.brc.dev/payments/0029) payment remittance.

Design goals:

1. **Minimal surface area** -- no JSON body negotiation, no challenge tokens, no session state.
2. **BRC-29 compatible** -- payment derivation uses the same protocol ID (`2-3241645161d8`), derivation prefix, and derivation suffix scheme defined in [BRC-29](https://bsv.brc.dev/payments/0029).
3. **BEEF transport** -- the payment transaction is transmitted as a base64-encoded [BRC-95 BEEF](https://bsv.brc.dev/transactions/0095) blob in a single header, carrying full SPV ancestry.
4. **Stateless verification** -- the server validates and internalizes the payment on each request independently. Caching of paid status is a client-side optimization, not a protocol requirement.

## Specification

### 1. Header Namespace

All protocol headers use the prefix `x-bsv-`. The following headers are defined:

| Header         | Direction        | Description                                                                                             |
| -------------- | ---------------- | ------------------------------------------------------------------------------------------------------- |
| `x-bsv-sats`   | Server to client | Required satoshi amount for the resource.                                                               |
| `x-bsv-server` | Server to client | Server's compressed, hex-encoded secp256k1 identity public key.                                         |
| `x-bsv-beef`   | Client to server | Base64-encoded [BRC-95 BEEF](https://bsv.brc.dev/transactions/0095) transaction containing the payment. |
| `x-bsv-sender` | Client to server | Client's compressed, hex-encoded secp256k1 identity public key.                                         |
| `x-bsv-nonce`  | Client to server | Base64-encoded [BRC-29](https://bsv.brc.dev/payments/0029) derivation prefix for the payment.           |
| `x-bsv-time`   | Client to server | Derivation suffix: a Unix millisecond timestamp as a decimal string (see Section 3).                    |
| `x-bsv-vout`   | Client to server | Output index (zero-based, decimal string) of the payment output within the transaction.                 |

### 2. Server: 402 Response

When a client requests a protected resource without payment headers, the server MUST respond with:

* HTTP status `402 Payment Required`
* Header `x-bsv-sats` set to the required price in satoshis
* Header `x-bsv-server` set to the server's identity public key
* An empty body (the server MUST NOT serve the protected content)

The server SHOULD also set appropriate CORS headers to expose `x-bsv-sats` and `x-bsv-server` to browser-based clients:

```
Access-Control-Expose-Headers: x-bsv-sats, x-bsv-server
```

### 3. Client: Payment Construction

Upon receiving a 402 response, the client:

1. Reads `x-bsv-sats` to determine the required payment amount.
2. Reads `x-bsv-server` to obtain the server's identity key (the payment recipient).
3. Generates a derivation prefix as specified in [BRC-29](https://bsv.brc.dev/payments/0029).
4. Sets the time value to the current Unix timestamp in milliseconds as a decimal string (e.g. `1719500000000`). This serves as both a freshness indicator for the server and, after base64 encoding, the derivation suffix required by [BRC-29](https://bsv.brc.dev/payments/0029).
5. Base64-encodes the time value for use as the derivation suffix in key derivation. Uses [BRC-42](https://bsv.brc.dev/key-derivation/0042) key derivation with the invoice number format `2-3241645161d8-<nonce> <base64(time)>` to derive the recipient's public key.
6. Constructs a BSV transaction with a P2PKH output of the required satoshi amount locked to the derived public key.
7. Serializes the transaction in [BRC-95 BEEF](https://bsv.brc.dev/transactions/0095) format and encodes it as base64.

### 4. Client: Paid Request

The client retransmits the original HTTP request with the following headers added:

| Header         | Value                                               |
| -------------- | --------------------------------------------------- |
| `x-bsv-beef`   | Base64-encoded BEEF transaction                     |
| `x-bsv-sender` | Client's identity public key (hex)                  |
| `x-bsv-nonce`  | Base64-encoded derivation prefix                    |
| `x-bsv-time`   | Unix millisecond timestamp (decimal string)         |
| `x-bsv-vout`   | Output index of the payment output (decimal string) |

The request method, URL, and any other headers or body MUST be identical to the original request.

### 5. Server: Payment Validation

Upon receiving a request with payment headers, the server MUST:

1. Verify that all five client headers (`x-bsv-beef`, `x-bsv-sender`, `x-bsv-nonce`, `x-bsv-time`, `x-bsv-vout`) are present. If any are missing, respond with 402.
2. Parse `x-bsv-time` as a Unix millisecond timestamp. If the value is not a valid number, or differs from the server's current time by more than 30 seconds, the server MUST reject the request and respond with 402. This prevents capture and delayed replay of payment headers.
3. Decode the BEEF transaction from base64.
4. Internalize the payment using the wallet's `internalizeAction` operation with:
   * The decoded transaction bytes
   * Protocol: `wallet payment`
   * Payment remittance containing `derivationPrefix` (from `x-bsv-nonce`), `derivationSuffix` (base64-encoded from the raw `x-bsv-time` value), and `senderIdentityKey` (from `x-bsv-sender`)
   * Output index from `x-bsv-vout`
5. Check the `isMerge` field of the internalization result. If `isMerge` is `true`, the transaction was already known to the wallet, indicating a replayed payment. The server MUST reject the request and respond with 402.
6. If internalization succeeds and `isMerge` is `false`, serve the protected resource with HTTP status `200`.
7. If internalization fails (invalid transaction, insufficient amount, invalid derivation, or SPV failure), respond with 402.

The server MUST NOT maintain per-client payment state. Each request is independently authorized. Replay protection is provided by two mechanisms: the timestamp freshness check on `x-bsv-time` (preventing delayed replay), and the wallet's `isMerge` flag (preventing immediate replay of the same transaction).

### 6. Client: Caching (Optional)

A client MAY cache the set of URLs for which payment has been accepted and skip the 402 round-trip on subsequent requests to the same URL. This is a client-side optimization. The server makes no guarantees about how long a payment remains valid.

### 7. Error Handling

* If the server cannot initialize its wallet, it SHOULD return `500 Internal Server Error`.
* If payment validation throws an exception, the server SHOULD return `402` to allow the client to retry.
* A client that receives a `402` after submitting payment headers SHOULD NOT automatically retry without user confirmation to avoid double-spending.

## Implementations

1. **`@bsv/402-pay` (npm package)** -- A production npm package providing both server middleware and client fetch wrapper. Install with `npm install @bsv/402-pay`. Source: [github.com/bsv-blockchain/402-pay](https://github.com/bsv-blockchain/402-pay).

   ```ts
   // Server (Express)
   import { createPaymentMiddleware } from '@bsv/402-pay/server'
   app.get('/content/:id', createPaymentMiddleware({ wallet, calculatePrice: () => 100 }), handler)

   // Client
   import { create402Fetch } from '@bsv/402-pay/client'
   const fetch402 = create402Fetch({ wallet })
   const res = await fetch402('https://example.com/content/foo')
   ```
2. **Server (Express/Node.js)** -- A reference server using `@bsv/402-pay` is available at [github.com/bsv-blockchain-demos/402-articles](https://github.com/bsv-blockchain-demos/402-articles).
3. **Client (React Native WebView)** -- A reference client implementation intercepts 402 responses in a fetch wrapper, constructs payment headers using a [BRC-42](https://bsv.brc.dev/key-derivation/0042)-compatible wallet, and retransmits the request. Source: [github.com/bsv-blockchain/bsv-browser](https://github.com/bsv-blockchain/bsv-browser).
4. **Client (Browser Extension)** -- A Chromium extension that intercepts 402 responses via the declarativeNetRequest API and retransmits with payment headers. Source: [github.com/bsv-blockchain/402-extension](https://github.com/bsv-blockchain/402-extension).
5. **Wallet Compatibility** -- Any wallet implementing the `WalletInterface` from `@bsv/sdk` with support for `internalizeAction` and `getPublicKey({ identityKey: true })` can be used on either side of the protocol.

## References

* [BRC-29: Simple Authenticated BSV P2PKH Payment Protocol](https://bsv.brc.dev/payments/0029)
* [BRC-42: Key Derivation Scheme](https://bsv.brc.dev/key-derivation/0042)
* [BRC-43: Security Levels and Protocol IDs](https://bsv.brc.dev/key-derivation/0043)
* [BRC-95: BEEF Transaction Format](https://bsv.brc.dev/transactions/0095)
* [BRC-105: HTTP Service Monetization Framework](https://bsv.brc.dev/payments/0105)
* [BRC-120: x402 Stateless Settlement-Gated HTTP Protocol](https://bsv.brc.dev/payments/0120)
* RFC 7231 Section 6.5.2: 402 Payment Required
* Reference server implementation: <https://github.com/bsv-blockchain-demos/402-articles>
* Reference client implementation: <https://github.com/bsv-blockchain/bsv-browser>