Stateless Settlement-Gated HTTP

What is x402-BSV

Cryptographically verifiable usage metering for HTTP APIs and machine-to-machine systems, using BSV settlement.

x402-BSV is a Stateless Settlement-Gated HTTP Protocol. It integrates settlement directly into the HTTP request lifecycle through a structured 402 challenge → proof → retry flow. Every API call produces an independently verifiable on-chain record. The blockchain is used as a proof layer, not a checkout system — commercial billing remains contractual and off-chain, exactly like AWS or any other cloud provider.

The Problem

The x402-BSV Model

An unpaid request receives a deterministic payment challenge. The client constructs a partial transaction spending a nonce UTXO issued in the challenge. A delegator hydrates fees, signs, and returns the completed transaction. The client broadcasts to the network, then resubmits the request with cryptographic proof of settlement. The gatekeeper verifies binding, nonce consumption, and settlement acceptance before delivering the asset.

This preserves HTTP semantics while embedding payment as a deterministic precondition to execution. Every usage event is recorded on-chain — independently auditable by both parties.

What It Is — and Isn't

Why BSV

The protocol design is blockchain-agnostic at the specification level. It requires deterministic per-request settlement, extremely low fees, high throughput, no mempool games, stateless verification, and unbounded scaling without L2 coordination.

Today, only BSV satisfies these constraints without compromises. Other chains can simulate parts of this model by adding layers of trust and batching. BSV is the only chain that runs it natively — predictable fees (1–50 sats), massive throughput, UTXO proofs mapping directly to usage events, and simple, legally intelligible transactions.

Wire Protocol Specification

X402-BSV-PROOF/1 — the exact wire-level protocol for x402-BSV settlement. FROZEN
View full protocol specification on GitHub ↗

HTTP Flow

The protocol operates as a six-step cycle within standard HTTP semantics.

Step 1 — Client Makes Unpaid Request

GET /api/expensive-resource HTTP/1.1
Host: api.example.com
Accept: application/json

No payment headers. No authentication.

Step 2 — Server Responds with 402 Challenge

HTTP/1.1 402 Payment Required
X402-Challenge: <base64url(JSON)>
X402-Accept: bsv-tx-v1
Cache-Control: no-store

Challenge JSON

{
  "v": "1",
  "scheme": "bsv-tx-v1",
  "nonce_utxo": {
    "txid": "hex_string",
    "vout": 0,
    "satoshis": 1,
    "locking_script_hex": "hex_string"
  },
  "amount_sats": 37,
  "payee_locking_script_hex": "hex_string",
  "expires_at": 1735689600,
  "domain": "api.example.com",
  "method": "GET",
  "path": "/api/expensive-resource",
  "query": "",
  "req_headers_sha256": "hex_string",
  "req_body_sha256": "hex_string",
  "require_mempool_accept": true,
  "confirmations_required": 0
}

Step 3 — Client Constructs Partial Transaction

The client builds a partial transaction with one input (spending the nonce_utxo) and one output (paying ≥ amount_sats to payee_locking_script_hex). Miner fee inputs and signatures are missing — these are added by the delegator.

Step 4 — Client Submits to Fee Delegator

{
  "partial_tx": "<hex>",
  "nonce_utxo": { "txid": "...", "vout": 0 },
  "challenge_sha256": "hex_string"
}

The delegator validates, adds fee inputs, signs its own inputs, and returns the completed transaction. The client then broadcasts to the BSV network.

Step 5 — Client Retries with Proof

GET /api/expensive-resource HTTP/1.1
Host: api.example.com
X402-Proof: <base64url(JSON)>
X402-Tx: <base64(rawtx)>

Proof JSON

{
  "v": "1",
  "scheme": "bsv-tx-v1",
  "txid": "hex_string",
  "rawtx_b64": "base64_string",
  "challenge_sha256": "hex_string",
  "request": {
    "domain": "api.example.com",
    "method": "GET",
    "path": "/api/expensive-resource",
    "query": "",
    "req_headers_sha256": "hex_string",
    "req_body_sha256": "hex_string"
  }
}

Step 6 — Server Verifies and Responds

The gatekeeper executes a deterministic 16-step verification sequence:

1. Base64url decode proof JSON
2. Validate v and scheme
3. Recompute req_body_sha256 from actual request body
4. Recompute req_headers_sha256 from actual request headers
5. Validate request hashes match proof.request.*
6. Recompute challenge_sha256 from stored challenge
7. Validate challenge_sha256 matches proof
8. Validate domain/method/path/query match challenge
9. Validate now ≤ expires_at
10. Decode rawtx_b64, compute txid, compare to proof.txid
11. Confirm tx includes input spending nonce_utxo
12. Confirm tx includes output paying ≥ amount_sats
13. Query mempool acceptance
14. Verify client_sig (optional, v1.1)
15. If all pass → 200 OK
16. If tx valid but not in mempool → 409 Conflict or 202 Accepted

Canonical Hashing Rules

Header Hash (req_headers_sha256)

Allowlist (default): accept, content-type, content-length, x402-idempotency-key, x402-client.

1. Lowercase header names
2. Trim surrounding whitespace in values
3. Collapse internal runs of whitespace to single space
4. Sort by header name (lexicographic)
5. Join as: name:value\n for each header
6. Compute: SHA256(utf8(canonical_headers_string)) → hex

Body Hash (req_body_sha256)

SHA256(raw_body_bytes) → hex. If no body: SHA256("") → hex.

Challenge Hash (challenge_sha256)

Serialize challenge JSON using RFC 8785 (JSON Canonicalization Scheme, JCS). Sort object keys lexicographically, no whitespace, deterministic encoding. SHA256(canonical_json_bytes) → hex.

Transaction Constraints

For scheme = "bsv-tx-v1", the transaction must contain:

1. Nonce spend — one input spending nonce_utxo from challenge
2. Payee output — one output with locking script matching payee_locking_script_hex, amount ≥ amount_sats
3. Optional change output(s) — as needed

If require_mempool_accept is true, the gatekeeper verifies mempool visibility independently. Broadcast origin is irrelevant to correctness. No confirmations required by default.

Acceptance Matrix

Error Codes

Architecture

Five strictly separated layers. Each with non-negotiable boundaries. No responsibility blurring.

Component Boundaries

The Gatekeeper handles HTTP semantics and proof validation — it never signs transactions, manages UTXOs, or holds private keys. The Fee Delegator handles transaction construction and fee sponsorship — it never parses HTTP, evaluates expiry timestamps, or performs business logic. The BSV Network enforces UTXO single-spend globally — it knows nothing about x402.

Trust Boundaries

Economics & Security

Operationally survivable by design — bounded costs, layered abuse prevention, deterministic failure modes.

Per-Request Cost Breakdown

Infrastructure costs: $50–500/month depending on scale (node + servers).

Funding Modes

The protocol is invariant across modes. Only the funding source changes.

Threat Model

Abuse Prevention Controls

Getting Started

Run the reference implementation locally in under five minutes.

Prerequisites

• Go 1.21+ (for gateway server and delegator)
• Node.js 20+ (for client SDK)
• Redis (optional — for persistent UTXO pool state)
• Docker (optional — for containerized deployment)

Quick Start

# Clone the reference implementation
git clone https://github.com/merkleworks/x402-bsv.git
cd x402-bsv

# Generate keys and configure
make setup

# Start the gateway (gatekeeper + delegator + demo API)
make demo

# In another terminal — make a paid request
make client

make setup generates BSV keypairs and creates a .env file. make demo starts the full stack on localhost. make client executes the complete 402 challenge → proof → response cycle.

Client SDK (TypeScript/Node.js)

The @merkleworks/x402-client package is a drop-in fetch() replacement that handles the x402 flow transparently. It performs the original request, intercepts 402 responses, forwards the challenge to the gateway, and retries with proof — in a single call.

npm install @merkleworks/x402-client

import { X402Client } from '@merkleworks/x402-client';

const client = new X402Client({
  gatewayUrl: 'https://gateway.example.com',
});

// Drop-in fetch replacement — handles 402 transparently
const response = await client.fetch('https://api.example.com/expensive-resource');
const data = await response.json();

Configuration Reference

Docker Deployment

# Build and run with Docker Compose
docker compose up -d

# Or build individual images
docker build -t x402-gateway -f Dockerfile.server .
docker build -t x402-delegator -f Dockerfile.delegator .

API Reference

Endpoints exposed by the gateway and delegator. Download the Postman collection to test these endpoints directly.

Protected Endpoints (any path behind the gatekeeper middleware)

Any endpoint behind the x402 middleware returns 402 Payment Required with X402-Challenge header on unpaid requests. Paid requests include X402-Proof and X402-Tx headers.

Fee Delegator

Dashboard API

Project Structure

Go monorepo with TypeScript client SDK and React dashboard.

x402-bsv/
├── cmd/
│   ├── server/        # Main gateway binary
│   ├── delegator/     # Standalone fee delegator
│   ├── keygen/        # Key generation utility
│   ├── setup/         # Initial setup tool
│   └── client/        # CLI test client
├── internal/
│   ├── gatekeeper/    # 402 middleware, challenge gen, proof verification
│   ├── delegator/     # Partial tx validation, fee injection, signing
│   ├── broadcast/     # Multi-backend tx broadcaster (ARC, WoC, Mock)
│   ├── pool/          # UTXO pool management (nonce, fee, payment)
│   ├── challenge/     # Challenge building, canonical hashing
│   ├── treasury/      # Treasury watcher, fanout, sweep, refill
│   ├── replay/        # LRU + TTL replay detection cache
│   ├── hdwallet/      # BIP32 HD key derivation
│   ├── pricing/       # Pluggable pricing (fixed, per-byte)
│   └── dashboard/     # Dashboard API handlers
├── client-js/         # @merkleworks/x402-client (TypeScript)
│   └── src/
│       ├── client.ts      # X402Client — drop-in fetch replacement
│       ├── challenge.ts   # Challenge parsing, canonical hashing
│       ├── transaction.ts # Partial transaction building
│       ├── proof.ts       # Proof header generation
│       ├── delegator.ts   # Gateway communication
│       └── broadcaster.ts # ARC broadcast integration
├── dashboard/         # React + TypeScript + Vite
│   └── src/
│       ├── MonitorTab.tsx
│       ├── TreasuryTab.tsx
│       ├── AnalyticsTab.tsx
│       └── SettingsTab.tsx
├── docs/              # Additional documentation
├── Dockerfile.server
├── Dockerfile.delegator
├── docker-compose.yml
├── Makefile
└── go.mod

Governance

Authority hierarchy for specification and implementation.