BSV blockchainBSV blockchain

Fetch a BRC-121-protected HTTP resource.

GET/{resourcePath}

When called without payment headers the server returns 402. When called with valid payment headers the server serves the resource.

The same pattern applies to any HTTP method; GET is used as the canonical example. POST, PUT, DELETE etc. follow identical header semantics.

Header Parameters

x-bsv-beefstring

Base64-encoded Atomic BEEF (BRC-95) transaction containing the payment output. MUST be present on the paid request.

x-bsv-senderstring

Client’s compressed, hex-encoded secp256k1 identity public key. Used by the server as the senderIdentityKey in paymentRemittance.

x-bsv-noncestring

Base64-encoded BRC-29 derivation prefix for this payment. Serves as derivationPrefix in the internalizeAction remittance.

x-bsv-timestring

Unix millisecond timestamp as a decimal string (e.g. 1719500000000). Two purposes:

  1. Freshness check — server rejects if |serverTime - x-bsv-time| > 30 s.
  2. Derivation suffix — base64(x-bsv-time) is used as the BRC-29 derivationSuffix in key derivation. MUST be present on the paid request.
x-bsv-voutstring

Zero-based output index (decimal string) of the payment output within the BEEF transaction. MUST be present on the paid request.

Path Parameters

resourcePathstringrequired

Arbitrary path of the protected resource.

Response

Payment accepted; protected resource served. Body is application-specific.

Payment is required. The response body MUST be empty (the server MUST NOT serve the protected content).

Two distinct conditions both result in 402:

  1. No payment headers — client should read x-bsv-sats and x-bsv-server, construct payment, and retry.
  2. Invalid payment — client SHOULD NOT retry automatically to avoid double-spending.

The server failed to initialise its wallet or encountered an unexpected error. The client SHOULD NOT retry payment for 5xx responses.

errorstring

Human-readable error description.

Payment processing failed after wallet work began, so acceptance state may be ambiguous. No fresh payment challenge headers are sent. The client MUST NOT create another payment until the transaction is reconciled.

Request
curl -X GET "https://{host}/<resourcePath>" \
  -H "x-bsv-beef: <x-bsv-beef>" \
  -H "x-bsv-sender: <x-bsv-sender>" \
  -H "x-bsv-nonce: <x-bsv-nonce>" \
  -H "x-bsv-time: <x-bsv-time>" \
  -H "x-bsv-vout: <x-bsv-vout>"
Response
(no body)