dfx cycles
Use the dfx cycles command to manage cycles associated with an identity's principal. dfx cycles uses the cycles ledger for cycles management.
The basic syntax for running dfx cycles commands is:
dfx cycles [subcommand] [options]
The following subcommands are available:
| Command | Description |
|---|---|
approve | Approves a principal to spend cycles on your behalf. |
balance | Prints the account balance of the current principal. |
convert | Convert some of the user's ICP balance into cycles. |
redeem-faucet-coupon | Redeem a code at the cycles faucet. |
top-up | Deposit cycles into a canister. |
transfer | Send cycles to another account. |
help | Displays usage information message for a specified subcommand. |
To view usage information for a specific subcommand, specify the subcommand and the --help flag. For example, to see usage information for dfx cycles balance, you can run the following command:
dfx cycles balance --help
dfx cycles approve
Use the dfx cycles approve command to approve a principal to spend cycles on your behalf.
Basic usage
dfx cycles approve [options] <spender> <amount>
Arguments
You must specify the following arguments for the dfx cycles approve command.
| Argument | Description |
|---|---|
<spender> | Allow this principal to spend cycles. |
<amount> | The number of cycles to approve. |
Options
You can specify the following options for the dfx cycles approve command.
| Option | Description |
|---|---|
--created-at-time <timestamp> | Specify the timestamp-nanoseconds for the created_at_time field on the transfer request. Useful for controlling transaction-de-duplication. |
--expected-allowance <cycles> | The number of previously approved cycles. See ICRC-2 specification for details. |
--expires-at <timestamp> | Timestamp-nanoseconds until which the approval is valid. None means that the approval is valid indefinitely. |
--from-subaccount <subaccount> | Approve cycles to be spent from the specified subaccount. |
--memo <memo> | Specifies a numeric memo for this transaction. |
--spender-subaccount <subaccount> | Allow the specified subaccount to spend cycles. |
Examples
Approve the principal raxcz-bidhr-evrzj-qyivt-nht5a-eltcc-24qfc-o6cvi-hfw7j-dcecz-kae to spend 1 billion cycles:
dfx cycles approve raxcz-bidhr-evrzj-qyivt-nht5a-eltcc-24qfc-o6cvi-hfw7j-dcecz-kae 1000000000 --network ic
Approve from a subaccount:
dfx cycles approve raxcz-bidhr-evrzj-qyivt-nht5a-eltcc-24qfc-o6cvi-hfw7j-dcecz-kae 1000000000 --from-subaccount 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f --network ic
dfx cycles balance
Use the dfx cycles balance command to print your account balance or that of another user.
Basic usage
dfx cycles balance [flag] --network ic
Options
You can specify the following arguments for the dfx cycles balance command.
| Option | Description |
|---|---|
--owner <principal> | Display the balance of the specified principal. |
--subaccount <subaccount> | Display the balance of the specified subaccount. |
--precise | Displays the exact balance, without scaling to trillions of cycles. |
Examples
Check the cycles balance of the selected identity.
$ dfx cycles balance --network ic
89.000 TC (trillion cycles).
To see the exact amount of cycles, you can use the --precise option:
$ dfx cycles balance --network ic --precise
89000000000000 cycles.
You can use the dfx cycles balance command to check the balance of another principal:
dfx cycles balance --owner raxcz-bidhr-evrzj-qyivt-nht5a-eltcc-24qfc-o6cvi-hfw7j-dcecz-kae --network ic
dfx cycles convert
Use the dfx cycles convert command to convert ICP into cycles that are stored on the cycles ledger.
Basic usage
dfx cycles convert [flag] --network ic
Options
You can specify the following arguments for the dfx cycles convert command.
| Option | Description |
|---|---|
--amount <amount> | Specify the number of ICP tokens to convert to cycles and deposit into your cycles ledger account. You can specify an amount as a number with up to eight (8) decimal places. |
--created-at-time <timestamp> | Specify the timestamp-nanoseconds for the created_at_time field on the ledger transfer request. Useful for transaction deduplication. |
--e8s <e8s> | Specify ICP token fractional units (called e8s) as a whole number, where one e8 is the smallest fraction of an ICP token. For example, 1.05000000 is 1 ICP and 5000000 e8s. You can use this option on its own or in conjunction with the --icp option. |
--fee <fee> | Specify a transaction fee. The default is 10000 e8s. |
--icp <icp> | Specify ICP tokens as a whole number. You can use this option on its own or in conjunction with --e8s. |
--deposit-memo <memo> | Memo used when depositing the minted cycles. |
--to-subaccount <subaccount> | Subaccount where the cycles are deposited. |
Examples
Convert 10 ICP into cycles:
$ dfx cycles convert --network ic --amount 10
Account was topped up with 1_234_567_000_000_000 cycles! New balance is 1_234_567_000_000_000 cycles.
To have the cycles deposited into a different subaccount, use the --to-subaccount option.
$ dfx cycles convert --network ic --amount 10 --to-subaccount 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
Account was topped up with 1_234_567_000_000_000 cycles! New balance is 1_234_567_000_000_000 cycles.
dfx cycles transfer
Use the dfx cycles transfer command to transfer cycles from your account to another account.
Basic usage
dfx cycles transfer [options] <to> <amount>
Arguments
You must specify the following arguments for the dfx cycles transfer command.
| Argument | Description |
|---|---|
<to> | The principal of the account to which you want to transfer cycles. |
<amount> | The number of cycles to transfer. |
Options
You can specify the following options for the dfx cycles transfer command.
| Option | Description |
|---|---|
--from <principal> | Transfer cycles from the specified principal. Requires that principal's approval. |
--to-subaccount <subaccount> | The subaccount to which you want to transfer cycles. |
--from-subaccount <subaccount> | The subaccount from which you want to transfer cycles. |
--spender-subaccount <subaccount> | Deduct allowance from this subaccount. Requires --from to be specified. |
--memo <memo> | Specifies a numeric memo for this transaction. |
--created-at-time <timestamp> | Specify the timestamp-nanoseconds for the created_at_time field on the transfer request. Useful for controlling transaction-de-duplication. |
Examples
Transfer 1 billion cycles to another account:
dfx cycles transfer raxcz-bidhr-evrzj-qyivt-nht5a-eltcc-24qfc-o6cvi-hfw7j-dcecz-kae 1000000000 --network ic
Transfer from a subaccount:
dfx cycles transfer raxcz-bidhr-evrzj-qyivt-nht5a-eltcc-24qfc-o6cvi-hfw7j-dcecz-kae 1000000000 --from-subaccount 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f --network ic
dfx cycles redeem-faucet-coupon
Use the dfx cycles redeem-faucet-coupon command to redeem a cycles faucet coupon.
This will redeem a coupon and deposit the cycles to your cycles ledger account.
Basic usage
dfx cycles redeem-faucet-coupon <your faucet coupon>
Arguments
Use the following necessary argument with the dfx cycles redeem-faucet-coupon command.
| Argument | Description |
|---|---|
<your faucet coupon> | The coupon code to redeem at the faucet. |
Flags
You can use the following optional flags with the dfx cycles redeem-faucet-coupon command.
| Flag | Description |
|---|---|
--faucet | Alternative faucet address. If not set, this uses the DFINITY faucet. |
--yes | Skips yes/no checks by answering 'yes'. Not recommended outside of CI. |
Example
If you have a coupon code ABCDE-ABCDE-ABCDE, you can redeem it like this:
dfx cycles redeem-faucet-coupon 'ABCDE-ABCDE-ABCDE'
This will print something like:
Redeemed coupon ABCDE-ABCDE-ABCDE to the cycles ledger for 10 TC (trillion cycles). New balance: 10 TC.
dfx cycles top-up
Use the dfx cycles top-up command to send cycles from your account to a canister.
Basic usage
dfx cycles top-up [options] <to> <amount>
Arguments
You must specify the following arguments for the dfx cycles transfer command.
| Argument | Description |
|---|---|
<to> | The name of a canister in the current project or a canister principal. |
<amount> | The number of cycles to transfer. |
Options
You can specify the following options for the dfx cycles top-up command.
| Option | Description |
|---|---|
--from-subaccount <subaccount> | The subaccount from which you want to transfer cycles. |
--created-at-time <timestamp> | Specify the timestamp-nanoseconds for the created_at_time field on the transfer request. Useful for controlling transaction deduplication. |
Examples
Send cycles to a canister in your project:
dfx cycles top-up my_backend 1000000000 --network ic
Send cycles to a canister by principal:
dfx cycles top-up bkyz2-fmaaa-aaaaa-qaaaq-cai 1000000000 --network ic