BRC-121 HTTP 402 Payment Required

BRC-121 monetizes HTTP API endpoints with a single-round-trip payment flow: client requests a resource, server responds with 402 and payment instructions (a nonce), client derives a payment address, constructs a BSV transaction, and re-sends the original request with payment headers. Server validates and serves the resource (or rejects with another 402).

At a glance

What problem this solves

Monetize APIs without subscriptions or token systems. Traditional APIs require accounts, credit cards, or API keys. BRC-121 enables instant monetization: each request is micro-paid in satoshis. No signup, no account needed—just pay per request and immediate access.

Request-bound payment derivation. The client supplies a fresh nonce and timestamp that participate in payment-key derivation. Those values bind the payment proof, but they are not a replay database by themselves. The server must also validate freshness and request fields, validate the remittance in its wallet, and atomically claim the transaction ID in an independent replay store. An exact wallet isMerge detail is useful defense in depth, but it is not part of the public BRC-100 result contract and cannot be the only replay control.

No authentication session required. Requests do not require BRC-103/104 mutual-auth state. Wallet transaction state and any application cache/replay policy are still stateful security dependencies. The built-in replay store is bounded and process-local; multi-process services require shared durable atomic claim state.

Protocol overview

Single round-trip with payment:

1. Client → Server GET /protected-resource (no payment headers)

   • Server checks if resource is free (price = 0) → serve it
   • Otherwise, server sends 402 Payment Required

2. Server → Client HTTP 402 response

   • x-bsv-server: <serverPublicKey> — Server's identity key
   • x-bsv-sats: <amount> — Satoshis required

3. Client (constructs payment)

   • Generates a fresh random nonce and millisecond timestamp
   • Calls wallet.createAction() with one P2PKH output
   • Derives address using key ID <nonce> <base64(timestamp)>
   • Uses BRC-42 to derive (pubKeyA, pubKeyB) from sender+server keys
   • Locks the output to the derived server payment key
   • Signs and constructs Atomic BEEF (BRC-95)

4. Client → Server same request with payment headers

   • x-bsv-beef: <beefBase64> — Atomic BEEF transaction
   • x-bsv-sender: <clientPublicKey> — Sender's identity key
   • x-bsv-nonce: <nonce> — Client-generated derivation prefix
   • x-bsv-time: <timestamp> — Unix millisecond timestamp
   • x-bsv-vout: <outputIndex> — Which output contains the payment

5. Server (validates & serves)

   • Calls wallet.internalizeAction() with BEEF
   • Requires an exact accepted === true result and rejects an exact isMerge === true detail
   • Atomically claims the payment transaction ID; only the first claim can serve the resource
   • If the transaction, nonce, amount, or output index is invalid → reject (HTTP 402)
   • If amount < required → reject (HTTP 402)
   • If wallet or replay-store state is ambiguous → return HTTP 503 without a fresh challenge

Key types / endpoints

Example: Monetized Express endpoint

import express from 'express'
import { createPaymentMiddleware } from '@bsv/402-pay/server'
import { ServerWallet } from '@bsv/simple/server'

const wallet = await ServerWallet.create({
  privateKey: process.env.SERVER_PRIVATE_KEY!,
  network: 'main',
  storageUrl: 'https://store-us-1.bsvb.tech'
})
const app = express()

app.use(
  createPaymentMiddleware({
    wallet,
    replayStore: sharedAtomicReplayStore,
    calculatePrice: path => {
      // Pricing logic
      if (path === '/premium') return 500 // 500 sats
      if (path === '/free') return 0 // Free
      return 100 // Default 100 sats
    }
  })
)

// Protected endpoint
app.get('/premium', (req, res) => {
  // If we reach here, payment was accepted
  res.json({
    content: 'Premium article here',
    paidBy: req.payment.senderIdentityKey,
    amount: req.payment.satoshisPaid,
    txid: req.payment.txid
  })
})

app.listen(3000)

Client-side (using create402Fetch):

import { create402Fetch } from '@bsv/402-pay/client'
import { WalletClient } from '@bsv/sdk'

const wallet = new WalletClient()

// Fetch wrapper that auto-handles 402
const fetch402 = create402Fetch({ wallet })

const response = await fetch402('https://api.example.com/premium')
const data = await response.json()
console.log(data.content) // Automatic payment + resource retrieval

Conformance vectors

There is no standalone BRC-121 vector directory in the current conformance corpus. Related portable fixtures live in conformance/vectors/wallet/brc29/payment-derivation.json for payment derivation and conformance/vectors/wallet/brc100/ for wallet methods used by payment clients and servers.

Implementations in ts-stack

Related specs

• BRC-29 Peer Payment — Key derivation and payment format
• BRC-42/43 — Key derivation for payment address
• BRC-95 / BRC-62 — Atomic BEEF format
• BRC-31 Auth — Often combined with 402 for dual auth + payment
• BRC-100 Wallet — internalizeAction() for payment validation

Spec artifact

brc121.yaml