BUD-07

Paid storage

draft optional

Payment requirements for blob storage.

Payment Required

Some servers MAY require payment for file storage. In that case, these endpoints MUST return a 402 Payment Required status code and a X-Payment header when the payment is required.

Server header

The X-Payment header is used by the server to inform the client that payment is required for the requested operation, MUST contain the following fields:

blob: The blob to be paid.
amount: The amount to be paid (optional).
payment_method: The payment system to be used (e.g., cashu, lightning, liquid).
payment_details: L2 specific payment details.

Each payment method has its own requirements and the server SHOULD provide the necessary information for the client to complete the payment.

Example for cashu:

{
  "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644",
  "payment_method": "cashu",
  "payment_details": {
    "amount": "300",
    "mints": "https://example.com",
    "unit": "sat",
    "pubkey": "0a3bce8b6005175d25432244340912dfa431a0d62681d9720cda9196398d7222"
  }
}

Example for lightning:

{
  "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644",
  "amount": "300",
  "payment_method": "lightning",
  "payment_details": {
    "payment_request": "lnbc300n1pw4..:",
  }
}

Example for liquid:

```json
{
  "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644",
  "payment_method": "liquid",
  "payment_details": {
    "payment_request": {
      "address": "VJLgF1s3...",
      "asset_id": "6f0279e9ed...",
      "amount": 0.000300,
      "memo": "test"
    }
  }
}

Schema:

HTTP/1.1 402 Payment Required
X-Payment: "<base64_encoded_server_json>"

Client implementation

Clients MUST check the X-Payment header received from the server and display the payment request to the user. When the payment is complete the client MUST use the same header to inform the server that the payment was successful using this structure:

blob: The paid blob.
payment_proof: The payment proof. (e.g., preimage for cashu and lightning, txid for liquid).

{
  "blob": "481d5f1a374e3750518db22337bc6cb3be5be615d550ba189c9a9a55f6d55644",
  "payment_proof": "c3b9e2..."
}