bitpilot Toolkit

Bitcoin-only wallet & mempool SDK for agents and humans.

bitpilot Toolkit is a Python SDK that gives developers and AI agents a clean, safe interface to Bitcoin. Non-custodial wallets, real-time mempool data, configurable spend policies, first-class Lightning support, and L402 auto-pay HTTP clients for pay-per-request APIs.

Website: bitpilot.xyz

---

Why bitpilot Toolkit?

	bitpilot Toolkit	BDK (Rust)	Coinbase AgentKit	bitcoinjs-lib
Language	Python-first	Rust (Python bindings exist)	Python/JS	JavaScript
Focus	Bitcoin L1 + AI agents	Bitcoin L1 primitives	EVM/Solana + USDC	Bitcoin L1
Agent-ready	First-class tools	Not agent-oriented	Yes, but not Bitcoin L1	No
Policy engine	Built-in spend caps, whitelists, approval flows	N/A	MPC-based	N/A
Safety model	Propose → Approve (never auto-spend)	Manual	API-key-gated	Manual
L402 support	Native L402Client with automatic 402 invoice payment	No	No	No
Supply chain	Zero npm. Audited Rust crypto under the hood	Rust-native	Mixed	npm ecosystem

---

Install

pip install bitpilot

With agent framework support:

pip install bitpilot[agent]

With L402 auto-payment client support:

pip install bitpilot[l402]

---

Quick Start

⚠ Mainnet status: Wallet operations on mainnet are supported but undertested. Start on testnet. Always back up your mnemonic. The authors are not liable for lost funds.

Wallet Operations

import os
from bitpilot import Wallet, Policy, Watcher

# Create a new wallet (or load existing)
wallet, mnemonic = Wallet.create(network="testnet")
print(f"Save this mnemonic: {mnemonic}")

# Or load from existing mnemonic
wallet = Wallet.from_mnemonic(
    mnemonic=os.environ["BITPILOT_MNEMONIC"],
    network="testnet",
)

# Check balance
balance = wallet.get_balance()
print(f"Balance: {balance.confirmed_sats} sats")

# Set a spend policy
policy = Policy(
    max_per_tx_sats=100_000,
    max_per_day_sats=500_000,
    require_approval_above_sats=50_000,
    allowed_addresses=["tb1q..."],
)
wallet.set_policy(policy)

Mempool Monitoring

from bitpilot import Watcher

watcher = Watcher.from_default_providers(network="mainnet")

# Get fee estimates
fee = await watcher.estimate_fee(target_blocks=3)
print(f"Recommended fee: {fee.sat_per_vb} sat/vB ({fee.estimated_minutes} min)")

# Get mempool state
state = await watcher.get_mempool_state()
print(f"Mempool: {state.tx_count} txs, {state.congestion_level} congestion")

# Human-readable summary (great for LLMs)
summary = await watcher.explain_mempool()
print(summary)

AI Agent Integration

from bitpilot import Wallet, Watcher
from bitpilot.agent import make_openai_tools

wallet = Wallet.from_mnemonic(os.environ["BITPILOT_MNEMONIC"], network="testnet")
watcher = Watcher.from_default_providers(network="testnet")

# Get tools ready for OpenAI Agents SDK
tools = make_openai_tools(wallet, watcher)

# Tools include: get_balance, get_utxos, estimate_fee,
# propose_payment, list_proposals
# Note: no approve/reject tools — agents can't auto-spend

L402 Auto-Pay HTTP Client

from bitpilot.lightning import LightningWallet, L402Client

lightning_wallet = LightningWallet.from_lnd(
    macaroon_path="~/.lnd/data/chain/bitcoin/mainnet/admin.macaroon",
    tls_cert_path="~/.lnd/tls.cert",
    host="localhost:10009",
)

async with L402Client(lightning_wallet) as client:
    response = await client.get("https://api.example.com/data")
    response.raise_for_status()
    print(response.json())

L402Client flow:

• Sends your request normally.
• On HTTP 402, extracts the Lightning invoice challenge.
• Pays the invoice with your Lightning wallet.
• Retries once with proof-of-payment headers.

By default, auto-pay retry is limited to idempotent methods (GET, HEAD, OPTIONS) for safety.

Propose → Approve Flow

# Agent or code proposes a payment
proposal = wallet.propose_payment(
    to_address="tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx",
    amount_sats=75_000,
    fee_rate_sat_vb=fee.sat_per_vb,
    memo="Test payment",
)

print(f"Proposal {proposal.id}: {proposal.policy_decision}")
# → "require_approval" (above 50k threshold)

# Human approves (never the agent)
txid = wallet.approve_proposal(proposal.id)
print(f"Broadcast: {txid}")

---

CLI

bitpilot init-wallet              # Generate new HD wallet
bitpilot balance                  # Show balance
bitpilot utxos                    # List UTXOs
bitpilot fees                     # Fee estimates (fast/med/slow)
bitpilot mempool                  # Mempool summary
bitpilot propose --to <addr> --amount-sats 50000
bitpilot approve --proposal-id <id>

---

Security

bitpilot Toolkit is designed with security as the default:

• Non-custodial — keys never leave your machine
• Proposal-based spending — agents propose, humans approve
• Encrypted key storage — AES-256-GCM with Argon2id KDF
• Policy enforcement — per-tx caps, daily limits, address whitelists
• Zero npm — no JavaScript supply chain risk for crypto operations
• Audited primitives — Rust-grade Bitcoin crypto via BDK bindings

See SECURITY.md for vulnerability reporting and full threat model.

---

Documentation

• Architecture — system design, data flows, technology choices
• Examples — runnable scripts for wallet, watcher, and agent usage
• Contributing — how to contribute
• Security — security policy and vulnerability disclosure

---

License

MIT — see LICENSE.