dfx cycles
NOTE: The cycles ledger is in development and the dfx cycles command is not expected to work on mainnet at this time.
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/current/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/current/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/current/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