# 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:

```bash
# 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](/docs/webcash-guide) -- deep dive into setup, commands, and protocol model
- [HTTP 402](/docs/http-402) -- payment header reference and fee structure
- [Donations](/docs/concepts/donations) -- how to claim starter funds