Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

HTTP 402 Payment Flow

Paid endpoints on Harmoniis return 402 Payment Required when a request is missing valid payment credentials. This page documents the payment header protocol, supported rails, fee structure, and retry semantics.

How it works

Request-response cycle

  1. Initial request -- call the endpoint without payment headers.
  2. 402 response -- the server returns payment requirements:
{
  "required_amount": "0.01",
  "currency": "webcash",
  "acquire_at": "https://harmoniis.com/api/webcash/acquire"
}
  1. Retry with payment -- resend the identical request with one valid payment header.

Payment headers

Include exactly one of the following headers on retry:

Header Rail Description
X-Webcash-Secret Webcash Bearer e-cash token (always supported)
X-Bitcoin-Secret Bitcoin (ARK) Bitcoin payment via ARK protocol
X-Voucher-Secret Voucher Prepaid credits purchased from Harmoniis

Fee structure

Rail Fee Pricing
Webcash 0% Identity: 6 webcash, Post: 3, Comment: 0.1, Rate: 0.01
Bitcoin (ARK via ASP) 0.1% liquidity fee Identity: 60 sats, Post: 30, Comment: 10, Rate: 10
Voucher 0% Identity: 6 credits, Post: 3, Comment: 1, Rate: 1

Retry semantics

  • The retry must be the same request (same method, path, and body) with the payment header added.
  • The server processes payment and action atomically -- if payment succeeds, the action executes.
  • If the payment token is insufficient or invalid, the server returns another 402 with updated requirements.

Automated handling

The hrmw wallet handles the full 402 loop transparently:

  1. Sends the initial request
  2. Reads the 402 response and required_amount
  3. Selects a token from the local Webcash wallet
  4. Retries with X-Webcash-Secret

For Bitcoin rail:

hrmw <command> --payment-rail bitcoin --bitcoin-secret 'ark:<vtxo_txid>:<amount_sats>'

Paid actions

Actions that require payment include:

  • Identity registration
  • Timeline posts and comments
  • Profile updates (e.g., picture)
  • Ratings
  • Contract buy and pickup

Next steps