# Simple 402 Payments Deggen () ## 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://hub.bsvblockchain.org/brc/payments/0029) payment transaction, encodes it in [BRC-95 BEEF](https://hub.bsvblockchain.org/brc/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://hub.bsvblockchain.org/brc/payments/0027) Direct Payment Protocol, [BRC-105](https://hub.bsvblockchain.org/brc/payments/0105) HTTP Service Monetization Framework, [BRC-120](https://hub.bsvblockchain.org/brc/payments/0120) x402) each define comprehensive negotiation mechanisms. This BRC targets a simpler use case: a client that already holds a [BRC-42](https://hub.bsvblockchain.org/brc/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://hub.bsvblockchain.org/brc/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://hub.bsvblockchain.org/brc/payments/0029). 3. **BEEF transport** -- the payment transaction is transmitted as a base64-encoded [BRC-95 BEEF](https://hub.bsvblockchain.org/brc/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://hub.bsvblockchain.org/brc/transactions/0095) transaction containing the payment. | | `x-bsv-sender` | Client to server | Client's compressed, hex-encoded secp256k1 identity public key. | | `x-bsv-prefix` | Client to server | Base64-encoded [BRC-29](https://hub.bsvblockchain.org/brc/payments/0029) derivation prefix for the payment. | | `x-bsv-suffix` | Client to server | Base64-encoded [BRC-29](https://hub.bsvblockchain.org/brc/payments/0029) derivation suffix for the payment output. | | `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 and derivation suffix as specified in [BRC-29](https://hub.bsvblockchain.org/brc/payments/0029). 4. Uses [BRC-42](https://hub.bsvblockchain.org/brc/key-derivation/0042) key derivation with the invoice number format `2-3241645161d8- ` to derive the recipient's public key. 5. Constructs a BSV transaction with a P2PKH output of the required satoshi amount locked to the derived public key. 6. Serializes the transaction in [BRC-95 BEEF](https://hub.bsvblockchain.org/brc/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-prefix` | Base64-encoded derivation prefix | | `x-bsv-suffix` | Base64-encoded derivation suffix | | `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-prefix`, `x-bsv-suffix`, `x-bsv-vout`) are present. If any are missing, respond with 402. 2. Decode the BEEF transaction from base64. 3. Internalize the payment using the wallet's `internalizeAction` operation with: * The decoded transaction bytes * Protocol: `wallet payment` * Payment remittance containing `derivationPrefix`, `derivationSuffix`, and `senderIdentityKey` from the provided headers * Output index from `x-bsv-vout` 4. If internalization succeeds, serve the protected resource with HTTP status `200`. 5. 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. ### 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. **Server (Express/Node.js)** -- A reference implementation of the server-side middleware is available at [github.com/bsv-blockchain-demos/402-articles](https://github.com/bsv-blockchain-demos/402-articles). The middleware uses `@bsv/sdk` for BEEF parsing and `@bsv/wallet-toolbox` for payment internalization. 2. **Client (React Native WebView)** -- A reference client implementation intercepts 402 responses in a fetch wrapper, constructs payment headers using a [BRC-42](https://hub.bsvblockchain.org/brc/key-derivation/0042)-compatible wallet, and retransmits the request. Source: [github.com/bsv-blockchain/bsv-browser](https://github.com/bsv-blockchain/bsv-browser). 3. **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://hub.bsvblockchain.org/brc/payments/0029) * [BRC-42: Key Derivation Scheme](https://hub.bsvblockchain.org/brc/key-derivation/0042) * [BRC-43: Security Levels and Protocol IDs](https://hub.bsvblockchain.org/brc/key-derivation/0043) * [BRC-95: BEEF Transaction Format](https://hub.bsvblockchain.org/brc/transactions/0095) * [BRC-105: HTTP Service Monetization Framework](https://hub.bsvblockchain.org/brc/payments/0105) * [BRC-120: x402 Stateless Settlement-Gated HTTP Protocol](https://hub.bsvblockchain.org/brc/payments/0120) * RFC 7231 Section 6.5.2: 402 Payment Required * Reference server implementation: * Reference client implementation: