Aibtc Official Mcp Server

---
name: aibtc-bitcoin-wallet
description: Bitcoin L1 wallet for agents - check balances, send BTC, manage UTXOs. Extends to Stacks L2 (STX, DeFi) and Pillar smart wallets (sBTC yield).
license: MIT
metadata:
  author: aibtcdev
  version: 1.69.0 # x-release-please-version
  npm: "@aibtc/mcp-server"
  github: https://github.com/aibtcdev/aibtc-mcp-server
---

# 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 | `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)
- Direct (non-sponsored) payment: signs a standard sBTC transfer and settles through the x402 facilitator — no relay in the middle
- Sender pays BOTH the sBTC message cost AND its own STX gas; requires an unlocked wallet holding sBTC and STX (mainnet only)
- 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).

### 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 (register_identity)
- L4: Reputation bootstrapping (get_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.*