{
  "markdown": "# @aibtc/mcp-server\n\n[![npm version](https://img.shields.io/npm/v/@aibtc/mcp-server.svg)](https://www.npmjs.com/package/@aibtc/mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nBitcoin-native MCP server for AI agents: BTC/STX wallets, DeFi yield, sBTC peg, NFTs, and x402 payments.\n\n## Features\n\n- **Bitcoin L1** - Check balances, send BTC, manage UTXOs via mempool.space\n- **Agent's Own Wallet** - Agents get their own wallet to perform blockchain transactions\n- **Secure Storage** - Wallets encrypted with AES-256-GCM and stored locally\n- **150+ Tools** - Bitcoin L1 + comprehensive Stacks L2 operations\n- **sBTC Support** - Native Bitcoin on Stacks operations\n- **Token Operations** - SIP-010 fungible token transfers and queries\n- **NFT Support** - SIP-009 NFT holdings, transfers, and metadata\n- **DeFi Trading** - ALEX DEX swaps and Zest Protocol lending/borrowing\n- **Stacking/PoX** - Stacking status and delegation\n- **BNS Domains** - .btc domain lookups and management (V1 + V2)\n- **x402 Payments** - Automatic payment handling for paid APIs\n\n## Quick Start\n\n### Claude Code (Terminal)\n\n```bash\nnpx @aibtc/mcp-server@latest --install\n```\n\nThat's it! This automatically configures Claude Code. Restart your terminal and start chatting.\n\n### Claude Desktop (App)\n\n```bash\nnpx @aibtc/mcp-server@latest --install --desktop\n```\n\nThis detects your OS and writes to the correct Claude Desktop config file:\n\n| OS | Config Path |\n|----|-------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%/Claude/claude_desktop_config.json` |\n\nRestart Claude Desktop after installing.\n\n### Other MCP Clients\n\nThis is a standard stdio MCP server, so it works with **any** MCP-compatible client. Claude Code is the default `--install` target; select another client with a flag:\n\n```bash\nnpx @aibtc/mcp-server@latest --install --cursor     # Cursor\nnpx @aibtc/mcp-server@latest --install --windsurf   # Windsurf\nnpx @aibtc/mcp-server@latest --install --gemini     # Gemini CLI\nnpx @aibtc/mcp-server@latest --install --codex      # OpenAI Codex CLI\nnpx @aibtc/mcp-server@latest --install --vscode     # VS Code (writes ./.vscode/mcp.json)\n```\n\n| Flag | Client | Config written |\n|------|--------|----------------|\n| _(none)_ | Claude Code | `~/.claude.json` |\n| `--desktop` | Claude Desktop | `claude_desktop_config.json` (see path table above) |\n| `--cursor` | Cursor | `~/.cursor/mcp.json` |\n| `--windsurf` | Windsurf | `~/.codeium/windsurf/mcp_config.json` |\n| `--gemini` | Gemini CLI | `~/.gemini/settings.json` |\n| `--codex` | OpenAI Codex CLI | `~/.codex/config.toml` |\n| `--vscode` | VS Code (Copilot agent) | `./.vscode/mcp.json` (project-scoped) |\n\nEach installer merges into the existing config — it won't clobber other servers or settings. Restart the client afterward.\n\n### OpenRouter (any model)\n\nThe clients above are MCP hosts — they connect to this server for you. To drive the tools with an [OpenRouter](https://openrouter.ai) model instead, the server ships a built-in bridge: it spawns itself in server mode, exposes the tools to the model as function tools, and runs the tool-call loop. This is the client-side pattern from [OpenRouter's MCP cookbook](https://openrouter.ai/docs/cookbook/coding-agents/mcp-servers), packaged into the binary.\n\n```bash\nexport OPENROUTER_API_KEY=sk-or-...\nnpx @aibtc/mcp-server@latest bridge \"what's the STX balance of SP3...?\"\n```\n\nSafety flags (this server moves real funds, so the bridge defaults to nothing extra and lets you constrain it):\n\n| Flag | Effect |\n|------|--------|\n| `--read-only` | Expose only read-only tools (no transfer/swap/deploy/etc.) |\n| `--allow a,b` | Force-allow specific tool names (added to the set) |\n| `--block a,b` | Force-remove specific tool names (wins over `--allow`) |\n| `--max-spend-ustx <n>` / `--max-spend-sats <n>` | Cap spend via the server's spend-limit rail (enforced before signing) |\n| `--list-tools` | Print the exposed tool set and exit (no API key needed) |\n| `--model <id>` | OpenRouter model (default `anthropic/claude-3.5-haiku`) |\n| `--network <net>` | `mainnet` or `testnet` (default `mainnet`) |\n| `--max-turns <n>` | Tool-call loop cap (default 10) |\n\n```bash\n# Preview what a read-only session would expose, no key needed:\nnpx @aibtc/mcp-server@latest bridge --read-only --list-tools\n\n# Read-only chat, plus one explicitly allowed write tool:\nnpx @aibtc/mcp-server@latest bridge --read-only --allow transfer_stx \"send 1 STX to SP3...\"\n```\n\nBefore any agent loop runs (and on `--list-tools`), the bridge prints a compact **safety receipt** to stderr — network, read-only mode, exposed/write/blocked tool counts, the session spend cap, and the number of known x402 endpoints — so the configured execution boundaries are visible up front. It reports boundaries only; it never claims any value moved.\n\nThe allowlist is re-enforced at execution time, so a model can never call a tool outside the exposed set. Any MCP-capable agent framework (`@openrouter/agent`, OpenAI Agents SDK, Claude Agent SDK) can also point at this server directly — the bridge is for driving it through OpenRouter's raw API without adopting a framework.\n\n### Testnet Mode\n\nAdd `--testnet` to any install command:\n\n```bash\nnpx @aibtc/mcp-server@latest --install --testnet            # Claude Code, testnet\nnpx @aibtc/mcp-server@latest --install --cursor --testnet   # Cursor, testnet\n```\n\n> **Why npx?** Using `npx @aibtc/mcp-server@latest` ensures you always get the newest version automatically. Global installs (`npm install -g`) won't auto-update.\n\n### Manual Configuration\n\nIf you prefer to configure manually, add the following to your client's config file. The `-y` flag stops npx from prompting for confirmation.\n\n**Claude Code / Claude Desktop / Cursor / Windsurf / Gemini CLI** — `mcpServers` JSON:\n\n```json\n{\n  \"mcpServers\": {\n    \"aibtc\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibtc/mcp-server@latest\"],\n      \"env\": {\n        \"NETWORK\": \"mainnet\"\n      }\n    }\n  }\n}\n```\n\n**VS Code** (`.vscode/mcp.json`) — uses a `servers` key and a typed entry:\n\n```json\n{\n  \"servers\": {\n    \"aibtc\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibtc/mcp-server@latest\"],\n      \"env\": { \"NETWORK\": \"mainnet\" }\n    }\n  }\n}\n```\n\n**OpenAI Codex CLI** (`~/.codex/config.toml`) — TOML, not JSON:\n\n```toml\n[mcp_servers.aibtc]\ncommand = \"npx\"\nargs = [\"-y\", \"@aibtc/mcp-server@latest\"]\n\n[mcp_servers.aibtc.env]\nNETWORK = \"mainnet\"\n```\n\n**Zed** (`settings.json`) — uses a `context_servers` key:\n\n```json\n{\n  \"context_servers\": {\n    \"aibtc\": {\n      \"source\": \"custom\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@aibtc/mcp-server@latest\"],\n      \"env\": { \"NETWORK\": \"mainnet\" }\n    }\n  }\n}\n```\n\n**Cline / Roo Code** (VS Code extension) — add the same `mcpServers` JSON block above via the extension's MCP settings panel (the exact `cline_mcp_settings.json` path varies by OS and VS Code build).\n\n> Any other MCP client works too — point it at `npx -y @aibtc/mcp-server@latest` over stdio with `NETWORK` in the env.\n\n## Giving Claude a Wallet\n\nWhen you first use @aibtc/mcp-server, Claude doesn't have a wallet. Here's the smooth onboarding flow:\n\n### Example Conversation\n\n```\nYou: What's your wallet address?\n\nClaude: I don't have a wallet yet. Would you like to assign me one?\n        I can either create a fresh wallet or you can import an existing one.\n\nYou: Create a new wallet called \"agent-wallet\"\n\nClaude: What password should I use to protect the wallet?\n\nYou: use \"secure123password\"\n\nClaude: I now have a wallet! My address is ST1ABC...XYZ\n\n        IMPORTANT: Please save this recovery phrase securely:\n        \"word1 word2 word3 ... word24\"\n\n        This phrase will NOT be shown again. It's the only way to recover\n        the wallet if the password is forgotten.\n\nYou: Send 10 STX to ST2DEF...\n\nClaude: Done! I've sent 10 STX to ST2DEF...\n        Transaction: 0x123...\n```\n\n### Wallet States\n\n| State | What Claude Says | What To Do |\n|-------|-----------------|------------|\n| No wallet | \"I don't have a wallet yet\" | Use `wallet_create` or `wallet_import` |\n| Locked | \"My wallet is locked\" | Use `wallet_unlock` with password |\n| Ready | \"My address is ST...\" | Claude can perform transactions |\n\n### Session Management\n\n- By default, the wallet auto-locks after 15 minutes\n- You can change this with `wallet_set_timeout` (set to 0 to disable)\n- Use `wallet_lock` to manually lock the wallet\n- Use `wallet_unlock` when you need Claude to transact again\n\n## Wallet Storage\n\nClaude's wallets are stored locally on your machine:\n\n```\n~/.aibtc/\n├── wallets.json       # Wallet index (names, addresses - no secrets)\n├── config.json        # Active wallet, settings\n└── wallets/\n    └── [wallet-id]/\n        └── keystore.json  # Encrypted mnemonic (AES-256-GCM + Scrypt)\n```\n\n**Security:**\n- AES-256-GCM encryption with Scrypt key derivation\n- Password required to unlock\n- Mnemonics never stored in plaintext\n- File permissions set to owner-only (0600)\n\n## Bitcoin L1 Support\n\nEach wallet automatically derives both a **Stacks address** and a **Bitcoin address** from the same mnemonic using BIP39/BIP32 standards.\n\n**Derivation Paths (BIP84):**\n- Mainnet: `m/84'/0'/0'/0/0` (Bitcoin coin type 0)\n- Testnet: `m/84'/1'/0'/0/0` (Bitcoin testnet coin type 1)\n\n**Address Format:**\n- Mainnet: `bc1q...` (Native SegWit P2WPKH)\n- Testnet: `tb1q...` (Native SegWit P2WPKH)\n\n**Capabilities:**\n- Full Bitcoin L1 transaction support (send BTC)\n- Balance and UTXO queries via mempool.space API\n- Fee estimation (fast/medium/slow)\n- P2WPKH (native SegWit) transactions for optimal fees\n\n**Example:**\n```\nYou: Create a wallet called \"my-wallet\"\nClaude: I've created a wallet with:\n        Stacks address: ST1ABC...\n        Bitcoin address: bc1q...\n\nYou: Send 50000 sats to bc1q...\nClaude: Done! Transaction broadcast: abc123...\n```\n\nBoth addresses are derived from the same recovery phrase, making it easy to manage both Layer 1 (Bitcoin) and Layer 2 (Stacks) assets.\n\n## Available Tools (150+ total)\n\n### Wallet Management\n| Tool | Description |\n|------|-------------|\n| `wallet_create` | Create a new wallet for Claude |\n| `wallet_import` | Import an existing wallet for Claude |\n| `wallet_unlock` | Unlock Claude's wallet |\n| `wallet_lock` | Lock Claude's wallet |\n| `wallet_list` | List Claude's available wallets |\n| `wallet_switch` | Switch Claude to a different wallet |\n| `wallet_delete` | Delete a wallet |\n| `wallet_export` | Export wallet mnemonic |\n| `wallet_status` | Check if Claude's wallet is ready (includes Stacks and Bitcoin addresses) |\n| `wallet_set_timeout` | Set how long wallet stays unlocked |\n\n### Bitcoin L1\n| Tool | Description |\n|------|-------------|\n| `get_btc_balance` | Get BTC balance (total, confirmed, unconfirmed) |\n| `get_btc_fees` | Get fee estimates (fast, medium, slow) |\n| `get_btc_utxos` | List UTXOs for an address |\n| `transfer_btc` | Send BTC to a recipient |\n| `get_cardinal_utxos` | UTXOs safe to spend (no inscriptions) |\n| `get_ordinal_utxos` | UTXOs containing inscriptions |\n\n### Mempool Watch (Bitcoin)\n| Tool | Description |\n|------|-------------|\n| `get_btc_mempool_info` | Get current Bitcoin mempool statistics (tx count, vsize, fees, fee histogram) |\n| `get_btc_transaction_status` | Get confirmation status and details for a Bitcoin transaction by txid |\n| `get_btc_address_txs` | Get recent transaction history for a Bitcoin address (last 25 transactions) |\n\n### Bitcoin Inscriptions\n| Tool | Description |\n|------|-------------|\n| `get_taproot_address` | Get wallet's Taproot (P2TR) address |\n| `estimate_inscription_fee` | Calculate inscription cost |\n| `inscribe` | Create inscription commit transaction |\n| `inscribe_reveal` | Complete inscription reveal transaction |\n| `get_inscription` | Fetch inscription content from reveal tx |\n| `get_inscriptions_by_address` | List inscriptions owned by address |\n\n### PSBT & Ordinals Trading\n| Tool | Description |\n|------|-------------|\n| `psbt_create_ordinal_buy` | Build a buyer-side PSBT for ordinal purchase |\n| `psbt_sign` | Sign selected PSBT inputs with active wallet keys |\n| `psbt_decode` | Decode PSBT inputs/outputs/signature status |\n| `psbt_broadcast` | Finalize and broadcast a fully-signed PSBT |\n\n### Message Signing\n| Tool | Description |\n|------|-------------|\n| `sip018_sign` | Sign structured Clarity data (SIP-018) |\n| `sip018_verify` | Verify SIP-018 signature |\n| `sip018_hash` | Compute SIP-018 hash without signing |\n| `stacks_sign_message` | Sign plain text (SIWS-compatible) |\n| `stacks_verify_message` | Verify Stacks message signature |\n| `btc_sign_message` | Sign with Bitcoin key (BIP-137) |\n| `btc_verify_message` | Verify BIP-137 signature |\n\n### Wallet & Balance\n| Tool | Description |\n|------|-------------|\n| `get_wallet_info` | Get Claude's wallet addresses (Stacks + Bitcoin) and status |\n| `get_stx_balance` | Get STX balance for any address |\n| `get_stx_fees` | Get STX fee estimates (low, medium, high) |\n\n### STX Transfers\n| Tool | Description |\n|------|-------------|\n| `transfer_stx` | Send STX to a recipient |\n| `broadcast_transaction` | Broadcast a pre-signed transaction |\n\n### sBTC Operations\n| Tool | Description |\n|------|-------------|\n| `sbtc_get_balance` | Get sBTC balance |\n| `sbtc_transfer` | Send sBTC |\n| `sbtc_initiate_withdrawal` | Initiate sBTC peg-out to BTC L1 |\n| `sbtc_withdraw` | Alias for withdrawal initiation |\n| `sbtc_withdrawal_status` | Check withdrawal request status |\n| `sbtc_get_deposit_info` | Get BTC deposit instructions |\n| `sbtc_deposit` | Build, sign, and broadcast BTC→sBTC deposit |\n| `sbtc_deposit_status` | Check deposit status via Emily API |\n| `sbtc_get_peg_info` | Get peg ratio and TVL |\n\n### Token Operations (SIP-010)\n| Tool | Description |\n|------|-------------|\n| `get_token_balance` | Get balance of any SIP-010 token |\n| `transfer_token` | Send any SIP-010 token |\n| `get_token_info` | Get token metadata |\n| `list_user_tokens` | List tokens owned by an address |\n| `get_token_holders` | Get top holders of a token |\n\n### NFT Operations (SIP-009)\n| Tool | Description |\n|------|-------------|\n| `get_nft_holdings` | List NFTs owned by an address |\n| `get_nft_metadata` | Get NFT metadata |\n| `transfer_nft` | Send an NFT |\n| `get_nft_owner` | Get NFT owner |\n| `get_collection_info` | Get NFT collection details |\n| `get_nft_history` | Get NFT transfer history |\n\n### Stacking / PoX\n| Tool | Description |\n|------|-------------|\n| `get_pox_info` | Get current PoX cycle info |\n| `get_stacking_status` | Check stacking status |\n| `stack_stx` | Lock STX for stacking |\n| `extend_stacking` | Extend stacking period |\n\n### BNS Domains (V1 + V2)\n| Tool | Description |\n|------|-------------|\n| `lookup_bns_name` | Resolve .btc domain to address |\n| `reverse_bns_lookup` | Get .btc domain for an address |\n| `get_bns_info` | Get domain details |\n| `check_bns_availability` | Check if domain is available |\n| `get_bns_price` | Get registration price |\n| `list_user_domains` | List domains owned |\n| `preorder_bns_name` | Preorder a .btc domain (step 1 of 2) |\n| `register_bns_name` | Register a .btc domain (step 2 of 2) |\n\n### Smart Contracts\n| Tool | Description |\n|------|-------------|\n| `call_contract` | Call a smart contract function |\n| `deploy_contract` | Deploy a Clarity smart contract |\n| `get_transaction_status` | Check transaction status |\n| `call_read_only_function` | Call read-only function |\n\n### DeFi - ALEX DEX (Mainnet)\n\nUses the official `alex-sdk` for swap operations. Supports simple token symbols like \"STX\", \"ALEX\".\n\n| Tool | Description |\n|------|-------------|\n| `alex_list_pools` | Discover all available trading pools |\n| `alex_get_swap_quote` | Get expected output for a token swap |\n| `alex_swap` | Execute a token swap (SDK handles routing) |\n| `alex_get_pool_info` | Get liquidity pool reserves |\n\n### DeFi - Zest Protocol (Mainnet)\n\nSupports 10 assets: sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC\n\n| Tool | Description |\n|------|-------------|\n| `zest_list_assets` | List all supported lending assets |\n| `zest_get_position` | Get user's supply/borrow position |\n| `zest_supply` | Supply assets to earn interest |\n| `zest_withdraw` | Withdraw supplied assets |\n| `zest_borrow` | Borrow against collateral |\n| `zest_repay` | Repay borrowed assets |\n\n### DeFi - Bitflow DEX (Mainnet)\n\nDEX aggregator that routes trades across multiple liquidity sources.\n\n> **Units:** Bitflow tools default to **human units** (`amountUnit: \"human\"`). Pass `\"2\"` to swap 2 STX, not `\"2000000\"`. Set `amountUnit: \"base\"` only when working with raw on-chain integers. See [Units & Decimals guide](skill/references/stacks-defi.md#units--decimals-bitflow--defi) for details and common pitfalls.\n\n| Tool | Description |\n|------|-------------|\n| `bitflow_get_ticker` | Get market data (no API key needed) |\n| `bitflow_get_quote` | Get swap quote |\n| `bitflow_swap` | Execute token swap |\n\n### Pillar Smart Wallet\n\nsBTC smart wallet with Zest Protocol integration and passkey authentication.\n\n| Tool | Description |\n|------|-------------|\n| `pillar_connect` | Connect to Pillar wallet |\n| `pillar_send` | Send sBTC to BNS names or addresses |\n| `pillar_boost` | Create leveraged sBTC position |\n| `pillar_position` | View wallet and Zest position |\n\nFor autonomous agents, use `pillar_direct_*` tools (no browser needed).\n\n### Blockchain Queries\n| Tool | Description |\n|------|-------------|\n| `get_account_info` | Get account nonce, balance |\n| `get_account_transactions` | List transaction history |\n| `get_block_info` | Get block details |\n| `get_mempool_info` | Get pending transactions |\n| `get_contract_info` | Get contract ABI and source |\n| `get_contract_events` | Get contract event history |\n| `get_network_status` | Get network health status |\n\n### Yield Hunter (Autonomous)\n| Tool | Description |\n|------|-------------|\n| `yield_hunter_start` | Start autonomous sBTC→Zest deposits |\n| `yield_hunter_stop` | Stop yield hunting |\n| `yield_hunter_status` | Check yield hunter status |\n| `yield_hunter_configure` | Adjust threshold, reserve, interval |\n\n### x402 API Endpoints\n| Tool | Description |\n|------|-------------|\n| `list_x402_endpoints` | Discover x402 endpoints |\n| `execute_x402_endpoint` | Execute x402 endpoint with auto-payment |\n| `scaffold_x402_endpoint` | Generate x402 Cloudflare Worker project |\n| `scaffold_x402_ai_endpoint` | Generate x402 AI API with OpenRouter |\n\n## Usage Examples\n\n**Wallet management:**\n> \"What's your wallet address?\"\n> \"Create a wallet for yourself\"\n> \"Unlock your wallet\"\n> \"Keep your wallet unlocked for 1 hour\"\n\n**Check balances:**\n> \"How much STX do you have?\"\n> \"What's your sBTC balance?\"\n\n**Transfer tokens:**\n> \"Send 2 STX to ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM\"\n> \"Transfer 0.001 sBTC to muneeb.btc\"\n\n**NFTs:**\n> \"What NFTs do you own?\"\n> \"Send this NFT to alice.btc\"\n\n**BNS domains:**\n> \"What address is satoshi.btc?\"\n> \"Is myname.btc available?\"\n\n**DeFi trading (mainnet):**\n> \"What pools are available on ALEX?\"\n> \"Swap 0.1 STX for ALEX\"\n> \"Get a quote for 100 STX to ALEX\"\n> \"What assets can I lend on Zest?\"\n> \"Supply 100 stSTX to Zest\"\n> \"Borrow 50 aeUSDC from Zest\"\n> \"Check my Zest position\"\n\n**x402 endpoints:**\n> \"Get trending liquidity pools\"\n> \"Tell me a dad joke\"\n\n## Supported Tokens\n\nWell-known tokens can be referenced by symbol:\n- **sBTC** - Native Bitcoin on Stacks\n- **USDCx** - USD Coin on Stacks\n- **ALEX** - ALEX governance token\n- **wSTX** - Wrapped STX\n\n**ALEX DEX tokens:** STX, ALEX, and any token from `alex_list_pools`\n\n**Zest Protocol assets:** sBTC, aeUSDC, stSTX, wSTX, USDH, sUSDT, USDA, DIKO, ALEX, stSTX-BTC\n\nOr use any SIP-010 token by contract ID: `SP2X...::token-name`\n\n## Configuration\n\n| Environment Variable | Description | Default |\n|---------------------|-------------|---------|\n| `NETWORK` | `mainnet` or `testnet` | `mainnet` (installer) / `testnet` (if unset) |\n| `API_URL` | Default x402 API base URL | `https://x402.biwas.xyz` |\n| `CLIENT_MNEMONIC` | (Optional) Pre-configured mnemonic | - |\n| `HIRO_API_KEY` | (Optional) Hiro API key for higher rate limits | - |\n| `SPEND_LIMIT_ENABLED` | Set `false` to disable the wallet spending limit | `true` |\n| `SPEND_LIMIT_DAILY_USTX` / `SPEND_LIMIT_SESSION_USTX` | STX spend cap per day / per unlock (micro-STX) | `10000000` (10 STX) |\n| `SPEND_LIMIT_DAILY_SATS` / `SPEND_LIMIT_SESSION_SATS` | BTC spend cap per day / per unlock (sats) | `50000` |\n\n**Note on `NETWORK`:** The `--install` command writes `NETWORK=mainnet` by default (pass `--testnet` to use testnet). If you omit `NETWORK` from your config entirely, the runtime fallback is `testnet`. Most users should set this explicitly.\n\n**Note on spending limits:** A default-on safety rail meters every outbound spend (`transfer_stx`, `transfer_btc`, x402/L402 auto-payments) against a cumulative per-session and per-day cap, so a single bad instruction or a malicious endpoint can't drain the wallet. A spend over the cap is blocked and reports the remaining budget. Raise the caps via the env vars above, or disable with `SPEND_LIMIT_ENABLED=false`. See [SECURITY.md](SECURITY.md#limit-blast-radius).\n\n**Note:** `CLIENT_MNEMONIC` is optional. The recommended approach is to let Claude create its own wallet. `HIRO_API_KEY` is optional but recommended for production use — without it, you may hit Hiro's public rate limits (429 responses). Get a key at [platform.hiro.so](https://platform.hiro.so).\n\n## Architecture\n\n```\nYou ←→ Claude ←→ aibtc-mcp-server\n                        ↓\n              Claude's Wallet (~/.aibtc/)\n                        ↓\n              ┌─────────┴─────────┐\n              ↓                   ↓\n        Hiro Stacks API    x402 Endpoints\n              ↓                   ↓\n        Stacks Blockchain  Paid API Services\n```\n\n## Security Notes\n\n- Claude's wallet is stored encrypted on YOUR machine\n- Password is never stored - only the encrypted keystore\n- Mnemonics shown only once at creation\n- Auto-lock after 15 minutes (configurable)\n- Transactions signed locally before broadcast\n- **Spending limit (default-on):** outbound spends are capped per session and per day so a single bad instruction can't drain the wallet — see [Configuration](#configuration)\n- **Secret-scanning pre-commit hook:** contributors get a hook (auto-installed via `npm install`) that blocks committing a seed phrase or private key\n- For mainnet: Fund with small amounts first\n\nSee [SECURITY.md](SECURITY.md) for the full wallet-key protection model and key-leak recovery steps.\n\n## Advanced: Pre-configured Mnemonic\n\nFor automated setups where Claude needs immediate wallet access, add the `CLIENT_MNEMONIC` environment variable to your MCP server config (in `~/.claude.json` for Claude Code, or `claude_desktop_config.json` for Claude Desktop):\n\n```json\n{\n  \"mcpServers\": {\n    \"aibtc\": {\n      \"command\": \"npx\",\n      \"args\": [\"@aibtc/mcp-server@latest\"],\n      \"env\": {\n        \"CLIENT_MNEMONIC\": \"your twenty four word mnemonic phrase\",\n        \"NETWORK\": \"testnet\"\n      }\n    }\n  }\n}\n```\n\nThis bypasses the wallet creation flow - Claude has immediate access to transact.\n\n## Agent Skill\n\nThis package includes an [Agent Skills](https://agentskills.io) compatible skill that teaches any LLM how to use the Bitcoin wallet capabilities effectively.\n\n### What is it?\n\nThe `aibtc-bitcoin-wallet` skill provides:\n- Structured workflows for Bitcoin L1 operations (balance, send, fees)\n- Reference guides for Pillar smart wallets and Stacks L2 DeFi\n- LLM-agnostic instructions that work with Claude Code, Cursor, Codex, and 20+ other tools\n\n### Using the Skill\n\nThe skill is automatically included when you install the MCP server. Find it at:\n- **Local**: `node_modules/@aibtc/mcp-server/skill/SKILL.md`\n- **ClawHub**: [clawhub.ai/skills](https://www.clawhub.ai/skills) - search for `aibtc-bitcoin-wallet`\n\n### Skill Structure\n\n```\nskill/\n├── SKILL.md                        # Bitcoin L1 core workflows\n└── references/\n    ├── genesis-lifecycle.md        # Agent registration & check-in\n    ├── inscription-workflow.md     # Bitcoin inscription guide\n    ├── pillar-wallet.md            # Pillar smart wallet guide\n    ├── stacks-defi.md              # Stacks L2 / DeFi operations\n    └── troubleshooting.md          # Common issues and solutions\n```\n\n## Development\n\n```bash\ngit clone https://github.com/aibtcdev/aibtc-mcp-server.git\ncd aibtc-mcp-server\nnpm install\nnpm run build\nnpm run dev       # Run with tsx (development)\n```\n\n### Releases\n\nThis repo uses [Release Please](https://github.com/googleapis/release-please) for automated releases:\n\n1. Merge PRs with conventional commits (`feat:`, `fix:`, etc.)\n2. Release Please creates a Release PR with changelog\n3. Merge the Release PR to publish\n\n### Repository Secrets (Maintainers)\n\n| Secret | Description |\n|--------|-------------|\n| `NPM_TOKEN` | npm publish token for @aibtc scope |\n| `CLAWHUB_API_TOKEN` | ClawHub API token for skill publishing |\n\nTo obtain a ClawHub API token, visit [clawhub.ai](https://www.clawhub.ai) and create an account.\n\n## License\n\nMIT\n",
  "bytes": 25251,
  "sha": "2fe1118d22a8c58ce648587a68dd9be0d2523970ac201a1f8171e98bd2aafd46",
  "repo_slug": "aibtcdev/aibtc-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_aibtcdev_mcp_server_96893793/readme"
}