Symbol
A symbol defines a unit of exchange such as a currency, loyalty points, or any other countable value. Every balance in the ledger is denominated in a symbol.
All amounts and balances are stored as integers in the smallest unit of the symbol. The factor field defines the conversion: multiply a decimal amount by the factor to get the integer value. For example, with a factor of 100, the amount $15.50 is stored as 15.50 × 100 = 1550. To display the value, divide: 1550 ÷ 100 = 15.50.
The owner of a symbol controls its supply by issuing new units. Once issued, balances move between wallets under the ledger's access rules.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /symbols | Define a new unit of exchange in the ledger. |
| GET | /symbols | Query symbols with filtering, sorting, and pagination. |
| GET | /symbols/{id} | Retrieve a symbol by its handle or LUID. |
| PUT | /symbols/{id} | Submit a new version of a symbol. |
| POST | /symbols/{id}/proofs | Submit a signed proof to a symbol record. |
Access & History
| Method | Path | Description |
|---|---|---|
| POST | /symbols/{id}/access/!check | Evaluate what actions a signer can perform on this symbol. |
| GET | /symbols/{id}/changes | Retrieve the change history of a symbol by its handle or LUID. |
| GET | /symbols/{id}/changes/{change} | Retrieve a change record for a symbol by handle or LUID and change number. |
Related
- Key Concepts — how symbols fit into the ledger domain model
- About Wallets — how wallets hold balances in symbols
Get wallet change GET
Returns a single change by its sequence number. The change includes a full record snapshot as it existed at that point.
Create symbol POST
The `factor` must be a power of 10. Common values: `100` for fiat currencies like USD and EUR, `1` for currencies without subdivisions like JPY, and `100000000` for Bitcoin (satoshis). Broadcasts the `symbol-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.