🛠️
Stacks Documentation
  • Start Here
  • 🧠Concepts
    • Stacks 101
      • What Is Stacks?
      • Bitcoin Connection
      • Proof of Transfer
      • Stacks Among Other Layers
      • Financial Incentive and Security Budget
    • Network Fundamentals
      • Network Basics
      • Mainnet and Testnets
      • Accounts
      • Authentication
      • Bitcoin Name System
      • SIPs
      • Technical Specifications
    • Block Production
      • Mining
      • Signing
      • Bitcoin Finality
      • Bitcoin Reorgs
      • Stacking
    • Transactions
      • How Transactions Work
      • Post Conditions
    • Clarity
      • Overview
      • Decidability
    • sBTC
      • Core Features
      • sBTC Operations
        • Deposit
        • Withdrawal
        • Deposit vs Withdrawal Times
      • Emily API
      • Peg Wallet UTXO
      • Clarity Contracts
        • sBTC Registry
        • sBTC Token
        • sBTC Deposit
        • sBTC Withdrawal
      • Auxiliary Features
        • Transaction Fee Sponsorship
        • Signer Wallet Rotation
      • Walkthroughs
        • Signer Process Walkthrough
        • sBTC Transaction Walkthrough
      • sBTC FAQ
    • Gaia
      • Configuration
      • Deploy Gaia Hub
      • Amazon EC2
      • Linux
      • Mac OS
  • 🛠️Guides & Tutorials
    • Developer Quickstart
    • Clarity Crash Course
    • Build a Borrowing & Lending Protocol
    • Bitcoin Integration
      • Sending Bitcoin with Leather Wallet
      • Verifying a Bitcoin Transaction
      • Parsing a Bitcoin Transaction
    • Create Tokens
      • Creating a NFT
      • Creating a Fungible Token
    • Build a Frontend
      • Post Conditions with Stacks.js
      • Authentication with Stacks.js
      • Sending Transactions with Stacks.js
    • Testing Smart Contracts
      • Fuzz Testing
    • Run a Node
      • Run a Node with Docker
      • Run a Node with Digital Ocean
      • Run a Node with a Hosted Provider
      • Run a Node with Quicknode
      • Run a Bitcoin Node
      • Run a Pruned Bitcoin Node
    • Run a Miner
      • Miner Prerequisites
      • Miner Costs and Fees
      • Mine Testnet Stacks Tokens
      • Mine Mainnet Stacks Tokens
      • Verify Miner
    • Run a Signer
      • Signer Quickstart
      • How to Read Signer Logs
      • How to Monitor a Signer
      • Best practices for running a Signer
      • OpSec Best Practices
    • sBTC
      • How to Run an sBTC Signer
      • Best practices for running an sBTC Signer
      • How to Use the sBTC Bridge
      • Earn sBTC Rewards
    • Stack STX
      • Solo Stack
      • Operate a Pool
      • Stack with a Pool
      • Increase Stacked Position
      • Stop Stacking
    • Oracles
    • Community Tutorials
  • 📚Reference
    • API
    • Clarity Types
    • Clarity Functions
    • Clarity Keywords
    • Stacks Node Configuration
    • Signer Configuration
    • Stacks Tooling
  • 🏗️Example Contracts
    • Audited Starter Contracts
    • Stacking
    • BNS
    • Multi Send
  • 🧡Press & Top Links
    • 🔶2024
      • 🔸January 2024
      • 🔸February 2024
      • 🔸March 2024
      • 🔸April 2024
      • 🔸May 2024
      • 🔸June 2024
      • 🔸July 2024
      • 🔸August 2024
      • 🔸September 2024
      • 🔸October 2024
      • 🔸November 2024
      • 🔸December 2024
    • 🔶2025
      • 🔸January 2025
      • 🔸February 2025
      • 🔸March 2025
  • 🧡Bitcoin Theses and Reports
    • 🟠Bitcoin Theses
    • 📙Bitcoin Reports
  • Contribute
Powered by GitBook
On this page
  • Step 1 - Prerequisites
  • Step 2 - Set Up Your Stacks Signer
  • Download the stacks-signer binary
  • Create the configuration file
  • Verify the setup
  • Start the signer
  • Step 3a - Set up a Bitcoin node (Optional but strongly recommended)
  • Step 3b - Set Up Your Stacks Node
  • Download the stacks-node binary
  • Create the configuration file
  • Optional: Start the node with a data archive
  • Verify the setup
  • Start the node
  • Step 5 - Generate your signer signature
  • Step 6 - Start stacking
  • Step 7 - Monitoring

Was this helpful?

  1. Guides & Tutorials
  2. Run a Signer

Signer Quickstart

PreviousRun a SignerNextHow to Read Signer Logs

Last updated 3 months ago

Was this helpful?

Current Signer and Stacks Node Versions

Stacks Signer - 3.1.0.0.5.0

Stacks Node - 3.1.0.0.5

If you want to get up and running as an active signer as quickly as possible, here is a list of the commands you need to run and actions to take.

If you are not familiar with how signing works yet, be sure to check out the concept guide.

If you would like a more detailed walkthrough of all of these steps, take a look at the guide.

Step 1 - Prerequisites

# Create the required directories
mkdir -p ~/stacks-signer/data
mkdir -p ~/stacks-node/data

# Install needed packages
sudo apt install -y npm wget unzip jq tar

# Install Stacks CLI globally
npm install --global @stacks/cli

# Generate a new account and store details in a file
stx make_keychain | jq > ~/stacks-signer/keychain.json
# Create the required directories
mkdir -p ~/stacks-signer/data
mkdir -p ~/stacks-node/data

# Install needed packages
sudo apt install -y npm wget unzip jq tar

# Install Stacks CLI globally
npm install --global @stacks/cli

# Generate a new account and store details in a file
# '-t' option makes this a testnet account
stx make_keychain -t | jq > ~/stacks-signer/keychain.json

The account file previously created looks like this:

{
  "mnemonic": "aaa bbb ccc ddd ...",
  "keyInfo": {
    "privateKey": "65f3...",
    "publicKey": "03a3...",
    "address": "SP1G...",
    "btcAddress": "19tg...",
    "wif": "Kzdt...",
    "index": 0
  }
}

From this file, you'll need the privateKey value.

Step 2 - Set Up Your Stacks Signer

Download the stacks-signer binary

Assuming a Linux x64 glibc machine, the commands to download and uncompress the signer binary look like this:

# Enter the signer directory
cd ~/stacks-signer

# Download the signer binary zip
wget https://github.com/stacks-network/stacks-core/releases/download/signer-3.1.0.0.5.0/linux-glibc-x64.zip

# Unzip the signer binary archive
unzip linux-glibc-x64.zip

Create the configuration file

Create the configuration file required to start the signer (be sure to replace <your_token> and <your_private_key> with your auth token and private key values):

# Set environment variables
AUTH_TOKEN=<your_token> # Used for signer-node authentication
PRIVATE_KEY=<your_private_key> # privateKey from Step 1, this is the signer's private key

# Create the signer's configuration file
cat <<EOF> ~/stacks-signer/signer-config.toml
node_host = "127.0.0.1:20443"
endpoint = "127.0.0.1:30000"
network = "mainnet"
db_path = "$HOME/stacks-signer/data/signer.sqlite"
auth_password = "$AUTH_TOKEN"
stacks_private_key = "$PRIVATE_KEY"
metrics_endpoint = "127.0.0.1:9154"
block_proposal_timeout_ms = 180000
tenure_idle_timeout_secs = 120
EOF
# Set environment variables
AUTH_TOKEN=<your_token> # Used for signer-node authentication
PRIVATE_KEY=<your_private_key> # privateKey from Step 1, this is the signer's private key

# Create the signer's configuration file
cat <<EOF> ~/stacks-signer/signer-config.toml
node_host = "127.0.0.1:20443"
endpoint = "127.0.0.1:30000"
network = "testnet"
db_path = "$HOME/stacks-signer/data/signer.sqlite"
auth_password = "$AUTH_TOKEN"
stacks_private_key = "$PRIVATE_KEY"
metrics_endpoint = "127.0.0.1:9154"
block_proposal_timeout_ms = 180000
EOF

Verify the setup

To ensure the signer has been set up correctly, you can run the following commands:

# Verify the signer's version
~/stacks-signer/stacks-signer --version

# Output:
stacks-signer stacks-signer signer-3.1.0.0.5.0 (release/signer-3.1.0.0.5.0:513dbc5, release build, linux [x86_64])

# Verify the config file
~/stacks-signer/stacks-signer check-config -c ~/stacks-signer/signer-config.toml 

# Output:
Config: 
Stacks node host: 127.0.0.1:20443
Signer endpoint: 127.0.0.1:30000
Stacks address: SP1G... # address from keychain file
Public key: 03a3... # publicKey from keychain file
Network: mainnet # or testnet
Chain ID: 0x1 # or 0x80000000 for testnet
Database path: /home/admin/stacks-signer/data/signer.sqlite
Metrics endpoint: 127.0.0.1:9154

Start the signer

If the outputs of the previous commands are correct, you can proceed and start the signer:

~/stacks-signer/stacks-signer run -c ~/stacks-signer/signer-config.toml

Step 3a - Set up a Bitcoin node (Optional but strongly recommended)

In order to optimize signer health and performance, we highly recommend setting up your own Bitcoin node rather than relying on a third-party node.

Step 3b - Set Up Your Stacks Node

Download the stacks-node binary

Assuming a Linux x64 glibc machine, the commands to download and uncompress the node binary look like this:

# Enter the node directory
cd ~/stacks-node

# Download the node binary zip
wget https://github.com/stacks-network/stacks-core/releases/download/3.1.0.0.5/linux-glibc-x64.zip

# Unzip the node binary archive
unzip linux-glibc-x64.zip

Create the configuration file

Create the configuration file required to start the node (be sure to replace <your_token> with your auth token value):

If you run your own bitcoin node, you'll have to update peer_host and optionally add rpc_port, peer_port, username and password fields under the [burnchain] section of the node's configuration file.

# Set environment variables
AUTH_TOKEN=<your_token> # Used for signer-node authentication, same token as the one set up in the signer configuration

# Create the node's configuration file
cat <<EOF> ~/stacks-node/node-config.toml
[node]
working_dir = "$HOME/stacks-node/data"
rpc_bind = "127.0.0.1:20443"
p2p_bind = "0.0.0.0:20444"
prometheus_bind = "127.0.0.1:9153" 
bootstrap_node = "02196f005965cebe6ddc3901b7b1cc1aa7a88f305bb8c5893456b8f9a605923893@seed.mainnet.hiro.so:20444,02539449ad94e6e6392d8c1deb2b4e61f80ae2a18964349bc14336d8b903c46a8c@cet.stacksnodes.org:20444,02ececc8ce79b8adf813f13a0255f8ae58d4357309ba0cedd523d9f1a306fcfb79@sgt.stacksnodes.org:20444,0303144ba518fe7a0fb56a8a7d488f950307a4330f146e1e1458fc63fb33defe96@est.stacksnodes.org:20444"
stacker = true

[burnchain]
chain = "bitcoin"
mode = "mainnet"
peer_host = "bitcoin.mainnet.stacks.org"

[connection_options]
auth_token = "$AUTH_TOKEN"

[[events_observer]]
endpoint = "127.0.0.1:30000"
events_keys = ["stackerdb", "block_proposal", "burn_blocks"]
EOF
# Set environment variables
AUTH_TOKEN=<your_token> # Used for signer-node authentication, same token as the one set up in the signer configuration

# Create the node's configuration file
cat <<EOF> ~/stacks-node/node-config.toml
[node]
working_dir = "$HOME/stacks-node/data"
rpc_bind = "127.0.0.1:20443"
p2p_bind = "0.0.0.0:20444"
bootstrap_node = "029266faff4c8e0ca4f934f34996a96af481df94a89b0c9bd515f3536a95682ddc@seed.testnet.hiro.so:30444"
prometheus_bind = "127.0.0.1:9153" 
stacker = true
pox_sync_sample_secs = 30
always_use_affirmation_maps = true
require_affirmed_anchor_blocks = true

[burnchain]
mode = "krypton"
peer_host = "bitcoin.regtest.hiro.so"
peer_port = 18444
pox_prepare_length = 100
pox_reward_length = 900

[connection_options]
auth_token = "$AUTH_TOKEN"
private_neighbors = false

[[events_observer]]
endpoint = "127.0.0.1:30000"
events_keys = ["stackerdb", "block_proposal", "burn_blocks"]

[[ustx_balance]]
address = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2"
amount = 10000000000000000

[[ustx_balance]]
address = "ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF"
amount = 10000000000000000

[[ustx_balance]]
address = "ST221Z6TDTC5E0BYR2V624Q2ST6R0Q71T78WTAX6H"
amount = 10000000000000000

[[ustx_balance]]
address = "ST2TFVBMRPS5SSNP98DQKQ5JNB2B6NZM91C4K3P7B"
amount = 10000000000000000

[[burnchain.epochs]]
epoch_name = "1.0"
start_height = 0

[[burnchain.epochs]]
epoch_name = "2.0"
start_height = 0

[[burnchain.epochs]]
epoch_name = "2.05"
start_height = 1

[[burnchain.epochs]]
epoch_name = "2.1"
start_height = 2

[[burnchain.epochs]]
epoch_name = "2.2"
start_height = 3

[[burnchain.epochs]]
epoch_name = "2.3"
start_height = 4

[[burnchain.epochs]]
epoch_name = "2.4"
start_height = 5

[[burnchain.epochs]]
epoch_name = "2.5"
start_height = 6

[[burnchain.epochs]]
epoch_name = "3.0"
start_height = 1_900

[[burnchain.epochs]]
epoch_name = "3.1"
start_height = 2_000
EOF

Optional: Start the node with a data archive

# Enter the node's datadir
cd ~/stacks-node/data

# Download the archive
wget https://archive.hiro.so/mainnet/stacks-blockchain/mainnet-stacks-blockchain-latest.tar.gz

# Decompress the archive
tar -xvf mainnet-stacks-blockchain-latest.tar.gz

# Remove the archive
rm mainnet-stacks-blockchain-latest.tar.gz
# Enter the node's datadir
cd ~/stacks-node/data

# Download the archive
wget https://archive.hiro.so/testnet/stacks-blockchain/testnet-stacks-blockchain-latest.tar.gz

# Decompress the archive
tar -xvf testnet-stacks-blockchain-latest.tar.gz

# Remove the archive
rm testnet-stacks-blockchain-latest.tar.gz

Verify the setup

To ensure the node has been set up correctly, you can run the following commands:

# Verify the node's version
~/stacks-node/stacks-node version

# Output:
INFO [1738695915.769633] [testnet/stacks-node/src/main.rs:278] [main] stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])
stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])

# Verify the node's config
~/stacks-node/stacks-node check-config --config ~/stacks-node/node-config.toml

# Output:
INFO [1738695915.769633] [testnet/stacks-node/src/main.rs:278] [main] stacks-node 3.1.0.0.5 (release/3.1.0.0.5:513dbc5, release build, linux [x86_64])
INFO [1729788064.913175] [testnet/stacks-node/src/main.rs:318] [main] Loading config at path /home/admin/stacks-node/node-config.toml
INFO [1729788064.969551] [testnet/stacks-node/src/main.rs:331] [main] Loaded config!

Start the node

If the outputs of the previous commands are correct, you can proceed and start the node:

~/stacks-node/stacks-node start --config ~/stacks-node/node-config.toml

Step 5 - Generate your signer signature

The command to generate a signature looks like this:

~/stacks-signer/stacks-signer generate-stacking-signature \
  --method stack-stx \
  --max-amount 1000000000000 \
  --auth-id 195591226970828652622091037492597751808 \
  --period 12 \
  --reward-cycle 100 \
  --pox-address 19tg... \
  --config ~/stacks-signer/signer-config.toml \
  --json

Step 6 - Start stacking

Step 7 - Monitoring

Official binaries are available from the . Each release includes pre-built binaries. Download the for your server’s architecture and decompress it. Inside of that folder is a stacks-signer binary.

We have created guides for running both a and a you can follow.

Official binaries are available from the . Each release includes pre-built binaries. Download the for your server’s architecture and decompress it. Inside of that folder is a stacks-node binary.

For mainnet, we strongly recommended that you run your own bitcoin node (you can follow guides on how to run a or a ) in order to ensure you have no connection issues when downloading bitcoin blocks. A hosted bitcoin node may cause your stacks node to fall behind tip and remain unsynced.

You can in order to quickly sync your node, otherwise it will take a long time to get up-to-date with the other nodes.

In order to stack, you'll need your signer signature. The fields required are further explained in the guide.

The generated JSON can be then copy-pasted directly in the website mentioned in the next step.

The simplest route is to solo stack. You can do that by using . Click on the 'Stack Independently' button and follow the instructions there.

If you would like to learn more about solo stacking or running a pool operator, take a look at the guide.

If you would like to learn more about monitoring your signer and its corresponding node, you can check the guide.

🛠️
Docker Image
GitHub Release
Docker Image
GitHub Release
Stackers and Signing
Running a Signer
Stacks Core releases page on Github
latest signer release ZIP file
full Bitcoin node
pruned Bitcoin node
Stacks Core releases page on Github
latest node release ZIP file
full Bitcoin node
pruned Bitcoin node
download a chainstate archive
Generate a signer key signature
Leather Earn
Leather Earn
Stack STX
How to Monitor a Signer