2026-07-31 — Wallet ledger and holds

Wallets now use pockets and a double-entry ledger; holds reserve funds before settlement.

Pockets

Each wallet has an available pocket (and you can add more). Balances live on pockets; the wallet total is the sum of available pocket balances.

List wallets (with pockets):

• GET /v1/api/wallet
• GET /v1/api/user/wallets (same data)

Move money

Transfer between pockets in the same wallet:

POST /v1/api/wallet/transfer

Include a stable idempotencyKey so retries do not double-post.

Holds (pay-class)

Reserve funds before an action settles:

1. POST /v1/api/wallet/holds — reserve
2. POST /v1/api/wallet/holds/:holdId/capture — settle (queues payment rail work)
3. POST /v1/api/wallet/holds/:holdId/release — return funds

Top-up

POST /v1/api/wallet/topup credits a pocket and queues a checkout intent on the payment rail.

All of these routes need a signed-in session.