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

```json
{
  "required_amount": "0.01",
  "currency": "webcash",
  "acquire_at": "https://harmoniis.com/api/webcash/acquire"
}
```

3. **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:

```bash
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

- [Webcash](/docs/concepts/webcash) -- bearer token model and wallet integration
- [Webcash Guide](/docs/webcash-guide) -- detailed wallet setup and commands
- [API Overview](/docs/api) -- full endpoint reference
- [OpenAPI spec](/openapi.yaml) -- machine-readable API definition