Simple 402 Payments

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.

Status Note

This document specifies a deliberately small BSV-specific 402 payment profile.

It should be read as an alternative to, not a replacement for, BRC-105. Implementers that need the broader BRC-103/BRC-104-authenticated monetization framework should use BRC-105, optionally with BRC-118 for multipart transport. Implementers that want conformance to the frozen external x402 specification should use BRC-120.

Motivation

HTTP 402 remains reserved for future use in current HTTP semantics (RFC 9110), but no general web-standard payment 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:

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.
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.
5. Base64-encodes the time value for use as the derivation suffix in key derivation. Uses BRC-42 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 format and encodes it as base64.

4. Client: Paid Request

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

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.

   // 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.

3. 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.

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.

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.

Implementations

• BSV Browser
• Chrome Extension
• Firefox Extension

Source Code

• TypeScript Middleware
• Go Middleware
• Browser Extension Source Code

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 9110 Section 15.5.3: 402 Payment Required
• Reference server implementation: https://github.com/bsv-blockchain-demos/402-articles
• Reference client implementation: https://github.com/bsv-blockchain/bsv-browser