Interact with the ICP ledger
Interact with ICP ledger from the command line
dfx provides a convenience command to interact with the ICP ledger canister and related functionality. You can find the documentation here or just enter the following command into your console:
dfx ledger --help
It's worth checking out the
--help flag of the subcommands as well.
dfx exposes only a subset of the ICP ledger functionality, namely
Both commands provide a flag to specify a ledger canister id (
--ledger-canister-id). This simplifies interacting with a local ledger deployment or other tokens that provide the same interface.
Get the ICP balance of a specific account:
dfx ledger --network ic balance <account-id>
<account-id> is encoded as a hex string. You can print the account id of the current
dfx identity by running:
dfx ledger account-id
In many cases you want to check the main account balance of a specific principal. You can combine the
balance command with the
account-id command, while specifying an
--of-principal argument to yield this helpful command:
dfx ledger --network ic balance $(dfx ledger account-id --of-principal <principal-id>)
The transfer function can be used to transfer ICP from your account to another.
dfx ledger --network ic transfer --amount <amount> --memo <memo> <receiver-account-id>
Interact with ICP ledger from your web application
Interact with ICP from a canister
The ICP transfer example provides a good starting point for interacting with ICP ledger from a canister. The example showcases the usage of
transfer in Motoko and Rust.
If you want a canister to receive payment in ICP you need to make sure that the canister knows about the payment, because a transfer only involves the sender and the ledger canister.
There are currently two main patterns to achieve this. Furthermore, there is a chartered working group on Ledger & Tokenization which is focused on defining a standard ledger/token interface as well payment flows.
Direct notification by sender
In this pattern the sender notifies the receiver about the payment. However, the receiver needs to verify the payment by using the
query_blocks interface of the ledger.
The following diagram shows a simplified illustration of this pattern:
Notification by ICP ledger (currently disabled)
In this pattern the ledger itself notifies the receiver. Thereby, the receiver can trust the notification immediately. However, this flow is currently disabled because the call to the receiver is not yet implemented as a one-way call.
icrc-ledger-types Rust crate
To interact with ICRC-1 and ICRC-2 compatible canisters, the Rust crate icrc-ledger-types can be used.
The crate can be installed with the command:
cargo add icrc-ledger-types
Or, it can be added to the
icrc-ledger-types = "0.1.1"
The documentation for this crate can be found here.