LogoLogo
  • README
  • Contribute
    • Discuss on Github
  • Example
    • Banana-Powered Bitcoin Wallet Control Protocol
  • Apps
    • The deployment-info.json Specification
  • Wallet
    • Transaction Creation
    • Data Encryption and Decryption
    • Digital Signature Creation and Verification
    • Input Redemption
    • HTTP Wallet Communications Substrate
    • XDM Wallet Communications Substrate
    • Window Wallet Communication Substrate
    • Wallet Transaction Output Tracking (Output Baskets)
    • Submitting Received Payments to a Wallet
    • Certificate Creation and Revelation
    • Unified Abstract Wallet-to-Application Messaging Layer
    • Transaction Labels and List Actions
    • Output Basket Removal and Certificate Deletion
    • Group Permissions for App Access
    • Extensible Proof-Type Format for Specific Key Linkage Claims
    • P Protocols: Allowing future wallet protocol permission schemes
    • P Baskets: Allowing Future Wallet Basket and Digital Asset Permission Schemes
    • Unified, Vendor-Neutral, Unchanging, and Open BSV Blockchain Standard Wallet-to-Application Interface
  • Transactions
    • Everett-style Transaction Envelopes
    • Simplified Payment Verification
    • Merkle proof standardised format
    • TSC Proof Format with Heights
    • Raw Transaction Format
    • TXO Transaction Object Format
    • Transaction Extended Format (EF)
    • Merkle Path JSON format
    • Compound Merkle Path Format
    • Background Evaluation Extended Format (BEEF) Transactions
    • Simplified Payment Verification
    • Merkle Path Binary Format
    • BSV Unified Merkle Path (BUMP) Format
    • Graph Aware Sync Protocol
    • Scalable Transaction Processing in the BSV Network
    • Atomic BEEF Transactions
    • BEEF V2 Txid Only Extension
  • Scripts
    • Bitcoin Script Binary, Hex and ASM Formats
    • Bitcoin Script Assembly Language
    • Pay to Public Key Hash
    • Pay to R Puzzle Hash
    • Pay to False Return
    • Pay to True Return
    • Push TX
    • Bare Multi-Signature
    • Pay to Push Drop
  • Tokens
    • There is no BRC-20
    • Definition of UTXOs as Bitcoin Tokens
    • Token Exchange Protocol for UTXO-based Overlay Networks
    • Mandala Token Protocol
  • Overlays
    • Overlay Network Data Synchronization
    • Confederacy Host Interconnect Protocol (CHIP)
    • Overlay Network Lookup Services
    • Confederacy Lookup Availability Protocol (CLAP)
    • Universal Hash Resolution Protocol
    • Overlay Network Transaction History Tracking
    • Private Overlays with P2PKH Transactions
    • Standardized Naming Conventions for BRC-22 Topic Managers and BRC-24 Lookup Services
    • Overlay Services Synchronization Architecture
    • Diverse Facilitators and URL Protocols for SHIP and SLAP Overlay Advertisements
  • Payments
    • Direct Payment Protocol (DPP)
    • Paymail Payment Destinations
    • Simple Authenticated BSV P2PKH Payment Protocol
    • PacketPay HTTP Payment Mechanism
    • Hybrid Payment Mode for DPP
    • HTTPS Transport Mechanism for DPP
    • Paymail BEEF Transaction
    • HTTP Service Monetization Framework
  • Peer-to-Peer
    • Authrite Mutual Authentication
    • PeerServ Message Relay Interface
    • PeerServ Host Interconnect Protocol
    • Identity Certificates
    • Genealogical Identity Protocol
    • Publishing Trust Anchor Details at an Internet Domain
    • Message Signature Creation and Verification
    • Serialization Format for Portable Encrypted Messages
    • Defining a Scalable IPv6 Multicast Protocol for Blockchain Transaction Broadcast and Update Delivery
    • Proven Identity Key Exchange (PIKE)
    • Peer-to-Peer Mutual Authentication and Certificate Exchange Protocol
    • HTTP Transport for BRC-103 Mutual Authentication
  • Key Derivation
    • BIP32 Key Derivation Scheme
    • BSV Key Derivation Scheme (BKDS)
    • Security Levels, Protocol IDs, Key IDs and Counterparties
    • Admin-reserved and Prohibited Key Derivation Protocols
    • Revealing Key Linkages
    • Protecting BRC-69 Key Linkage Information in Transit
    • Mnemonic For Master Private Key
    • Linked Key Derivation Scheme
    • Bidirectionally Authenticated Derivation of Privacy Restricted Type 42 Keys
    • Limitations of BRC-69 Key Linkage Revelation
    • Verifiable Revelation of Shared Secrets Using Schnorr Protocol
  • Outpoints
    • Format for Bitcoin Outpoints
    • Spending Instructions Extension for UTXO Storage Format
  • Opinions
    • Users should never see an address
    • List of user experiences
    • Legitimate Uses for mAPI
    • Security and Scalability Benefits of UTXO-based Overlay Networks
    • Improving on MLD for BSV Multicast Services
    • Web 3.0 Standard (at a high level)
    • Thoughts on the Mandala Network
    • Outputs, Overlays, and Scripts in the Mandala Network
  • State Machines
    • Simplifying State Machine Event Chains in Bitcoin
Powered by GitBook
On this page
  • 1. Abstract
  • 2. Motivation
  • 3. Terminology & Definitions
  • 4. Relationship to BRC-103 and BRC-104
  • 5. Payment Protocol Overview
  • 5.1 Payment Steps Summary
  • 5.2 Payment Headers
  • 6. Detailed Protocol Flow
  • 6.1 Request
  • 6.2 Server’s 402 Response
  • 6.3 Client Payment Submission
  • 6.4 Server Payment Verification
  • 6.5 Response to Payment-Funded Request
  • 7. Example Implementation
  • 7.1 Server-Side Steps
  • 7.2 Client-Side Steps
  • 8. Security Considerations
  • 9. Extensibility & Future Work
  • 10. References
  • 11. Conclusion

Was this helpful?

Edit on GitHub
Export as PDF
  1. Payments

HTTP Service Monetization Framework

PreviousPaymail BEEF TransactionNextAuthrite Mutual Authentication

Last updated 4 months ago

Was this helpful?

  • Ty Everett (ty@projectbabbage.com)

  • Brayden Langley (brayden@projectbabbage.com)

1. Abstract

This document specifies an HTTP-based micropayment framework that extends (mutual authentication and certificate exchange) and (HTTP transport for BRC-103). It defines how a server can advertise payment requirements for a given HTTP request and how a client can respond with a BSV transaction fulfilling these requirements. By leveraging:

  • HTTP 402 Payment Required responses

  • Nonce-based derivation prefixes ()

  • BRC-103 Identity keys

this specification enables an authenticated, verifiable mechanism to monetize any web service with micropayments. The server could even cryptographically bind each payment to the mutual-authenticated session, ensuring that the payment correlates uniquely to the requested action.

2. Motivation

Current HTTP-based APIs often rely on subscription models or external billing/invoicing solutions. This approach can be cumbersome for fine-grained (micropayment-level) usage-based billing. By contrast, BSV Blockchain capabilities allow on-chain micropayments. However, bridging these seamlessly into existing HTTP flows requires:

  • Standardized BSV wallet functionality ()

  • A standard approach to advertise payment requirements (HTTP 402)

  • A mechanism to tie a user’s payment to their session identity (via BRC-103 identity keys)

  • Nonce-based replay protection (ensuring the same payment is not reused maliciously)

BRC-105 addresses these needs by specifying how a BRC-103–authenticated server can request and verify a BSV payment from the client within a standard HTTP request–response cycle. Clients can use specialized 402-handling agents (e.g. AuthFetch or custom code) to automatically respond to 402 Payment Required, building and broadcasting a transaction on the user’s behalf.

3. Terminology & Definitions

  • Payer (or Client): The party sending the HTTP request, who must pay the server if required. They are already mutually authenticated to the server via BRC-103/104.

  • Payee (or Server): The HTTP endpoint receiving the request, which may respond with 402 Payment Required, specifying the needed payment details.

  • x-bsv-payment header: A custom header carrying JSON data, including the transaction references and derivation prefixes/suffixes.

  • internalizeAction(): A function defined by the payee’s wallet or server that finalizes the transaction acceptance logic (e.g., verifying the correct output script, ensuring the derivation prefix is valid, confirming the transaction is not a duplicate, etc.).

4. Relationship to BRC-103 and BRC-104

BRC-103 defines mutual authentication and certificate exchange but does not define how to handle micropayments. BRC-104 applies BRC-103 to HTTP, detailing how to wrap BRC-103 handshake data in HTTP messages.

BRC-105 sits on top of BRC-104, specifying a payment layer for monetizing HTTP endpoints. It reuses:

  • identityKey: The user’s 33-byte compressed public key from the BRC-103 session.

  • Nonce generation: The server can generate derivation prefixes that are cryptographically bound to its identity key, used by the parties to derive an ephemeral key pair for the payment.

  • HTTP 402 status code**: A recognized but typically unused code, repurposed here for BSV micropayments.

5. Payment Protocol Overview

5.1 Payment Steps Summary

  1. Client Authenticates

    • The client (payer) establishes a BRC-103 session with the server (payee) using BRC-104. This ensures both parties have authenticated and exchanged any necessary certificates to establish identity.

  2. Server Determines Price

    • The server calculates how many satoshis this request requires (if any). This can be a static fee, dynamic, or zero.

  3. 402 Payment Required (if fee > 0 and no valid payment provided)

    • If the client has not included a valid x-bsv-payment header, the server responds with HTTP status 402 and sets:

      • x-bsv-payment-satoshis-required: Number of satoshis required.

  4. Client Submits Payment

    • The client’s wallet or user agent sees the 402 response.

    • It constructs a BSV transaction paying the requested amount to the server’s derivation.

    • The client re-sends the request with a header x-bsv-payment containing JSON:

      {
        "derivationPrefix": "AAAAA...",
        "derivationSuffix": "...",
        "transaction": "SGVsbG8s" // a BSV transaction in AtomicBEEF format encoded as base64
      }
  5. Server Verifies Payment

    • The server checks the prefix (derivationPrefix) and suffix (derivationSuffix), ensures it matches what was advertised, and that the transaction properly pays the required amount.

    • If successful, the server considers the request to be funded.

  6. Server Continues

    • Assuming the payment is valid, the server proceeds with the requested operation and returns a normal success response (e.g., 200).

5.2 Payment Headers

  • x-bsv-payment-version

    • The current supported version is 1.0.

    • If a client does not explicitly support the server's indicated version, the client MUST NOT submit a payment.

  • x-bsv-payment-satoshis-required

    • Integer number of satoshis needed for this request.

    • Sent from server → client in 402 Payment Required.

  • x-bsv-payment-derivation-prefix

    • Payment-level nonce for deriving the payment output script.

    • Sent from server → client in 402 Payment Required.

  • x-bsv-payment

    • JSON structure containing the actual transaction data.

    • Sent from client → server in a subsequent request or retry after 402.

6. Detailed Protocol Flow

6.1 Request

6.1.1 Normal Request With Potential Payment

A mutually authenticated request arrives (client has previously performed BRC-103 handshake). The request may or may not contain x-bsv-payment data:

  • If no payment is needed (the server’s calculateRequestPrice returns 0), proceed normally.

  • If the request has a non-zero price and the client did not supply x-bsv-payment, or the payment is invalid, the server responds with 402 Payment Required.

6.2 Server’s 402 Response

When the server determines a payment is needed but not yet provided or invalid:

  1. HTTP Status: 402 Payment Required.

  2. Headers:

    • x-bsv-payment-version: 1.0

    • x-bsv-payment-satoshis-required: <price in satoshis>

    • x-bsv-payment-derivation-prefix: <nonce> (often base64 or hex)

  3. Body: Optional JSON describing the error or instructions for convenience:

    {
      "status": "error",
      "code": "ERR_PAYMENT_REQUIRED",
      "satoshisRequired": 200,
      "description": "A BSV payment is required..."
    }

After receiving this, the client is expected to construct and broadcast a payment transaction referencing this prefix.

6.3 Client Payment Submission

Subsequent request includes the header x-bsv-payment, JSON:

{
  "derivationPrefix": "<prefix from server>",
  "derivationSuffix": "<optional suffix>",
  "transaction": "SGVsbG8s"
}
  • derivationPrefix: Must match what the server gave in the 402 response.

  • transaction: A fully signed transaction paying an output script derived from the prefix, acceptable on the BSV network.

6.4 Server Payment Verification

Upon receiving x-bsv-payment, the server:

  1. Ensures the prefix is the same as previously advertised (and not used before).

  2. Validates the transaction using wallet.internalizeAction() or similar. Steps might include:

    • Ensuring the output script pays to the correct derivation from derivationPrefix.

    • Checking if the amount is at least the required satoshisRequired.

    • Preventing double-spend or replay.

If validated, the server MUST proceed to handle the request logic, and is obliged to provide the requested service, according to what the client has paid for.

6.5 Response to Payment-Funded Request

If payment is successful, the server responds with a normal (e.g., 200 OK) plus any business logic response body. The server may add:

  • x-bsv-payment-satoshis-paid: <value>

  • Possibly additional data about the transaction or usage.

7. Example Implementation

7.1 Server-Side Steps

  1. Auth Check (BRC-103/104)

    • If not authenticated, respond 401 Unauthorized.

  2. Calculate Price

    • E.g., price = 200 satoshis.

  3. If x-bsv-payment Provided

    • Parse and verify. If valid, continue. If invalid, return 400 Bad Request.

  4. If Not Paid

    • Return 402 + x-bsv-payment-version + x-bsv-payment-derivation-prefix + x-bsv-payment-satoshis-required.

  5. If Paid

    • Proceed to business logic.

7.2 Client-Side Steps

  1. Send Request

    • If server returns 402, parse x-bsv-payment-version + x-bsv-payment-satoshis-required + x-bsv-payment-derivation-prefix.

  2. Construct Payment

    • Create transaction paying the server’s derivation.

    • Store it in x-bsv-payment JSON.

  3. Re-Send

    • Re-send the request with x-bsv-payment header.

    • If accepted, receives normal 200 OK.

    • If server fraudulently absconds with client funds:

      • Do not use the service again.

      • Make reports to the issuers of the server's certificates to have them revoked.

      • Do not trust certifiers who are willing to issue certificates to fraudulent entities.

      • Contact your local police department.

8. Security Considerations

  1. Replay Attacks

    • The server and its wallet must ensure each derivationPrefix can only be used once. Typically, this prefix is stored in a wallet database or in-memory structure. Once a valid transaction is processed, subsequent attempts to reuse the prefix or submit the same transaction for multiple requests must fail.

  2. Man-in-the-Middle

    • Because all requests are already mutually authenticated via BRC-103, a MITM cannot hijack the payment flow. Tampering with the transaction or the prefix invalidates the request and leads to cryptographic failure.

  3. Underpayment

    • The server should reject transactions that pay less than required. Or, if partial payments are allowed, the server must define how to handle partial coverage. Servers should set clear refund policies, and policies for services not used or partially paid. Generally, partial payment is prohibited.

  4. Double Spends

    • The server’s wallet.internalizeAction() logic must handle double-spend scenarios, ensuring the transaction is fully-signed, final and valid on the network.

  5. Data Confidentiality

    • BRC-105 does not itself encrypt data. Transport-level encryption (e.g., TLS) is recommended to protect transaction details and requests from eavesdroppers.


9. Extensibility & Future Work

  • Advanced Pricing: BRC-105 does not define how to calculate price. Implementation can adopt static or dynamic logic.

  • Refund Handling: Out of scope for this version. The server might store overpayments or offer on-chain refunds via additional flows.

  • Multi-Output Payments: Some use cases might require paying multiple outputs. The basic 402 flow still applies but must be extended with more sophisticated transaction logic.

10. References

11. Conclusion

BRC-105 introduces a standard approach to HTTP-based micropayment flows, leveraging the authentication and transport models defined in BRC-103 and BRC-104. By responding with 402 Payment Required and specifying a nonce-based derivation, the server ensures each payment is uniquely bound to the mutual-authenticated session and request. This framework enables straightforward pay-per-use APIs and extends the BSV ecosystem with a robust, standardized mechanism for monetizing web services at scale.

Derivation Prefix: A random nonce string used to derive or reference a unique public key / payment output. Defined in .

Derivation Suffix: An additional, output/script-level field included by the client with the payment transaction that is used by the payee's wallet for verification. Also defined in .

x-bsv-payment-derivation-prefix: A random nonce () for the transaction.

Clients should request more robust identity certificates using in the future.

File an .

: Peer-to-Peer Mutual Authentication and Certificate Exchange Protocol

: HTTP Transport for BRC-103

: Derivation-based Payment Protocol

BRC-103
BRC-104
BRC-29
BRC-100
BRC-29
BRC-29
BRC-29
BRC-103
IC3 complaint
BRC-103
BRC-104
BRC-29
402 Payment Required