The Stacks CLI enables interactions with the Stacks blockchain through a set of commands.
First, ensure you have
npm installed. Next, run the following command in your terminal:
npm install -g @stacks/cli
-g flag makes the CLI commands available globally
By default, the CLI will attempt to interact with Stacks mainnet. However, it is possible to override the network and set it to testnet:
stx <command> -t
For account usage, that means addresses generated will only be available for the specific network. An account generated for testnet cannot be used on mainnet.
-t flag causes the CLI to connect to the testnet at
https://api.testnet.hiro.so. To specify a node to connect to, add the
-I flag followed by the URL of the node:
stx <command> -I "http://localhost:20443"
This section describes how to use the CLI to manage an account.
We don't recommended you use the CLI to handle accounts with real STX tokens on the mainnet. Instead, use an appropriate wallet to support secure token holding.
Creating an account
You can generate a new account for testnet by using the
make_keychain command with the
stx make_keychain -t
Your response should look like this:
"mnemonic": "private unhappy random runway boil scissors remove harvest fatigue inherit inquiry still before mountain pet tail mad accuse second milk client rebuild salt chase",
The mnemonic is your 24 word seed phrase, which you should back up securely if you want access to this account again in the future. Once lost, it cannot be recovered.
The Stacks address associated with the newly generated account is:
The preceding address is a testnet address that can only be used on testnet.
It is best to store the response of the CLI somewhere. You will need the private key, for instance, to send tokens to others.
You can check the balance of your account using the following command:
stx balance ST1BG7MHW2R524WMF7X8PGG3V45ZN040EB9EW0GQJ -t
The response should look like this:
To receive testnet STX tokens, use the faucet.
Take note that the nonce for the account is
0. Account nonce is important for transaction broadcasting.
This section describes how to use the CLI to generate and broadcast transactions.
In order to send tokens, the CLI command requires 5 parameters:
- Recipient Address: The Stacks address of the recipient
- Amount: The number of Stacks to send denoted in microstacks (1 STX = 1,000,000 microstacks)
- Fee Rate: The fee rate for this transaction. You can safely set a fee rate of 200 for testnet
- Nonce: The nonce is a number that needs to be incremented monotonically for each transaction from the account. This ensures transactions are not duplicated
- Private Key: This is the private key corresponding to your account
The CLI command to use with these parameters is
stx send_tokens ST2KMMVJAB00W5Z6XWTFPH6B13JE9RJ2DCSHYX0S7 1000 200 0 381314da39a45f43f45ffd33b5d8767d1a38db0da71fea50ed9508e048765cf301 -t
With this command we’re sending 1000 microstacks to the Stacks address
We set the fee rate to
You can add the
-e flag to estimate the transaction fee needed to get processed by the network, without broadcasting your transaction.
The nonce is set to
0 for this transaction, since it will be the first transaction we send from this account. For subsequent transactions, you will need to increment this number by
1 each time. You can check the current nonce for the account using the
Finally, the last parameter is the private key for the account.
Once again, we’re using the
-t option to indicate that this is a testnet transaction, so it should be broadcast to testnet.
If valid, the transaction will be broadcast to the network, and the command will respond with a transaction ID.
To obtain the raw, serialized transaction payload without broadcasting it, you can add the