Bitcoin wallet MCP server

⚠️ Warning: Experimental. Not yet safe for meaningful funds. Use only with wallets you are prepared to lose. The code is not battle-tested, audited, or hardened. This doc covers setup, configuration, running, and the full tool reference.

Intro

This repo is a single MCP server that exposes Bitcoin (Layer 1) and Stacks (Layer 2) wallet operations as tools. Agents or other MCP clients connect over stdio, pass tool names and arguments as JSON, and get back structured results. The server wraps local Python wallet code and external APIs (mempool.space, Hiro, CoinGecko, etc.). Destructive actions (send, sign-and-broadcast, deploy) support dry_run and do not broadcast by default. No keys or mnemonics are ever returned.

What it exposes: 93 tools in two groups.

1. Layer 1 (Bitcoin): addresses, balance (confirmed and unconfirmed), UTXOs, fee estimation, single and multi-recipient sends, sweep, PSBT sign/decode, message sign/verify, Ordinals / inscriptions, inscription creation, transaction history and RBF, Ledger (Bitcoin app).
2. Layer 2 (Stacks): STX addresses and balances, nonce, STX and token transfers, Clarity call/deploy/read, signing, swaps (Alex, Bitflow, Velar), sBTC bridge, stacking, BNS, market and portfolio data, Ledger (Stacks app), enhanced transaction queries with filtering, mempool monitoring, block explorer, contract event monitoring, token metadata (SIP-10/SIP-9), and network statistics. One mnemonic or WIF key drives both layers; Stacks keys are derived from the same seed.

---

Table of contents

• Intro
• Overview
• Requirements
• Installation
• Configuration
• Running the server
• Architecture
• Tools reference
  • Layer 1 (Bitcoin)
    • Core Bitcoin
    • Ordinals & inscriptions
    • Inscription creation & onramp
    • Transaction & wallet management
    • Ledger hardware wallet (Bitcoin)
  • Layer 2 (Stacks)
    • Stacks (STX)
    • Swaps, DeFi & bridge
    • BNS & market data
    • Ledger hardware wallet (Stacks)
    • Enhanced transaction queries
    • Mempool operations
    • Block explorer
    • Contract event monitoring
    • Token metadata
    • Network statistics & health
• Security
• Testing
• Troubleshooting
• Reference
• Related documents

---

Overview

• Purpose: Layer 1 (Bitcoin) and Layer 2 (Stacks) wallet operations as MCP tools with a single, safe interface.
• Design: Destructive operations support dry_run (default true). Responses: { "success": true, ... } or { "success": false, "error": "..." }. No keys or mnemonics in responses.

---

Requirements

• Python: 3.10 or later (for type hints and runtime).
• OS: Any platform supported by Python and the dependencies (Linux, macOS, Windows). Ledger tools require a Ledger device and USB (or Speculos with interface: "tcp").
• Dependencies: Listed in requirements.txt; install with pip install -r requirements.txt (see Installation).

Package	Purpose
mcp	MCP server and stdio transport
python-dotenv	Load .env configuration
bip-utils	BIP-39/44/84 derivation
bit	Bitcoin transaction building (legacy paths)
python-bitcoinlib	PSBT, keys, addresses, raw tx
requests	HTTP for mempool.space, Hiro, CoinGecko, etc.
coincurve	ECDSA and key operations
ledgercomm	Ledger device communication (optional for Ledger tools)

---

Installation

1. Clone the repo. If you did not use --recurse-submodules, run git submodule update --init foundation.

2. Create a virtual environment (recommended):

   python3 -m venv .venv
   source .venv/bin/activate   # Windows: .venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure environment: Copy .env.example to .env and set at least one key source and network (see Configuration).

5. Optional: If you use the repo’s run_btc_wallet_mcp.sh, it will prefer ../../execution/venv when present; otherwise it uses python3 from PATH.

---

Configuration

Configuration comes from environment variables. The runner script loads .env from the repository root (two levels above this directory). You can also set variables in the shell or in your MCP host.

Key material (choose one)

Variable	Description
BTC_PRIVATE_KEY	WIF private key for the wallet.
BTC_MNEMONIC	BIP-39 mnemonic (12 or 24 words).
BTC_MNEMONIC_PASSPHRASE	Optional BIP-39 passphrase when using BTC_MNEMONIC.

Stacks (STX) keys are derived from the same mnemonic using the Stacks path m/44'/5757'/0'/0/0.

Network and safety

Variable	Description	Default
BTC_NETWORK	mainnet or testnet.	testnet
BTC_DRY_RUN	If true, send/sign tools do not broadcast by default.	true

Limits (optional)

Variable	Description
BTC_MAX_SEND_BTC	Maximum BTC per transfer (decimal string or number).
BTC_MAX_FEE_SATS	Maximum fee in satoshis per transaction.

Fee behavior

Variable	Description
BTC_FEE_RATE_SAT_PER_BYTE	Fixed fee rate (sat/vB). If set, overrides tier.
BTC_FEE_TIER	mempool.space tier: hourFee, halfHourFee, fastestFee. Used when no fixed rate is set.

---

Running the server

• Wrapper script (recommended): run_btc_wallet_mcp.sh loads .env from repo root, uses execution/venv/bin/python3 if present else python3, runs the server over stdio.
• Direct: Set env from .env, then run python3 bitcoin_wallet_mcp_server.py from this directory.

Cursor MCP config

Add to .cursor/mcp.json (or your Cursor MCP config file):

{
  "mcpServers": {
    "bitcoin-wallet": {
      "command": "/absolute/path/to/repo/mcp/btc_wallet/run_btc_wallet_mcp.sh"
    }
  }
}

Use an absolute path to your repo. The server lives in mcp/btc_wallet/. Put .env at repo root if you use the script’s env loading.

---

Architecture

• Entrypoint: bitcoin_wallet_mcp_server.py. Single MCP server; registers all tools and delegates to wallet modules.
• Layer 1 (Bitcoin) modules: bitcoin_wallet.py (addresses, accounts, balance, sends, PSBT, message signing, fees, UTXOs); ord_wallet.py (ordinals and inscriptions); inscribe_onramp_wallet.py (inscription creation, buy quotes); advanced_wallet.py (transaction history, RBF, wallet network, enhanced STX transaction queries, network statistics); ledger_wallet.py (Ledger Bitcoin app).
• Layer 2 (Stacks) modules: stx_wallet.py (addresses, accounts, balance, STX/token transfers, contracts, signing); defi_wallet.py (swaps via Alex, Bitflow, Velar; sBTC bridge; stacking with enhanced cycle metrics); bns_market_wallet.py (BNS, market, portfolio); stx_mempool.py (mempool monitoring and statistics); stx_explorer.py (block explorer queries); stx_events.py (contract event monitoring); stx_token_metadata.py (SIP-10/SIP-9 token metadata); ledger_wallet.py (Ledger Stacks app).

Responses: JSON with "success": true and data, or "success": false and "error". Keys and mnemonics are never returned.

---

Tools reference

93 tools, grouped by Layer 1 (Bitcoin) and Layer 2 (Stacks). Parameters and response shape are below; optional args can be omitted. dry_run defaults to BTC_DRY_RUN (usually true).

---

Layer 1 (Bitcoin)

Tools for the Bitcoin chain: addresses, balance, transfers, PSBT, message signing, fees, UTXOs, ordinals, inscription creation, transaction management, and Ledger (Bitcoin app).

Core Bitcoin

Address and account management, balance, prices, transfers, PSBT, message signing, fees, UTXOs.

Tool	Description
btc_get_addresses	All derived addresses (P2PKH, P2SH-P2WPKH, P2WPKH, P2TR) with public keys and derivation paths.
btc_get_accounts	Accounts with balances per address type; uses mempool.space for UTXO data.
btc_get_info	Wallet version, network, supported tools, and configuration (e.g. dry_run_default, fee_tier).

Parameters: None.

Example response (btc_get_addresses):

{
  "success": true,
  "addresses": [
    {
      "symbol": "BTC",
      "type": "p2wpkh",
      "address": "bc1q...",
      "publicKey": "02abc...",
      "derivationPath": "m/84'/0'/0'/0/0",
      "label": "bip84_p2wpkh_0"
    }
  ],
  "network": "mainnet"
}

---

Tool	Description
btc_wallet_get_balance	Current wallet balance in BTC.
btc_wallet_get_prices	Current BTC prices in USD and EUR.

Parameters: None.

Example response (btc_wallet_get_balance): { "success": true, "balance_btc": "0.12345678", "network": "testnet" }
Example response (btc_wallet_get_prices): { "success": true, "usd": "91000.12", "eur": "84000.34" }

---

Tool	Description
btc_wallet_preview_transfer	Preview a transfer and estimated fees. Provide either amount_btc or amount_eur.
btc_wallet_send_transfer	Send BTC to a single recipient (BTC or EUR amount). Prefer calling the preview tool first and require explicit user confirmation.

Parameters (preview): to_address (required), amount_btc or amount_eur (one required).
Parameters (send): to_address (required), amount_btc or amount_eur (one required), optional max_fee_sats, memo, dry_run.

---

Tool	Description
btc_send_transfer	Send BTC to one or more recipients with amounts in sats; multi-output.
btc_send_max	Sweep: send maximum spendable BTC to one address (amount after fees).
btc_combine_utxos	Consolidate UTXOs into one output (optionally to a given address).

Parameters (btc_send_transfer): recipients (array of { "address", "amount_sats" }), optional max_fee_sats, memo, dry_run.
Parameters (btc_send_max): to_address (required), optional fee_rate, dry_run.
Parameters (btc_combine_utxos): optional to_address, fee_rate, dry_run.

Example request (btc_send_transfer):

{
  "recipients": [
    { "address": "bc1q...", "amount_sats": 50000 },
    { "address": "bc1q...", "amount_sats": 30000 }
  ],
  "dry_run": true
}

Example response: { "success": true, "txid": "DRYRUN_...", "num_recipients": 2, "dry_run": true, "network": "testnet" }

---

Tool	Description
btc_sign_psbt	Sign a PSBT (hex or base64). Optional sign_at_index, broadcast, dry_run.
btc_sign_batch_psbt	Sign multiple PSBTs in one call.
btc_decode_psbt	Decode a PSBT and return a human-readable summary (inputs, outputs, total value, finalization).

Parameters (btc_sign_psbt): psbt (hex or base64), optional sign_at_index (array of input indices), broadcast, dry_run.
Parameters (btc_sign_batch_psbt): psbts (array of PSBT strings), optional broadcast.
Parameters (btc_decode_psbt): psbt.

Example response (btc_decode_psbt): { "success": true, "num_inputs": 2, "num_outputs": 3, "total_input_sats": 150000, "has_witness_utxo": true, "is_finalized": false, "size_bytes": 512 }

---

Tool	Description
btc_sign_message	Sign a message (ECDSA legacy Bitcoin Signed Message or BIP-322).
btc_verify_message	Verify a signed Bitcoin message.

Parameters (sign): message, optional protocol (ecdsa | BIP-322), address_type (e.g. p2wpkh).
Parameters (verify): message, signature, address.

Example response (sign): { "success": true, "signature": "H...", "address": "bc1q...", "message": "Hello, world!", "protocol": "ecdsa" }

---

Tool	Description
btc_get_fees	Recommended fee rates from mempool.space (all tiers).
btc_estimate_fee	Estimate fee for given input/output count and address type.

Parameters (btc_estimate_fee): num_inputs, num_outputs, address_type (e.g. p2wpkh), optional fee_tier.

Example response (btc_get_fees): { "success": true, "fastest_sat_per_vb": 25, "half_hour_sat_per_vb": 18, "hour_sat_per_vb": 12, "economy_sat_per_vb": 5, "minimum_sat_per_vb": 1, "network": "mainnet", "source": "mempool.space" }

---

Tool	Description
btc_list_utxos	List UTXOs with optional filters: address type, min value, confirmed only.
btc_get_utxo_details	Detailed info for one UTXO (scriptPubKey, confirmation, tx metadata).

Parameters (btc_list_utxos): optional address_type, min_value_sats, confirmed_only.
Parameters (btc_get_utxo_details): txid, vout.

Example response (btc_list_utxos): { "success": true, "utxos": [{ "txid": "...", "vout": 0, "value_sats": 50000, "value_btc": "0.00050000", "confirmed": true, "address": "bc1q...", "address_type": "p2wpkh" }], "count": 1, "total_sats": 50000, "total_btc": "0.00050000" }

---

Ordinals & inscriptions

Uses Hiro Ordinals API for inscription data; taproot (P2TR) for ordinals storage; P2WPKH for fee funding.

Tool	Description
ord_get_inscriptions	List inscriptions owned by the wallet; pagination via offset, limit.
ord_get_inscription_details	Detailed inscription info (genesis, content type, sat ordinal, rarity, UTXO location).

Parameters (ord_get_inscriptions): optional offset, limit.
Parameters (ord_get_inscription_details): inscription_id.

---

Tool	Description
ord_send_inscriptions	Send inscriptions to recipients; full UTXO transfer; separate payment UTXO for fees.
ord_send_inscriptions_split	Send inscriptions with UTXO splitting (only the inscription's sat range to recipient, rest to sender).
ord_extract_from_utxo	Extract ordinals from a mixed UTXO into separate outputs.
ord_recover_bitcoin	Recover BTC from ordinals address (sweep non-inscription UTXOs to payment address).
ord_recover_ordinals	Move inscription-bearing UTXOs from payment address to ordinals (taproot) address.

Parameters (send tools): transfers (array of { "address", "inscriptionId" }), optional dry_run.
Parameters (ord_extract_from_utxo): outpoint (txid:vout), optional dry_run.
Parameters (recover tools): optional dry_run.

---

Inscription creation & onramp

Tool	Description
ord_create_inscription	Create a single inscription; content type and body; estimates commit/reveal fees.
ord_create_repeat_inscriptions	Create multiple inscriptions in batch with shared fee estimation.
buy_get_providers	List fiat-to-crypto onramp providers and supported currencies.
buy_get_quote	Fiat-to-crypto quote (e.g. price and fees).

Parameters (ord_create_inscription): content_type, content (text or hex if content_encoding: hex), optional content_encoding, dry_run.
Parameters (ord_create_repeat_inscriptions): content_type, contents (array), optional dry_run.
Parameters (buy_get_providers): optional crypto, fiat.
Parameters (buy_get_quote): crypto, fiat, fiat_amount (or equivalent).

---

Transaction & wallet management

Tool	Description
tx_get_history	Transaction history for BTC and/or STX.
tx_get_status	Status of a single transaction (BTC or STX).
tx_speed_up	Speed up pending BTC tx via RBF.
tx_cancel	Cancel pending BTC tx (RBF send-to-self).
wallet_get_network	Current network config, API endpoints, fee settings.
wallet_switch_network	Switch between mainnet and testnet.
wallet_add_network	Add custom network (name, BTC API URL, etc.).
wallet_get_supported_methods	List all MCP tool names and descriptions.

Parameters (tx_get_history): optional chain (btc | stx | both), limit.
Parameters (tx_get_status): txid, chain (btc | stx).
Parameters (tx_speed_up, tx_cancel): txid, optional dry_run.
Parameters (wallet_switch_network): network (mainnet | testnet).
Parameters (wallet_add_network): name, btc_api_url, and other endpoint fields as needed.

---

Ledger hardware wallet (Bitcoin)

Requires a Ledger device connected via USB with the Bitcoin app open. Use interface: "tcp" for Speculos.

Tool	Description
ledger_get_addresses	Get BTC addresses (P2PKH, P2SH-P2WPKH, P2WPKH, P2TR) from Ledger.
ledger_sign_psbt	Sign a PSBT with Ledger Bitcoin app.

Parameters: account (optional), display (optional, show on device), interface (hid or tcp for Speculos).
Parameters (sign PSBT): psbt, interface.

---

Layer 2 (Stacks)

Tools for the Stacks chain: STX addresses, balance, transfers, contracts, swaps, sBTC bridge, stacking, BNS, market/portfolio data, and Ledger (Stacks app).

Stacks (STX)

Keys are derived from BTC_MNEMONIC using path m/44'/5757'/0'/0/0. Hiro Stacks API is used for chain data and broadcasting.

Tool	Description
stx_get_addresses	Stacks addresses with public keys and derivation paths.
stx_get_accounts	Accounts with STX balance, locked amounts, nonces.
stx_get_balance	STX balance plus fungible and non-fungible token balances for an address.
stx_get_networks	Available Stacks networks (mainnet, testnet) with chain IDs and API URLs.

Parameters (stx_get_balance): optional address.

Example response (stx_get_balance): { "success": true, "address": "SP...", "balance_ustx": 5000000, "balance_stx": "5.000000", "fungible_tokens": [...], "non_fungible_tokens": [...] }

---

Tool	Description
stx_transfer_stx	Transfer STX; amount in micro-STX (1 STX = 1_000_000 uSTX).
stx_preview_transfer	Preview STX transfer with fee and balance check.
stx_transfer_sip10_ft	Transfer a SIP-10 fungible token via contract call.
stx_transfer_sip9_nft	Transfer a SIP-9 NFT via contract call.

Parameters (stx_transfer_stx): recipient, amount_ustx, optional memo, dry_run.
Parameters (stx_transfer_sip10_ft): recipient, asset (e.g. SP...contract::token), amount, optional dry_run.
Parameters (stx_transfer_sip9_nft): recipient, asset, asset_id, optional dry_run.

---

Tool	Description
stx_call_contract	Call a public Clarity function; args in Clarity notation.
stx_deploy_contract	Deploy a Clarity contract.
stx_read_contract	Read-only contract call (no transaction).

Parameters (stx_call_contract): contract_address, contract_name, function_name, function_args (array of Clarity literals), optional dry_run.
Parameters (stx_deploy_contract): contract_name, clarity_code, optional dry_run.
Parameters (stx_read_contract): contract_address, contract_name, function_name, optional function_args.

Clarity argument examples: u100, i-5, true/false, none, 'SP... (principal), 0xDEADBEEF (buffer), "hello" (string-ascii).

---

Tool	Description
stx_sign_transaction	Sign a serialized Stacks transaction (SIP-30); hex in, signed hex out.
stx_sign_transactions	Sign multiple Stacks transactions.
stx_sign_message	Sign a UTF-8 message (recoverable ECDSA).
stx_sign_structured_message	Sign SIP-018 structured data (domain + message).
stx_get_nonce	Current nonce for a Stacks address.
stx_estimate_fee	Estimate Stacks transaction fee in micro-STX.
stx_update_profile	Update on-chain profile (schema.org/Person); requires BNS name.

Parameters (stx_sign_message): message.
Parameters (stx_sign_structured_message): domain, message (JSON string).
Parameters (stx_get_nonce): optional address.

---

Swaps, DeFi & bridge

Swap protocols: Alex, Bitflow, and Velar. Use protocol for quotes and pair listing: alex (pools and token prices), bitflow (ticker API), velar (Alex token prices). Execution: swap_execute supports protocol=alex only (default). For bitflow or velar you get a quote only; to execute, use protocol alex. Execution for Bitflow and Velar could be added via protocol SDKs (e.g. Velar’s @velarprotocol/velar-sdk returns contract-call params; Bitflow requires their SDK or API).

Tool	Description
swap_get_supported_pairs	List supported swap pairs and protocols (Alex pools, Bitflow ticker).
swap_get_quote	Get swap quote: estimated output, rate, fees. Protocol: alex (default), bitflow, or velar.
swap_execute	Execute swap via Alex DEX contract call (protocol=alex). Bitflow/Velar execution could be added via protocol SDKs.
swap_get_history	Swap transaction history from on-chain activity.
sbtc_get_balance	sBTC token balance for the wallet.
sbtc_bridge_deposit	Deposit info for bridging BTC → sBTC.
sbtc_bridge_withdraw	Withdrawal info for sBTC → BTC.
stx_get_stacking_info	PoX stacking status, cycle info, thresholds, wallet stacking state.
stx_stack	Initiate STX solo stacking (lock STX for reward cycles).
stx_revoke_delegation	Revoke stacking delegation via PoX contract.

Parameters (swap_get_quote): token_in, token_out, amount, optional protocol (alex | bitflow | velar, default alex).
Parameters (swap_execute): token_in, token_out, amount, optional min_output, protocol (must be alex for execution), dry_run.
Parameters (sbtc_bridge_deposit): amount_sats, optional dry_run.
Parameters (sbtc_bridge_withdraw): amount_sats, btc_address, optional dry_run.
Parameters (stx_stack): amount_ustx, pox_address, num_cycles, optional dry_run.

---

BNS & market data

Tool	Description
bns_lookup	Resolve BNS name to Stacks address.
bns_get_names	BNS names owned by an address.
bns_register	Register a BNS name (contract call).
market_get_prices	Multi-asset prices (e.g. CoinGecko).
market_get_history	Price history for charting.
portfolio_get_summary	Portfolio summary with USD valuations (BTC + STX).
portfolio_get_assets	All assets (BTC, STX, fungible tokens) with balances.
portfolio_get_collectibles	Collectibles: Bitcoin inscriptions and Stacks NFTs.

Parameters (bns_lookup): name (e.g. alice.btc).
Parameters (bns_get_names): address.
Parameters (bns_register): name, namespace (e.g. btc), optional dry_run.
Parameters (market_get_prices): coins (e.g. ["bitcoin", "blockstack"]).
Parameters (market_get_history): coin, days, optional interval (e.g. daily).
Parameters (portfolio_get_collectibles): optional limit.

---

Ledger hardware wallet (Stacks)

Requires a Ledger device connected via USB with the Stacks app open. Use interface: "tcp" for Speculos.

Tool	Description
ledger_get_stx_addresses	Get Stacks addresses from Ledger device with public keys and derivation paths.
ledger_sign_stx_transaction	Sign a Stacks transaction with Ledger Stacks app.

Parameters (ledger_get_stx_addresses): optional account, display, interface.
Parameters (ledger_sign_stx_transaction): tx_hex, optional derivation_path, interface.

---

Enhanced transaction queries

Advanced Stacks transaction queries with filtering, contract-specific queries, and mempool inclusion. Uses Hiro /extended/v2/addresses/ and /extended/v1/address/ endpoints.

Tool	Description
stx_query_transactions	Query Stacks transactions for an address with filtering by type and mempool inclusion.
stx_query_transactions_by_contract	Query transactions that called a specific contract, optionally filtered by function name.

Parameters (stx_query_transactions): optional address, limit, offset, tx_type (token_transfer, contract_call, smart_contract, coinbase, poison_microblock), unanchored (include mempool).
Parameters (stx_query_transactions_by_contract): contract_id (required), optional function_name, limit, offset.

Example response (stx_query_transactions): { "success": true, "address": "SP...", "transactions": [{ "txid": "0x...", "tx_type": "token_transfer", "status": "success", "block_height": 150000 }], "total": 42, "tx_type_filter": null, "unanchored": false }

---

Mempool operations

Monitor pending Stacks transactions, view mempool statistics, and track dropped transactions. Uses Hiro /extended/v1/tx/mempool/ endpoints.

Tool	Description
stx_mempool_list_pending	List pending mempool transactions, optionally filtered by address.
stx_mempool_get_stats	Get mempool statistics: transaction counts by type, fee averages, ages, byte sizes.
stx_mempool_get_dropped	Get recently dropped mempool transactions (removed without being mined).

Parameters (stx_mempool_list_pending): optional address, limit, offset.
Parameters (stx_mempool_get_dropped): optional limit, offset.

Example response (stx_mempool_get_stats): { "success": true, "tx_type_counts": { "token_transfer": 42, "contract_call": 18 }, "tx_simple_fee_averages": { "token_transfer": { "p50": 200 } } }

---

Block explorer

Query Stacks blocks by height, hash, or Bitcoin block association. Uses Hiro /extended/v2/blocks/ and /extended/v2/burn-blocks/ endpoints.

Tool	Description
stx_get_recent_blocks	Get recent Stacks blocks with metadata (height, hash, tx count, burn block info).
stx_get_block_by_height	Get a specific Stacks block by its height, including transaction IDs.
stx_get_block_by_hash	Get a specific Stacks block by its hash.
stx_get_stacks_blocks_for_bitcoin_block	Get all Stacks blocks produced during a specific Bitcoin block.

Parameters (stx_get_recent_blocks): optional limit, offset.
Parameters (stx_get_block_by_height): height (required).
Parameters (stx_get_block_by_hash): block_hash (required, with or without 0x prefix).
Parameters (stx_get_stacks_blocks_for_bitcoin_block): bitcoin_height (required), optional limit, offset.

Example response (stx_get_block_by_height): { "success": true, "height": 150000, "hash": "0x...", "burn_block_height": 935748, "tx_count": 12, "transaction_ids": ["0x..."] }

---

Contract event monitoring

Track events emitted by smart contracts and asset transfers for addresses. Uses Hiro /extended/v1/contract/ and /extended/v1/address/ endpoints.

Tool	Description
stx_get_contract_events	Get event history for a contract (print events, FT/NFT events, STX events).
stx_get_address_asset_events	Get asset events (FT, NFT, STX transfers) for an address.

Parameters (stx_get_contract_events): contract_id (required), optional limit, offset.
Parameters (stx_get_address_asset_events): optional address (default: wallet), limit, offset.

Example response (stx_get_contract_events): { "success": true, "contract_id": "SP...contract", "events": [{ "event_type": "fungible_token_asset", "tx_id": "0x...", "asset_id": "SP...::token", "amount": "1000" }], "total": 5 }

---

Token metadata

Query SIP-10 fungible and SIP-9 non-fungible token metadata and holder information. Uses Hiro Token Metadata API (/metadata/v1/).

Tool	Description
stx_get_token_metadata	Get metadata for a fungible (SIP-10) or non-fungible (SIP-9) token: name, symbol, decimals, supply.
stx_get_token_holders	Get holder addresses and balances for a fungible token.

Parameters (stx_get_token_metadata): contract_id (required), optional token_type (ft or nft, default: ft).
Parameters (stx_get_token_holders): contract_id (required), optional limit, offset.

Example response (stx_get_token_metadata): { "success": true, "contract_id": "SP...::alex-token", "name": "Alex Token", "symbol": "ALEX", "decimals": 8, "total_supply": "1000000000000" }

---

Network statistics & health

Query Stacks network status, peer info, and chain tip details. Uses Hiro /v2/info and /extended/v1/status endpoints.

Tool	Description
stx_get_network_info	Core network info: peer version, burn block height, server version, chain tip.
stx_get_network_status	Blockchain sync status and chain tip details.

Parameters: None.

Example response (stx_get_network_info): { "success": true, "peer_version": 402653189, "burn_block_height": 935748, "stacks_tip_height": 150000, "server_version": "stacks-node 2.5.0" }

---

Security

• Secrets: MUST NOT be returned in tool responses (keys, mnemonics, passphrases).
• Destructive ops: Send, sign-and-broadcast, and deploy tools support dry_run. Keep BTC_DRY_RUN=true unless you intend to broadcast. Require explicit confirmation before dry_run=false.
• Preview first: Use preview/estimate tools before sending (e.g. btc_wallet_preview_transfer, btc_estimate_fee, stx_preview_transfer).
• Limits: Optional BTC_MAX_SEND_BTC and BTC_MAX_FEE_SATS cap amount and fees.
• Env: Keep .env out of version control and restrict permissions. Run script loads it from repo root.

---

Testing

Unit tests live under tests/unit/ and target MCP server behavior and wallet modules:

# From mcp/btc_wallet (this directory) or repo root
python -m pytest mcp/btc_wallet/tests/unit -v

Test modules include: test_bitcoin_wallet_mcp_server.py, test_stx_wallet_mcp_server.py, test_ord_wallet_mcp_server.py, test_defi_wallet_mcp_server.py, test_phase5ab_mcp_server.py, test_phase5d_mcp_server.py, test_ledger_wallet_mcp_server.py, test_hiro_integration_mcp_server.py. Ledger tests require a device or Speculos.

---

Troubleshooting

Issue	What to check
Server fails to start	Python 3.10+, pip install -r requirements.txt, and correct PATH.
"Missing key" or "No mnemonic"	Set exactly one of BTC_PRIVATE_KEY or BTC_MNEMONIC in .env (and ensure the run script loads it from repo root).
Wrong network	Set BTC_NETWORK=mainnet or testnet; some tools also accept an explicit network argument.
Transfers not broadcasting	Confirm BTC_DRY_RUN and/or the tool’s dry_run are false when you intend to broadcast.
Ledger "No device"	Device connected, Bitcoin/Stacks app open, no other app holding the device; try interface: "tcp" with Speculos for dev.
Fee or balance errors	Check mempool.space (or configured API) is reachable; for Stacks, check Hiro API and network.
Import errors	Run from repo root or from mcp/btc_wallet so that bitcoin_wallet, stx_wallet, etc. are importable; or install the package if you use a package layout.

---

Reference

• MCP: Model Context Protocol. Protocol and tool contract used by this server.
• Foundation: markmhendrickson/foundation. Shared development processes and documentation conventions. After cloning, run git submodule update --init foundation if the foundation/ directory is empty.