STX stacking operations on Stacks — query PoX cycle info, check stacking status, lock STX to earn BTC rewards (stack-stx), and extend an existing stacking lock period. Write operations require an unlocked wallet.
Provides Proof of Transfer (PoX) stacking operations on the Stacks blockchain. Stacking locks STX tokens for a specified number of reward cycles to earn Bitcoin rewards.
bun run stacking/stacking.ts <subcommand> [options]
Get current Proof of Transfer (PoX) cycle information, including current and next cycle details, minimum stacking amount, and cycle lengths.
bun run stacking/stacking.ts get-pox-info
Output:
{
"network": "testnet",
"currentCycle": {
"id": 88,
"min_threshold_ustx": 50000000000,
"stacked_ustx": 1200000000000,
"is_pox_active": true
},
"nextCycle": {
"id": 89,
"min_threshold_ustx": 50000000000,
"min_increment_ustx": 5000000000,
"stacked_ustx": 0,
"prepare_phase_start_block_height": 3450,
"blocks_until_prepare_phase": 25,
"reward_phase_start_block_height": 3500,
"blocks_until_reward_phase": 75,
"ustx_until_pox_rejection": 0
},
"minAmountUstx": 50000000000,
"rewardCycleLength": 2100,
"prepareCycleLength": 100,
"currentBurnchainBlockHeight": 3425,
"totalLiquidSupplyUstx": 1400000000000000
}
Check if an address is currently stacking STX.
bun run stacking/stacking.ts get-stacking-status [--address <addr>]
Options:
--address (optional) — Stacks address to check (uses active wallet if omitted)Output:
{
"address": "SP2...",
"network": "testnet",
"stacked": true,
"amountMicroStx": "100000000000",
"amountStx": "100000",
"firstRewardCycle": 85,
"lockPeriod": 3,
"unlockHeight": 6300
}
Lock STX tokens to earn Bitcoin rewards via Proof of Transfer. Requires an unlocked wallet with sufficient STX.
The Bitcoin reward address must be provided as a version byte and hash. For P2PKH (legacy Bitcoin address), version is 0. For P2SH, version is 1. For P2WPKH (native SegWit), version is 4.
bun run stacking/stacking.ts stack-stx \
--amount <microStx> \
--pox-address-version <version> \
--pox-address-hashbytes <hex> \
--start-burn-height <btcBlockHeight> \
--lock-period <cycles>
Options:
--amount (required) — Amount of STX to stack in micro-STX (1 STX = 1,000,000 micro-STX). Must meet the minimum stacking threshold.--pox-address-version (required) — Bitcoin address version byte: 0 (P2PKH), 1 (P2SH), 4 (P2WPKH), 5 (P2WSH), 6 (P2TR)--pox-address-hashbytes (required) — Bitcoin address hash bytes as a hex string (20 bytes for P2PKH/P2SH/P2WPKH, 32 bytes for P2WSH/P2TR)--start-burn-height (required) — Bitcoin block height at which stacking begins (must be in a prepare phase or the first block of a reward phase)--lock-period (required) — Number of reward cycles to lock STX (1–12)Output:
{
"success": true,
"txid": "abc123...",
"stacker": "SP2...",
"amount": "100000000000",
"lockPeriod": 3,
"startBurnHeight": 850000,
"network": "testnet",
"explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=testnet"
}
Extend an existing stacking lock period by additional reward cycles. Must already be stacking. Requires an unlocked wallet.
bun run stacking/stacking.ts extend-stacking \
--extend-count <cycles> \
--pox-address-version <version> \
--pox-address-hashbytes <hex>
Options:
--extend-count (required) — Number of additional reward cycles to lock (1–12)--pox-address-version (required) — Bitcoin address version byte (same as used when initially stacking)--pox-address-hashbytes (required) — Bitcoin address hash bytes as a hex string (same as used when initially stacking)Output:
{
"success": true,
"txid": "abc123...",
"stacker": "SP2...",
"extendCount": 2,
"network": "testnet",
"explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=testnet"
}
get-pox-info to check minAmountUstx before calling stack-stx.wallet skill's get-taproot-address for Taproot addresses.lock-period of 1–12 cycles is valid. Each cycle is typically ~2 weeks on mainnet.start-burn-height must fall within the prepare phase of the current PoX cycle. Check nextCycle.prepare_phase_start_block_height from get-pox-info.bun run wallet/wallet.ts unlock first).