Topping up a canister
Overview
A canister needs to have cycles deposited continuously into it to pay for the resources it uses. This process is known as 'topping up' the canister. Topping up canisters is routine maintenance.
Basic rules
Anyone can top up any canister deployed to ICP; you do not need to be the owner or controller of the canister. All you need is the canister's principal.
There are a few different ways to top up canisters:
Using
dfx cycles top-up.Through the NNS frontend dapp.
Through a third-party service (e.g. https://cycleops.dev).
Number of cycles
For ease of use, you can copy/paste the cycles amounts below:
| Cycles | Number |
|---|---|
| 1 million | 1000000 |
| 10 million | 10000000 |
| 100 million | 100000000 |
| 1 billion | 1000000000 |
| 10 billion | 10000000000 |
| 100 billion | 100000000000 |
| 1 trillion | 1000000000000 |
| 10 trillion | 10000000000000 |
| 100 trillion | 100000000000000 |
Canister top up workflows
The following examples will demonstrate how to interact with and top up a canister with the canister ID jqylk-byaaa-aaaal-qbymq-cai with one trillion cycles (1000000000000) or one ICP's worth of cycles. These instructions will work for any canister ID or cycles/ICP amount.
Checking the cycles balance of a canister
Canister cycles balances are available through the dfx canister status command. They are not exposed publicly by default; you can only see them if you are the controller of a canister:
dfx canister status jqylk-byaaa-aaaal-qbymq-cai --network=ic
Output
Canister status call result for jqylk-byaaa-aaaal-qbymq-cai.
Status: Running
Controllers: mto6d-zfnut-rlsxr-ogdeg-apo53-evpob-ljgnp-ma2x3-6yf3b-t4rd5-qqe t5j57-vyaaa-aaaal-qatsq-cai
Memory allocation: 0
Compute allocation: 0
Freezing threshold: 2_592_000
Memory Size: Nat(2471918)
Balance: 9_811_813_913_485 Cycles
Module hash: 0xe7866e1949e3688a78d8d29bd63e1c13cd6bfb8fbe29444fa606a20e0b1e33f0
Canisters can check their balance programmatically.
- Motoko
- Rust
Motoko canisters can use the ExperimentalCycles library to interact with cycles.
Rust canisters can use the function canister_balance128() from the Rust IC CDK.
Option 1: If you have ICP on your account
If you have ICP associated with your developer identity you can use dfx ledger top-up to convert some ICP into cycles, then top up a canister with those cycles:
Option 2: If you have cycles
If you already have cycles, you can top up a canister with the command dfx cycles top-up:
dfx cycles top-up jqylk-byaaa-aaaal-qbymq-cai 1T --network ic
Special case: topping up a cycles wallet
The cycles wallet will be removed from dfx in a future release.
It is recommended to use the cycles ledger instead.
Cycles wallets are canisters like any other. If you have a cycles wallet you control via dfx, there is another option for sending cycles from your cycles wallet to a canister of your choice: dfx wallet send [OPTIONS] <DESTINATION> <AMOUNT>.
Topping up a canister with the NNS frontend dapp
You can also top up any canister via the NNS frontend dapp:
Step 1: Navigate to the My Canisters section of the dapp.
Step 2: Click Link Canister.
Step 3: Add a canister principal. The user doesn't need to control the canister.
Step 4: Once the canister is added, click on that canister.
Step 5: Click
Add cyclesto add cycles using the ICP in your NNS frontend dapp.
Managing cycle depletion with freezing threshold
ICP features a mechanism to prevent canisters from running out of cycles. Canisters have a configurable freezing_threshold, dynamically evaluated in cycles.