dfx wallet
Use the dfx wallet command with subcommands and flags to manage the cycles wallets of your identities and to send cycles to the wallets of other account cycles wallet canisters.
The basic syntax for running the dfx wallet commands is:
dfx wallet [option] <subcommand> [flag]
Depending on the dfx wallet subcommand you specify, additional arguments, options, and flags might apply or be required.
To view usage information for a specific dfx wallet subcommand, specify the subcommand and the --help flag.
For example, to see usage information for dfx wallet send, you can run the following command:
dfx wallet send --help
For reference information and examples that illustrate using dfx wallet commands, select an appropriate command.
| Command | Description |
|---|---|
add-controller | Add a controller using the selected identity's principal. |
addresses | Displays the address book of the cycles wallet. |
authorize | Authorize a custodian by principal for the selected identity's cycles wallet |
balance | Displays the cycles wallet balance of the selected identity. |
controllers | Displays a list of the selected identity's cycles wallet controllers. |
custodians | Displays a list of the selected identity's cycles wallet custodians. |
deauthorize | Deauthorize a cycles wallet custodian using the custodian's principal. |
help | Displays a usage message and the help of the given subcommand(s). |
name | Returns the name of the cycles wallet if you've used the dfx wallet set-name command. |
remove-controller | Removes a specified controller from the selected identity's cycles wallet. |
send | Sends a specified amount of cycles from the selected identity's cycles wallet to another cycles wallet using the destination wallet canister ID. |
set-name | Specify a name for your cycles wallet. |
upgrade | Upgrade the cycles wallet's Wasm module to the current Wasm bundled with DFX. |
Using your wallet
After you have used the dfx identity deploy-wallet command to create a cycles wallet canister tied to an identity, you can use dfx wallet commands to modify your cycles wallet settings, send cycles to other cycles wallets, and add or remove controllers and custodians.
dfx wallet add-controller
Use the dfx wallet add-controller to add a controller to the wallet. An identity assigned the role of Controller has the most privileges and can perform the following actions on the selected identity's cycles wallet:
Rename the cycles wallet.
Add entries to the address book.
Add and remove controllers.
Authorize and deauthorize custodians.
A controller is also a custodian and can perform the following actions associated with that role:
Access wallet information.
Send cycles.
Forward calls.
Create canisters.
Basic usage
dfx wallet add-controller [option] <controller> [flag]
Flags
You can use the following optional flags with the dfx wallet add-controller command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Options
You can use the following options with the dfx canister call command.
| Option | Description |
|---|---|
--network <network> | Specifies the environment (e.g., {platform} or testnet) of the controller you want to add. |
Arguments
You can specify the following arguments for the dfx wallet add-controller command.
| Argument | Description |
|---|---|
controller | Specifies the principal of the controller to add to the wallet. |
Examples
You can use the dfx wallet add-controller command to add a controller to your wallet. If the controller you want to add is on a different environment, specify it using the --network option. For example:
dfx wallet --network=https://192.168.74.4 add-controller hpff-grjfd-tg7cj-hfeuj-olrjd-vbego-lpcax-ou5ld-oh7kr-kl9kt-yae
dfx wallet addresses
Use the dfx wallet addresses command to display the wallet's address book.The address entries contain the principal and role (Contact, Custodian, or Controller), and might contain a name, and kind (Unknown, User, or Canister) associated with the address.
Basic usage
dfx wallet addresses
Flags
You can use the following optional flags with the dfx wallet add-controller command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Examples
You can use the dfx wallet addresses command to retrieve information on the addresses in your wallet's address book. For example:
dfx wallet addresses
Id: hpff-grjfd-tg7cj-hfeuj-olrjd-vbego-lpcax-ou5ld-oh7kr-kl9kt-yae, Kind: Unknown, Role: Controller, Name: ic_admin.
Id: e7ptl-4x43t-zxcvh-n6s6c-k2dre-doy7l-bbo6h-ok8ik-msiz3-eoxhl-6qe, Kind: Unknown, Role: Custodian, Name: alice_auth.
dfx wallet authorize
Use the dfx wallet authorize command to authorize a custodian for the wallet. An identity assigned the role of custodian can perform the following actions on the cycles wallet:
Access wallet information.
Send cycles.
Forward calls.
Create canisters.
Basic usage
dfx wallet authorize <custodian> [flag]
Flags
You can use the following optional flags with the dfx wallet authorize command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Arguments
Use the following necessary argument with the dfx wallet authorize command.
| Argument | Description |
|---|---|
<custodian> | Specify the principal of the identity you would like to add as a custodian to the selected identity's cycles wallet. |
Example
For example, to add alice_auth as a custodian, specify her principal in the following command:
dfx wallet authorize dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae
dfx wallet balance
Use the dfx wallet balance command to display the balance of the cycles wallet of the selected identity.
Basic usage
dfx wallet balance
Flags
You can use the following optional flags with the dfx wallet balance command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Examples
Check the balance of the selected identity's cycles wallet.
dfx wallet balance
This command displays the number of cycles in your cycles wallet. For example:
89000000000000 cycles.
dfx wallet controllers
Use the dfx wallet controllers command to list the principals of the identities that are controllers of the selected identity's cycles wallet.
Basic usage
dfx wallet controllers
Flags
You can use the following optional flags with the dfx wallet controllers command.
|Flag |Description
|-h, --help |Displays usage information.
|-V, --version |Displays version information.
Examples
List the controllers of your selected identity's cycles wallet.
dfx wallet controllers
The information returned should look similar to the following if there are two controllers:
dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae
hpnmi-qgxsv-tgecj-hmjyn-gmfft-vbego-lpcax-ou4ld-oh7kr-l3nu2-yae
dfx wallet custodians
Use the dfx wallet custodians command to list the principals of the identities that are custodians of the selected identity's cycles wallet. Identities that are added as controllers are also listed as custodians.
Basic usage
dfx wallet custodians
Flags
You can use the following optional flags with the dfx wallet custodians command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
Examples
List the custodians of your selected identity's cycles wallet.
dfx wallet custodians
The information returned should look similar to the following if there are two custodians:
dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae
hpnmi-qgxsv-tgecj-hmjyn-gmfft-vbego-lpcax-ou4ld-oh7kr-l3nu2-yae
dfx wallet deauthorize
Use the dfx wallet deauthorize command to remove a custodian from the cycles wallet.
NOTE: that this will also remove the role of controller if the custodian is also a controller.
Basic usage
dfx wallet deauthorize <custodian> [flag]
Flags
You can use the following optional flags with the dfx wallet deauthorize command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Arguments
Use the following necessary argument with the dfx wallet deauthorize command.
| Argument | Description |
|---|---|
<custodian> | Specify the principal of the custodian you want to remove. |
Example
For example, to remove "alice_auth" as a custodian, specify her principal in the following command:
dfx wallet deauthorize dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae
dfx wallet name
Use the dfx wallet name command to display the name of the selected identity's cycles wallet if it has been set using the dfx wallet set-name command.
Basic usage
dfx wallet name [flag]
Flags
You can use the following optional flags with the dfx wallet name command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Example
If you have named your cycles wallet "Terrances_wallet", then the command would return the following:
Terrances_wallet
dfx wallet remove-controller
Use the dfx wallet remove-controller command to remove a controller of your selected identity's cycles wallet.
Basic usage
dfx wallet remove-controller <controller> [flag]
Flags
You can use the following optional flags with the dfx wallet remove-controller command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Arguments
Use the following necessary argument with the dfx wallet remove-controller command.
|Argument |Description
|<controller> | Specify the principal of the controller you want to remove.
Example
For example, to remove alice_auth as a controller, specify her principal in the following command:
dfx wallet remove-controller dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae
dfx wallet send
Use the dfx wallet send command to send cycles from the selected identity's cycles wallet to another cycles wallet using the destination cycle wallet's Canister ID.
Basic usage
dfx wallet [network] send [flag] <destination> <amount>
Flags
You can use the following optional flags with the dfx wallet send command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Options
You can use the following option with the dfx wallet send command.
| Option | Description |
|---|---|
--network | Override the environment to connect to. By default, the local canister execution environment is used. A valid URL (starting with http: or https:) can be specified here. E.g. "http://localhost:12345/" is a valid network name. |
Arguments
You must specify the following arguments for the dfx wallet send command.
| Argument | Description |
|---|---|
<destination> | Specify the destination cycle wallet using its Canister ID. |
<amount> | Specify the number of cycles to send. |
Examples
Send cycles from the selected identity's cycles wallet to another cycles wallet.
For example, to send 2,000,000,000 cycles from the cycles wallet of the selected identity, <ic_admin>, to the cycles wallet of the destination identity, <buffy_standard> with a wallet address r7inp-6aaaa-aaaaa-aaabq-cai, run the following command:
dfx wallet send r7inp-6aaaa-aaaaa-aaabq-cai 2000000000
dfx wallet set-name
Use the dfx wallet set-name command to assign a name to the selected identity's cycles wallet.
Basic usage
dfx wallet set-name [flag] <name>
Arguments
You must specify the following arguments for the dfx wallet set-name command.
| Argument | Description |
|---|---|
<name> | Specify a name for the cycles wallet. |
Flags
You can use the following optional flags with the dfx wallet set-name command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Example
If you want to set the name of the current identity's cycles wallet to "Terrances_wallet" you can run the following command:
dfx wallet set-name Terrances_wallet
dfx wallet upgrade
Use the dfx wallet upgrade command to upgrade the cycle wallet's Wasm module to the current Wasm bundled with DFX.
Basic usage
dfx wallet upgrade [flag]
Flags
You can use the following optional flags with the dfx wallet upgrade command.
| Flag | Description |
|---|---|
-h, --help | Displays usage information. |
-V, --version | Displays version information. |
Example
To upgrade the Wasm module to the latest version, run the following command:
dfx wallet upgrade