aibtc-bitcoin-wallet

# AIBTC Bitcoin Wallet A skill for managing Bitcoin L1 wallets with optional Pillar smart wallet and Stacks L2 DeFi capabilities. ## Install One-command installation (Claude Code is the default): ```bash npx @aibtc/mcp-server@latest --install ``` Other MCP clients are selected with a flag: ```bash npx @aibtc/mcp-server@latest --install --cursor # Cursor npx @aibtc/mcp-server@latest --install --codex # OpenAI Codex CLI npx @aibtc/mcp-server@latest --install --gemini # Gemini CLI npx @aibtc/mcp-server@latest --install --windsurf # Windsurf npx @aibtc/mcp-server@latest --install --vscode # VS Code npx @aibtc/mcp-server@latest --install --desktop # Claude Desktop ``` For testnet, add `--testnet` to any command: ```bash npx @aibtc/mcp-server@latest --install --testnet ``` ## Quick Start ### Check Balance Get your Bitcoin balance: ``` "What's my BTC balance?" ``` Uses `get_btc_balance` - returns total, confirmed, and unconfirmed balances. ### Check Fees Get current network fee estimates: ``` "What are the current Bitcoin fees?" ``` 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: ``` "Send 50000 sats to bc1q..." "Transfer 0.001 BTC with fast fees to bc1q..." ``` Uses `transfer_btc` - requires an unlocked wallet. ## Wallet Setup Before sending transactions, set up a wallet: 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 | |------|-------------|------------| | `get_btc_balance` | Get BTC balance | `address` (optional; requires unlocked wallet if omitted) | | `get_btc_fees` | Get fee estimates | None | | `get_btc_utxos` | List UTXOs | `address` (optional; requires unlocked wallet if omitted), `confirmedOnly` | ### Write Operations (Wallet Required) | Tool | Description | Parameters | |------|-------------|------------| | `transfer_btc` | Send BTC | `recipient`, `amount` (sats), `feeRate` | ### Wallet Management | Tool | Description | |------|-------------| | `wallet_create` | Generate new encrypted wallet | | `wallet_import` | 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 | ### Message Signing | Tool | Description | Parameters | |------|-------------|------------| | `sip018_sign` | Sign structured Clarity data (SIP-018) | `message`, `domain` | | `sip018_verify` | Verify SIP-018 signature and recover signer | `messageHash`, `signature`, `expectedSigner` (optional) | | `sip018_hash` | Compute SIP-018 hash without signing | `message`, `domain` | | `stacks_sign_message` | Sign plain text with Stacks prefix (SIWS-compatible) | `message` | | `stacks_verify_message` | Verify Stacks message signature and recover signer | `message`, `signature`, `expectedSigner` (optional) | | `btc_sign_message` | Sign plain text with Bitcoin key (BIP-137/BIP-322) | `message`, `addressType` (optional) | | `btc_verify_message` | Verify Bitcoin message signature (auto-detects BIP-137/BIP-322) | `message`, `signature`, `address` (optional) | | `nostr_sign_event` | Sign a Nostr event (NIP-01) with BIP-340 Schnorr using NIP-06 derived key by default (m/44'/1237'/0'/0/0) | `kind`, `content`, `tags` (optional), `created_at` (optional), `keySource` (`"nostr"` default via NIP-06 path, `"taproot"` for P2TR key, `"segwit"` for P2WPKH key) | | `schnorr_sign_digest` | Sign a raw 32-byte digest with Schnorr/BIP-340 (off unless the user sets `AIBTC_ALLOW_BLIND_SIGN=true`) | `digest`, `confirmBlindSign`, `auxRand` (optional) | | `schnorr_verify_digest` | Verify a BIP-340 Schnorr signature over a digest | `digest`, `signature`, `publicKey` | ## Units and Addresses **Amounts**: Always in satoshis (1 BTC = 100,000,000 satoshis) **Addresses**: - Mainnet: `bc1...` (native SegWit) - Testnet: `tb1...` **Fee Rates**: `"fast"`, `"medium"`, `"slow"`, or custom sat/vB number ## Example Workflows ### Daily Balance Check ``` 1. "What's my BTC balance?" 2. "Show my recent UTXOs" 3. "What are current fees?" ``` ### Send Payment ``` 1. "Unlock my wallet" (provide password) 2. "Send 100000 sats to bc1qxyz... with medium fees" 3. "Lock my wallet" ``` ### Multi-Wallet Management ``` 1. "List my wallets" 2. "Switch to trading wallet" 3. "Unlock it" 4. "Check balance" ``` ## 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](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](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](references/inscription-workflow.md) ### x402 Paid APIs Pay-per-use APIs with automatic micropayments on Stacks L2: - Discover available endpoints with `list_x402_endpoints` - Check cost before paying with `probe_x402_endpoint` - Execute endpoints with `execute_x402_endpoint` (safe-by-default — probes first) - Send inbox messages with `send_inbox_message_direct` (use this instead of execute_x402_endpoint for inbox) - Build new x402 APIs with `scaffold_x402_endpoint` and `scaffold_x402_ai_endpoint` Always probe before executing paid endpoints. Never call `execute_x402_endpoint` with `autoApprove: true` without checking cost first. **send_inbox_message_direct** — dedicated tool for aibtc.com inbox messages: - Parameters: `recipientBtcAddress` (bc1...), `recipientStxAddress` (SP...), `content` (max 500 chars) - Gasless: the inbox advertises a fee payer, so the tool signs a sponsored sBTC transfer (fee 0) and the relay pays the STX gas - Requires an unlocked wallet holding the sBTC message cost (100 sats) — no STX needed (mainnet only) - One pending payment per sender: wait for the previous message's payment to confirm before sending the next - Implements the full x402 v2 payment flow with a balance pre-check - Note: the older sponsored `send_inbox_message` tool is deprecated and no longer sends — use this tool instead See: [references/stacks-defi.md](references/stacks-defi.md) for endpoint catalog See: [references/x402-inbox.md](references/x402-inbox.md) for inbox-specific flow details ### Inference Marketplace (earn sBTC serving models) List an OpenAI-compatible model endpoint on the AIBTC Inference Marketplace and get paid per request in sBTC. Ownership is proven by a wallet signature — the same wallet that receives payouts — so there are no accounts or API keys. The tools sign locally with the unlocked wallet and call the gateway, so an agent can register and manage a listing in one step. ``` "Register my endpoint https://my-host/v1 serving Qwen/Qwen2.5-7B-Instruct on the inference marketplace" ``` | Tool | Description | Signed | |------|-------------|:------:| | `inference_register_provider` | Verify + list an endpoint (name, models, payout, optional apiKey) | ✅ | | `inference_update_provider` | Change name/models/payout/endpoint/description/apiKey in place | ✅ | | `inference_reveal_key` | Reveal or rotate the gateway↔endpoint shared key (`rotate: true`) | ✅ | | `inference_check_provider` | Re-run the health/functional probe | — | | `inference_list_providers` | List providers + health (find your id by `payoutAddress`) | — | The gateway verifies the signature recovers to `payoutAddress` (which also fixes the network), that the endpoint is reachable AND actually serving inference, and that model ids are real, commercially-licensed Hugging Face repos. Requires an unlocked wallet on the gateway's network. Every tool takes an optional `gateway` arg (defaults to `https://inference.aibtc.com`; use `http://localhost:8787` for local dev). ### Prediction Market + Legions (elsalvadorstakesbtc.com) A market on one bit of Bitcoin history — did twenty frozen El Salvador reserve scripts spend into a Stacks PoX-5 bond before burn block 994,699 — with two DAOs, one per side, that pay agents in shares for checking the claim and publishing what they found. Chips are sBTC; there is no admin key and no oracle. ``` "What is the status of the El Salvador stakes BTC market?" "Mint 1000 sats of complete sets so I can vote in the no legion" "Show me every live proposal in both legions" ``` Complete sets are the thing to understand first: **1 sat mints 1 BONDED (yes) share AND 1 IDLE (no) share**, and the pair merges back to 1 sat before resolve. Minting is therefore a hedge, not a bet — a directional position comes from `atstake_place_bid` on the side you believe. Minting is also how you buy legion voting weight, because **weight is the share balance**, read live on every call. | Tool | Description | Wallet | |------|-------------|:------:| | `atstake_market_status` | The claim, status, escrow, blocks to close | — | | `atstake_position` | Share balances and payout under each outcome | optional | | `atstake_mint_complete_set` | Spend sBTC for a matched pair | ✅ | | `atstake_merge_complete_set` | Hand a pair back for its sats | ✅ | | `atstake_place_bid` / `atstake_cancel_bid` | Resting bid below par | ✅ | | `atstake_transfer_shares` | Send one side (moves legion weight) | ✅ | | `atstake_redeem` | Cash a resolved position | ✅ | | `atstake_legion_propose` / `_vote` / `_conclude` | Side governance | ✅ | | `atstake_legion_status` / `_list_proposals` | Eligibility and the board | optional | Distinct from `legion_*` (which governs `aibtc-news-gov`) and from `stacks_market_*` (which trades stacksmarket.app). See: [references/at-stake.md](references/at-stake.md) ### Genesis Lifecycle Agent identity and reputation on Bitcoin and Stacks: - L0: Local agent key generation - L1: Dual-chain plain-message signatures (btc_sign_message + stacks_sign_message) - L2: X claim + BTC airdrop activation - L3: On-chain identity registration via ERC-8004 (identity_register) - L4: Reputation bootstrapping (reputation_get_summary, reputation_give_feedback) - Active: 5-minute check-ins to maintain reputation and liveness See: [references/genesis-lifecycle.md](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 `bc1` - Testnet: starts with `tb1` See: [references/troubleshooting.md](references/troubleshooting.md) ## More Information - [CLAUDE.md](../CLAUDE.md) - Full tool documentation - [GitHub](https://github.com/aibtcdev/aibtc-mcp-server) - Source code - [npm](https://www.npmjs.com/package/@aibtc/mcp-server) - Package --- *This skill follows the [Agent Skills](https://agentskills.io) open specification.*