Wallet
A wallet holds balances of one or more symbols. Each wallet is identified by a user-defined handle such as a phone number, email, or account number, chosen to suit the use case.
Wallets can model bank accounts, loyalty programs, subscriptions, loans, or any other concept that carries a balance.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /wallets | Register a new wallet that can hold balances in one or more symbols. |
| GET | /wallets | Query wallets with filtering, sorting, and pagination. |
| GET | /wallets/{id} | Retrieve a wallet by its handle or LUID. |
| PUT | /wallets/{id} | Submit a new version of a wallet. |
| DELETE | /wallets/{id} | Permanently remove a wallet from the ledger. |
| POST | /wallets/{id}/proofs | Submit a signed proof to a wallet record. |
Balances & Links
| Method | Path | Description |
|---|---|---|
| GET | /wallets/{id}/balances | Retrieve all balances held by a wallet across symbols. |
| GET | /wallets/{id}/limits | Retrieve balance limits configured for a wallet. |
| GET | /wallets/{id}/anchors | Retrieve anchors linked to a wallet. |
| POST | /wallets/{id}/anchors/!lookup | Search for anchors linked to a wallet using advanced filters. |
| GET | /wallets/{id}/domains | Retrieve domains associated with a wallet. |
Access & History
| Method | Path | Description |
|---|---|---|
| POST | /wallets/{id}/access/!check | Evaluate what actions a signer can perform on this wallet. |
| GET | /wallets/{id}/changes | Retrieve the change history of a wallet by its handle or LUID. |
| GET | /wallets/{id}/changes/{change} | Retrieve a change record for a wallet by handle or LUID and change number. |
Related
- About Wallets — what wallets represent and how they hold balances
- Balance Reservations — how pending intents affect available balances
- Wallet Limits — how balance limits work
Get intent change GET
Returns a single change by its sequence number. The change includes a full record snapshot as it existed at that point.
Create wallet POST
The wallet is created with an empty balance sheet. Balances are managed exclusively through intents — issue claims add balance, transfer claims move it between wallets, and destroy claims remove it. Wallets support routes that forward debits or credits to other wallets, enabling flexible payment topologies. Broadcasts the `wallet-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.