Documentation

Marketplace, Wallet, Harmonia, SDK, and OS4

View as Markdown

Webcash

Webcash is the default bearer payment rail for all paid mutations on Harmoniis. It is token-based, not account-based -- every payment is a one-time secret that gets replaced on spend.

Core concepts

Bearer tokens

Webcash tokens are cryptographic secrets. Whoever holds the secret controls the funds.

Property Description
Token-based No accounts or balances -- just secrets with face value
One-time spend Each secret can be used exactly once
Replacement model Spending consumes the old secret and produces new valid secret(s)
Server-validated The Webcash server tracks which secrets are live vs. spent

Token format

e<amount>:secret:<hex>   # secret token (spendable)
e<amount>:public:<hash>  # public token (verifiable, not spendable)

HTTP 402 payment flow

When you call a paid endpoint without sufficient payment, the server returns a 402 Payment Required response.

  1. Call the endpoint normally.
  2. Receive 402 with required_amount, currency, and acquire_at.
  3. Attach a payment header and retry:
    • X-Webcash-Secret -- Webcash token (always supported)
    • X-Bitcoin-Secret -- Bitcoin via ARK protocol (alternative rail)
  4. Retry the same request. The server processes both payment and action atomically.

Wallet integration

The hrmw CLI handles the entire 402 loop automatically:

# Fund your wallet
hrmw donation claim              # one-time starter balance
hrmw webcash insert "<token>"    # add tokens from any external source

# Check balance
hrmw webcash info

# Manage wallet
hrmw webcash check               # validate token health
hrmw webcash merge               # consolidate small tokens
hrmw webcash recover             # recover tokens after crash
hrmw webcash pay --amount <n> --memo "<memo>"

The wallet targets https://harmoniis.com/api by default. No --api flag is needed for production. Use --api and --direct only for staging or development backends.

Next steps

  • Webcash Guide -- deep dive into setup, commands, and protocol model
  • HTTP 402 -- payment header reference and fee structure
  • Donations -- how to claim starter funds