Generate a Signer Signature

Stacking transactions require a signer key signature to prove that the controller of the signer key authorizes the stacking operation. This page covers what a signer signature is, what data it contains, and all the ways to generate one.

Both solo stacking and delegated stacking (Stack with a Pool / Operate a Pool) reference this page. Generate your signature here before making stacking transactions.

---

Overview

Signer signatures are created using your signer key. They demonstrate that the controller of that signer key is allowing a stacker (or pool operator) to use their signing key in a stacking transaction. Because signer keys must be unique across the network, this also prevents other stackers from using someone else's key.

The current pox-4 contract address can be found at https://api.mainnet.hiro.so/v2/pox. You can view the contract in the Stacks Explorer.

Fields Passed in Stacking Transactions

When making stacking transactions, you need to provide these signature-related fields:

1

signer-key

The public key that corresponds to the stacks_private_key your signer is using.

2

signer-signature

A signature that demonstrates you actually control your signer-key.

3

max-amount

The maximum amount of uSTX (1 STX = 1,000,000 uSTX) that can be locked in the transaction that uses this signature. For example, if calling stack-increase, this dictates the maximum amount of uSTX that can be used to add more locked STX.

4

auth-id

A random integer that prevents the same signature from being reused, similar to how nonces are used with transactions. Must be less than 14 characters.

Signature Message Contents

The signer signature's message hash is created using the following data:

• method: the stacking function that is allowed to use this signature. Valid options:

  • stack-stx: for solo stacking

  • stack-extend: for extending a solo stacking lock

  • stack-increase: for increasing a solo stacking position

  • agg-commit: for stack-aggregation-commit-indexed (pool operators)

  • agg-increase: for stack-aggregation-increase (pool operators)

• max-amount: the maximum uSTX allowed (described above)

• auth-id: the random integer (described above)

• period: a value between 1 and 12 indicating how many cycles the stacker is allowed to lock for. For agg-commit, this must equal 1.

• reward-cycle: the reward cycle in which the stacking transaction can be confirmed. See the important note below about how this differs between solo and delegated stacking.

• pox-address: the Bitcoin address allowed for receiving rewards

• config: the signer configuration file path where the stacks_private_key is located (used by the CLI for signing)

reward-cycle differences:

• For solo stacking operations (stack-stx, stack-extend, stack-increase): set this to the current reward cycle.

• For stack-aggregation-commit-indexed: set this to the target reward cycle (typically current cycle + 1, or a future cycle you are committing to). This is because pool operators can commit for future cycles, not just the next one.

Every field in the signature must exactly match the corresponding fields in your stacking transaction. A mismatch will cause the transaction to fail.

---

Generating Signatures

You have several options for generating signer signatures. Choose the one that best fits your setup.

Using the stacks-signer CLI

If you have your signer configured and running, you can use the stacks-signer CLI to generate signatures. You can SSH into your running signer or use the CLI locally with a matching configuration file.

Having a matching configuration file is important to ensure the signer public key in your stacking transactions is the same as in your hosted signer.

stacks-signer generate-stacking-signature \
  --method stack-stx \
  --max-amount 1000000000000 \
  --auth-id 71948271489 \
  --period 1 \
  --reward-cycle 100 \
  --pox-address bc1... \
  --config ./config.toml \
  --json

• --json optionally outputs the result in JSON format

You can generate a random 32-bit integer for auth-id with:

python3 -c 'import secrets; print(secrets.randbits(32))'

The CLI outputs a JSON object:

{
  "authId": "71948271489",
  "maxAmount": "1000000000000",
  "method": "stack-stx",
  "period": 1,
  "poxAddress": "bc1...",
  "rewardCycle": 100,
  "signerKey": "03a3...",
  "signerSignature": "bbbbbbbbbbb"
}

Use this JSON when making stacking transactions. This output can be pasted directly into Leather Earn.

The address you use for stacking transactions may differ from your signer address. See Key and Address Rotation for more details on the relationship between signer keys and pool operator keys.

Using stacks.js

The @stacks/stacking NPM package provides a signPoxSignature function to generate signer signatures programmatically.

More information and code samples can be found on Hiro's Nakamoto docs.

Using Degen Lab's stacking.tools

Degen Lab provides a signature generation tool that generates signatures using their signer. This is the quickest and simplest option. Visit the tool and enter the relevant parameters.

Using Leather Earn

At the time of writing, this has only been tested using the Leather wallet.

Visit earn.leather.io to generate a signer key signature. Make sure you're connected to the correct network.

To generate a signer key signature, log into Leather with the same secret key used to generate your signer key (not your pool operator address). Then click the "Signer key signature" link at the bottom of the page.

The fields are:

• Reward cycle:

  • For solo stacking transactions: must equal the current reward cycle. The field defaults to the current cycle.

  • For stack-aggregation-commit-indexed: must equal the cycle used in that function's "reward cycle" argument. Typically current_cycle + 1.

• Bitcoin address: the PoX reward address

• Topic: the stacking function that will use this signature

• Max amount: max amount of STX that can be used. Defaults to "max possible amount".

• Auth ID: defaults to a random integer

• Duration: must match the number of cycles used in the stacking transaction. For stack-aggregation-commit-indexed, use "1".

Click "generate signature" to popup a Leather signing window. After signing, Leather Earn will display your signer key and signature. You can click the "copy" icon next to "signer details to share with stackers" to copy a JSON string that can be pasted directly into the stacking transaction form.

Using a Hardware or Software Wallet

If your signer is configured with a stacks_private_key, you can use that key in a wallet to generate stacking signatures.

If you used @stacks/cli to generate the key, the CLI also outputs a mnemonic (seed phrase) that can be imported into a wallet. Because the Stacks CLI uses the standard derivation path, any Stacks wallet will default to the same private key when imported.

Setting up a wallet for signature generation

1

Generate the keypair and configure signer

1. Use @stacks/cli to generate the keychain and private key.

   • When using a hardware wallet, it's typically better to generate the mnemonic on the device itself. However, the signer software needs the raw private key, which hardware wallets don't export by design.

2. Take the privateKey from the CLI output and add it to your signer's configuration.

3. Take the mnemonic (24 words) and either:

   • Set up a new hardware wallet with this mnemonic, or

   • Store it securely (e.g., in a password manager). Import it into Leather or XVerse when you need to generate signatures.

2

Generate signatures when needed

1. Set up your wallet with your signer key's private key:

   • Set up Leather with a Ledger hardware wallet, or

   • Import your mnemonic into Leather, XVerse, or another Stacks wallet

2. Open an app with stacking signature functionality (e.g., Leather Earn)

3. Connect your wallet (sign in)

4. Enter your PoX address and submit. The app will prompt you to sign

5. Confirm the signature (if using a Ledger, confirm on the device)

6. The app displays your signer key and signature

7. Use the signer key and signature in your stacking transaction

---

Signature Requirements by Function

Function	Method	Period	Reward Cycle
stack-stx	stack-stx	Lock period (1–12)	Current cycle
stack-extend	stack-extend	Extend count (1–12)	Current cycle
stack-increase	stack-increase	Current lock period	Current cycle
stack-aggregation-commit-indexed	agg-commit	1	Target cycle (e.g., current + 1)
stack-aggregation-increase	agg-increase	1	Target cycle