dfx cycles
Use the dfx cycles command to manage cycles associated with an identity's principal.
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 user. |
convert | Convert some of the user's ICP balance into cycles. |
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 this subaccount. |
--memo <memo> | Specifies a numeric memo for this transaction. |
--spender-subaccount <subaccount> | Allow this 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 this principal |
--subaccount <subaccount> | Display the balance of this 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. https://internetcomputer.org/docs/developer-docs/integrations/icrc-1/#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 this 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. https://internetcomputer.org/docs/developer-docs/integrations/icrc-1/#transaction-deduplication- |
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 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. https://internetcomputer.org/docs/developer-docs/integrations/icrc-1/#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