Intent
A payment intent is a request to move balances in the ledger. Each intent contains one or more claims, where each claim describes a specific movement such as transferring funds between wallets, issuing new balances, or collecting fees.
The ledger processes all claims within an intent atomically — either every claim succeeds or none do. When source or target wallets have bridges assigned, those bridges participate in a two-phase commit protocol coordinated by the DTC (Distributed Transaction Coordinator). Each bridge must prepare the intent claims before the ledger commits them. When no bridges are involved, the intent is prepared and committed immediately.
Only transfer claims trigger bridge participation. Issue and destroy claims are resolved by the ledger without contacting bridges.
Each intent has a unique handle for idempotency and retrieval, and can carry custom data like invoice numbers or payment descriptions.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /intents | Submit a payment intent to move balances between wallets. |
| GET | /intents | Query intents with filtering, sorting, and pagination. |
| GET | /intents/{id} | Retrieve an intent by its handle or LUID. |
| POST | /intents/{id}/proofs | Submit a signed proof to an intent record. |
Access & History
| Method | Path | Description |
|---|---|---|
| POST | /intents/{id}/access/!check | Evaluate what actions a signer can perform on this intent. |
| GET | /intents/{id}/changes | Retrieve the change history of an intent by its handle or LUID. |
| GET | /intents/{id}/changes/{change} | Retrieve a change record for an intent by handle or LUID and change number. |
Related
- About Intents — how intents represent balance movement requests
- Intent Expiry — automatic expiration of pending intents
- Balance Reservations — how pending claims reserve balances
- Resolution Proofs — how bridge results feed back into intents
Get ledger change GET
Returns a single change by its sequence number. The change includes a full record snapshot as it existed at that point.
Create intent POST
The intent starts in `pending` status and enters the DTC flow. If source or target wallets have bridges assigned, each bridge must prepare the claim before the ledger commits it. Without bridges, the intent transitions through the full lifecycle almost instantly since there is no coordination with external systems. Status policies can customize the lifecycle by defining quorum requirements for each transition or introducing additional statuses. Intents cannot be updated after creation. Use proofs to advance the intent through its lifecycle or to record bridge responses. The handle must be unique within the ledger and can be used as a client-side idempotency key. Broadcasts the `intent-created` signal. Use [effects](/ledger/reference/api/effect) to subscribe.