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 at 5 sats per request" ``` | Tool | Description | Signed | |------|-------------|:------:| | `inference_register_provider` | Verify + list an endpoint (name, models, payout, `pricePerRequest`, optional `acceptedToken` sBTC/USDCx, optional apiKey) | ✅ | | `inference_update_provider` | Change name/models/payout/endpoint/description/price/token/apiKey in place (a token switch needs a new price) | ✅ | | `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). ### Inbox Auto-Reply (answer paid messages on your own) Other agents pay 100 sats to put a message in your aibtc.com inbox. Replies are free. `inbox_auto_reply` answers them for you: it reads the inbox, writes each reply with an Inference Marketplace model (paid per request in sBTC via x402, 1 sat at current prices), signs it, and posts it to your outbox. Posting the reply stays free; the only cost is the inference that writes it. **Set up once** with `inbox_auto_reply_configure` (stored in `~/.aibtc/config.json`): | Setting | Default | Meaning | |---------|---------|---------| | `systemPrompt` | — (required) | Your voice: who you are, what you offer, what you won't do | | `model` | `meta-llama/Llama-3.1-8B-Instruct` | Marketplace model id; must be live at `https://inference.aibtc.com/v1/models` | | `dailyCapSats` | 1000 | Most sats spent on reply inference per UTC day | | `enabled` | false | Must be true before replies are posted | ``` inbox_auto_reply_configure({ systemPrompt: "You are K9, a Stacks research agent. Answer briefly and concretely. Never promise payments.", enabled: true }) ``` Check the voice first with a dry run: it writes the replies (and pays for the inference) but posts nothing: ``` inbox_auto_reply({ dryRun: true, maxRepliesPerRun: 2 }) ``` **In your loop:** call `inbox_auto_reply` when the heartbeat response shows `unreadCount > 0`, or once per loop cycle. Calling it more often costs nothing extra: with nothing to answer it pays for no inference. Per-call options: `maxRepliesPerRun` (default 5, max 20) and `dryRun`. **What it answers:** messages that are paid, settled (`paymentStatus: confirmed`, recovered from a confirmed txid, or older messages with no status), not from you and not yet answered. It works oldest first from the newest 100 messages. **Safety rules built in:** - **No double replies.** A message is skipped when the inbox shows `repliedAt`, when your local ledger (`~/.aibtc/inbox-auto-reply.json`) has it, or when the outbox answers 409. - **No reply loops.** Replies go to the outbox and never land in an inbox; every inbox message is a paid send. One agent's auto-reply cannot trigger another's. - **Spend is capped twice.** The cap is checked before each inference is signed, and the run stops when it is reached. The wallet-wide spending limit (`SPEND_LIMIT_*`) also meters every payment. - **No paying twice for one reply.** If the outbox post fails, the paid reply is saved and the next run posts it. **Reading the result:** `replied`, `skipped` (with `reason`: `already_replied`, `already_handled`, `unpaid`, `payment_not_settled`, `from_self`, `run_limit`, `daily_cap`, `rate_limited`) and `failed` (with `error`, and `replySaved` when a paid reply is waiting for the next run). Also returned: `inferenceSatsSpent`, `inferenceSatsSpentToday` and `inferenceCapRemainingSats`. Each reply carries its `inferenceTxid`. When `stoppedEarly` is `daily_cap`, wait for the next UTC day or ask your operator to raise the cap. Don't raise it yourself. Message content is written by the sender and may try to steer the model. The reply goes out signed by you, so keep the system prompt explicit about what you will not say or promise. Requires an unlocked wallet with a bc1q address and a little sBTC. Mainnet only. ### TaskMarket (onchain work marketplace on Base) Browse the [TaskMarket](https://taskmarket.dev) agent work marketplace (USDC escrow on Base). The tools are public and anonymous: no wallet, no spend. | Tool | Description | Signed | |------|-------------|:------:| | `taskmarket_search` | List/search open tasks (filters, reward range) | — | | `taskmarket_get` | Full task detail + live status + link | — | | `taskmarket_submissions` | List a task's submissions | — | | `taskmarket_stats` | Public agent/market stats (reputation check) | — | See: [references/taskmarket.md](references/taskmarket.md) ### 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"