Skip to main content
Glama
aibtc-mcp-server
by aibtcdev

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:

  1. Fetches current nonce state from Hiro API (gaps, mempool)

  2. In dryRun mode: shows what would happen without broadcasting

  3. 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

NameRequiredDescriptionDefault
dryRunNoIf true (default), preview proposed actions without broadcasting. Set to false to execute.
addressNoSTX address to heal. Defaults to the active wallet address. Execute mode only accepts the unlocked wallet's address.
bumpHeadNoWhether to RBF-bump the first real pending tx (chain head) after filling gaps. Default true.
feeMultiplierNoFee 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changedv1.77.4
    • changedInput schema / properties / address / description
      Previous value: -"STX address to heal. Defaults to the active wallet address."New value: +"STX address to heal. Defaults to the active wallet address. Execute mode only accepts the unlocked wallet's address."
    • changedInput schema / properties / feeMultiplier / description
      Previous value: -"Fee multiplier for RBF bump (e.g. 1.5 = 50% higher fee). Minimum 1.1. Default 1.5."New value: +"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."
    • addedInput schema / properties / feeMultiplier / maximum
      Added value: +5
  2. First observedv1.77.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does so thoroughly: it discloses that execute mode broadcasts 1 uSTX self-transfers to fill gaps, RBF-bumps the chain head, skips sponsored and contract-call txs, requires an unlocked wallet, books every action against the spend limit and aborts at the first refusal, and refuses bumps above 1,000,000 uSTX or a zero/missing-fee head.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Structure is strong: a one-line summary, then a numbered flow and a dedicated RBF subsection, with the key constraint statements grouped at the end. It is longer than most definitions and the trailing 'Tip: call earning_opportunities' cross-promotion does not help an agent call this tool, which keeps it below a 5.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a broadcasting mutation with no annotations and no output schema, the description covers everything an agent needs: prerequisites (unlocked wallet), mode semantics, per-tx-type RBF handling, spend-limit and fee refusal rules, and a full enumeration of the return payload fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: it clarifies that dryRun previews without broadcasting, that execute mode only accepts the unlocked wallet's own address (address is effectively read-only in execute), and that bumpHead targets the lowest non-gap pending tx — more precise than the schema's 'first real pending tx'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening line gives a specific verb and resource ('Diagnose and heal the full nonce state for the active wallet') plus explicit scope ('in one shot'), and the numbered breakdown makes clear this is a combined diagnose+repair operation rather than a pure read like nonce_health or a narrow single-gap fix.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the target case ('Handles 90% of stuck-tx cases automatically'), the sequencing requirement ('Always run nonce_health first'), and cleanly separates preview (dryRun=true) from execute (dryRun=false). It does not say when to prefer nonce_fill_gap or recover_sponsor_nonce instead, so the alternative-routing guidance is incomplete even though it is explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools