Simple 402 Payments

Deggen ([email protected])

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 payment transaction, encodes it in BRC-95 BEEF 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 Direct Payment Protocol, BRC-105 HTTP Service Monetization Framework, BRC-120 x402) each define comprehensive negotiation mechanisms. This BRC targets a simpler use case: a client that already holds a BRC-42-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 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.

3. BEEF transport -- the payment transaction is transmitted as a base64-encoded BRC-95 BEEF 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 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 derivation prefix for the payment.
x-bsv-suffix	Client to server	Base64-encoded BRC-29 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.

4. Uses BRC-42 key derivation with the invoice number format 2-3241645161d8-<prefix> <suffix> 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 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. 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-compatible wallet, and retransmits the request. Source: 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

• BRC-42: Key Derivation Scheme

• BRC-43: Security Levels and Protocol IDs

• BRC-95: BEEF Transaction Format

• BRC-105: HTTP Service Monetization Framework

• BRC-120: x402 Stateless Settlement-Gated HTTP Protocol

• 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