AIBTC Bitcoin Wallet

A skill for managing Bitcoin L1 wallets with optional Pillar smart wallet and Stacks L2 DeFi capabilities.

Install

One-command installation:

CODEBLOCK0

For testnet:

CODEBLOCK1

Quick Start

Check Balance

Get your Bitcoin balance:

CODEBLOCK2

Uses get_btc_balance - returns total, confirmed, and unconfirmed balances.

Check Fees

Get current network fee estimates:

CODEBLOCK3

Uses get_btc_fees - returns fast (~10 min), medium (~30 min), and slow (~1 hr) rates in sat/vB.

Send BTC

Transfer Bitcoin to an address:

CODEBLOCK4

Uses transfer_btc - requires an unlocked wallet.

Wallet Setup

Before sending transactions, set up a wallet:

1. 1. Create new wallet: wallet_create - generates encrypted BIP39 mnemonic
2. Import existing: wallet_import - import from mnemonic phrase
3. Unlock for use: wallet_unlock - required before transactions

Wallets are stored encrypted at ~/.aibtc/.

Tool Reference

Read Operations

Tool	Description	Parameters
INLINECODE7	Get BTC balance	INLINECODE8 (optional; requires unlocked wallet if omitted)
INLINECODE9

Get fee estimates | None | | get_btc_utxos | List UTXOs | address (optional; requires unlocked wallet if omitted), confirmedOnly |

Write Operations (Wallet Required)

Tool	Description	Parameters
INLINECODE13	Send BTC	INLINECODE14, amount (sats), INLINECODE16

Wallet Management

Tool	Description
INLINECODE17	Generate new encrypted wallet
INLINECODE18

Import wallet from mnemonic | | wallet_unlock | Unlock wallet for transactions | | wallet_lock | Lock wallet (clear from memory) | | wallet_list | List available wallets | | wallet_switch | Switch active wallet | | wallet_status | Get wallet/session status |

Units and Addresses

Amounts: Always in satoshis (1 BTC = 100,000,000 satoshis)

Addresses:

• - Mainnet: bc1... (native SegWit)
• Testnet: INLINECODE25

Fee Rates: "fast", "medium", "slow", or custom sat/vB number

Example Workflows

Daily Balance Check

CODEBLOCK5

Send Payment

CODEBLOCK6

Multi-Wallet Management

CODEBLOCK7

Progressive Layers

This skill focuses on Bitcoin L1. Additional capabilities are organized by layer:

Stacks L2 (Layer 2)

Bitcoin L2 with smart contracts and DeFi:

• - STX token transfers
• ALEX DEX token swaps
• Zest Protocol lending/borrowing
• x402 paid API endpoints (AI, storage, utilities) — safe-by-default with probe-before-pay workflow

See: references/stacks-defi.md

Pillar Smart Wallet (Layer 3)

sBTC smart wallet with yield automation:

• - Passkey or agent-signed transactions
• Send to BNS names (alice.btc)
• Auto-boost yield via Zest Protocol

See: references/pillar-wallet.md

Bitcoin Inscriptions

Inscribe and retrieve digital artifacts on Bitcoin:

• - Commit-reveal inscription workflow
• Get inscription content and metadata
• Protect ordinal UTXOs from accidental spending

See: references/inscription-workflow.md

x402 Paid APIs

Pay-per-use APIs with automatic micropayments on Stacks L2:

• - Discover available endpoints with INLINECODE29
• Check cost before paying with INLINECODE30
• Execute endpoints with execute_x402_endpoint (safe-by-default — probes first)
• Send inbox messages with send_inbox_message (use this instead of executex402endpoint for inbox)
• Build new x402 APIs with scaffold_x402_endpoint and INLINECODE34

Always probe before executing paid endpoints. Never call execute_x402_endpoint with autoApprove: true without checking cost first.

sendinboxmessage — dedicated tool for aibtc.com inbox messages:

• - Parameters: recipientBtcAddress (bc1...), recipientStxAddress (SP...), content (max 500 chars), paymentTxid (optional)
• Uses sponsored transactions: sender pays only the sBTC message cost, relay covers STX gas
• Avoids sBTC settlement timeout issues that affect the generic executex402endpoint tool
• Implements the full 5-step x402 v2 payment flow with balance pre-check
• paymentTxid (optional): provide a confirmed on-chain sBTC transfer txid to skip the x402 flow and deliver the message using that txid as payment proof — use for manual recovery when a settlement timeout left the sBTC payment confirmed on-chain but the message undelivered
• Automatic recovery: if retries are exhausted, the tool checks whether any submitted payment txid confirmed on-chain and, if so, resubmits the message automatically — no agent action required

See: references/stacks-defi.md for endpoint catalog
See: references/x402-inbox.md for inbox-specific flow details

Genesis Lifecycle

Agent identity and reputation on Bitcoin and Stacks:

• - L0: Local agent key generation
• L1: Dual-chain plain-message signatures (btcsignmessage + stackssignmessage)
• L2: X claim + BTC airdrop activation
• L3: On-chain identity registration via ERC-8004 (registeridentity)
• L4: Reputation bootstrapping (getreputation, give_feedback)
• Active: 5-minute check-ins to maintain reputation and liveness

See: references/genesis-lifecycle.md

Troubleshooting

"Wallet not unlocked"

Run wallet_unlock with your password before sending transactions.

"Insufficient balance"

Check get_btc_balance - you need enough BTC for amount + fees.

"Invalid address"

Ensure address matches network:

• - Mainnet: starts with INLINECODE43
• Testnet: starts with INLINECODE44

See: references/troubleshooting.md

More Information

• - CLAUDE.md - Full tool documentation
• GitHub - Source code
• npm - Package

---

This skill follows the Agent Skills open specification.