Tokens and Cycles
This guide covers managing ICP tokens and cycles with icp-cli.
Overview
The Internet Computer uses two types of currency:
| Currency | Purpose | Used For |
|---|---|---|
| ICP | Governance token | Trading, staking, converting to cycles |
| Cycles | Computational fuel | Running canisters, paying for storage and compute |
Canisters consume cycles to operate. To deploy and run canisters on the IC mainnet, you need cycles.
Checking Balances
ICP Token Balance
Check your ICP balance:
# On IC mainneticp token balance -n ic
# On local network (for testing)icp token balanceCycles Balance
Check your cycles balance:
# On IC mainneticp cycles balance -n ic
# On local networkicp cycles balanceCanister Cycles Balance
Check how many cycles a specific canister has:
# On IC mainneticp canister status <canister-id> -n icThe output includes the canister’s cycles balance.
Transferring ICP
Send ICP tokens to another principal:
# On IC mainneticp token transfer <AMOUNT> <RECEIVER> -n icExample:
# Send 1 ICPicp token transfer 1 aaaaa-aa -n ic
# Send 0.5 ICPicp token transfer 0.5 xxxxx-xxxxx-xxxxx-xxxxx-cai -n icThe receiver can be a principal ID or account identifier.
Converting ICP to Cycles
Note: You need ICP tokens before you can convert them to cycles. See Getting ICP and Cycles below if you don’t have ICP yet.
Convert ICP tokens to cycles for use with canisters:
# Convert a specific amount of ICP on IC Mainneticp cycles mint --icp 1 -n ic
# Or request a specific amount of cycles (ICP calculated automatically) on IC Mainneticp cycles mint --cycles 1000000000000 -n icThe conversion rate is determined by the current ICP/XDR exchange rate. One trillion cycles (1T = 1,000,000,000,000) costs approximately 1 XDR worth of ICP.
Topping Up Canisters
Add cycles to a canister to keep it running:
icp canister top-up <canister-id> --amount 1000000000000 -n icThe --amount is specified in cycles (not ICP).
Monitoring Cycles
Regularly check canister cycles to avoid running out:
# Check all canisters in an environmenticp canister status -e my-env
# Check specific canistericp canister status my-canister -e my-envGetting ICP and Cycles
On IC Mainnet
To get ICP tokens:
- Receive from another wallet — Share your principal:
icp identity principal - Purchase on an exchange — Buy ICP and withdraw to your principal
To get cycles:
- Convert ICP — Use
icp cycles mintafter acquiring ICP - Receive cycles — Someone can transfer cycles to your principal via the cycles ledger
On Local Network
Local networks have unlimited cycles for testing. The default identity is automatically funded.
Working with Different Tokens
icp-cli supports ICRC-1 tokens beyond ICP:
# Check balance of a specific token on IC Mainneticp token <TOKEN_CANISTER_ID> balance -n ic
# Transfer a specific token on IC Mainneticp token <TOKEN_CANISTER_ID> transfer 100 <RECEIVER> -n icReplace <TOKEN_CANISTER_ID> with the canister ID of the token ledger.
Using Different Identities
Specify which identity to use for token operations:
# Check balance for a specific identity on IC Mainneticp token balance --identity my-other-identity -n ic
# Transfer using a specific identity on IC Mainneticp token transfer 1 <RECEIVER> --identity my-wallet -n icTroubleshooting
“Insufficient balance”
Your account doesn’t have enough ICP or cycles. Check your balance:
# For IC Mainneticp token balance -n icicp cycles balance -n ic
# For the local networkicp token balance -n localicp cycles balance -n local“Canister out of cycles”
Top up the canister:
# On IC mainneticp canister top-up <canister-id> --amount 1000000000000 -n ic
# In an environment callend `prod-env`icp canister top-up <canister-name> --amount 1000000000000 -e prod-envTransfer fails
Verify:
- The receiver address is correct
- You have sufficient balance (including fees)
- You’re using the correct identity
Next Steps
- Deploying to Mainnet — Use cycles to deploy canisters
- Managing Identities — Manage keys and principals