nonce_heal
Diagnose and repair stuck Stacks wallet transactions: detect nonce gaps, preview fixes, fill missing nonces, and optionally RBF-bump the pending chain head to resume processing.
Instructions
Diagnose and heal the full nonce state for the active wallet in one shot.
Handles 90% of stuck-tx cases automatically:
Fetches current nonce state from Hiro API (gaps, mempool)
In dryRun mode: shows what would happen without broadcasting
In execute mode (dryRun=false):
Fills every gap with a 1 uSTX self-transfer to the PoX burn address
Optionally RBF-bumps the chain head (lowest non-gap pending tx) to kick off processing
RBF bump behavior:
Token-transfer txs: rebuilt at same nonce with fee * feeMultiplier and rebroadcast
Sponsored txs: skipped with explanation (sender cannot RBF without sponsor key)
Contract-call txs: skipped with manual RBF instructions
Always run nonce_health first to understand the current state. Requires wallet to be unlocked for execute mode (dryRun=false), and execute mode only heals that wallet's own address (any address can be previewed with dryRun=true). Every gap fill and bump is booked on the spend limit; the run stops at the first spend-limit refusal. A bump fee above 1,000,000 uSTX, or a head with a missing or zero fee, is refused.
Returns:
address, dryRun flag, confirmedNonce
gapsFound: list of missing nonces
actions: per-action detail (fill_gap or bump_head) with txids, fees, status
warnings: informational notes
summary: human-readable description of what happened
Tip: call earning_opportunities to see how to put your assets to work.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "nonce_heal"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dryRun | No | If true (default), preview proposed actions without broadcasting. Set to false to execute. | |
| address | No | STX address to heal. Defaults to the active wallet address. Execute mode only accepts the unlocked wallet's address. | |
| bumpHead | No | Whether to RBF-bump the first real pending tx (chain head) after filling gaps. Default true. | |
| feeMultiplier | No | Fee multiplier for RBF bump (e.g. 1.5 = 50% higher fee). Minimum 1.1, maximum 5. Default 1.5. The bumped fee is booked on the wallet's spend limit. |