Metadata-Version: 2.4
Name: bitpilot
Version: 0.3.1
Summary: Bitcoin-only wallet & mempool SDK for agents and humans.
Project-URL: Homepage, https://github.com/bitpilot/bitpilot
Project-URL: Repository, https://github.com/bitpilot/bitpilot
Project-URL: Issues, https://github.com/bitpilot/bitpilot/issues
Project-URL: Security, https://github.com/bitpilot/bitpilot/security/policy
Project-URL: Releases, https://github.com/bitpilot/bitpilot/releases
Project-URL: Documentation, https://docs.bitpilot.io
Author: bitpilot
License: MIT
License-File: LICENSE
Keywords: agent,bip32,bip39,bitcoin,l402,lightning,mempool,sdk,wallet
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: bitcoinlib>=0.7
Requires-Dist: click>=8.0
Requires-Dist: cryptography>=41.0
Requires-Dist: httpx>=0.25
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: agent
Requires-Dist: langchain-core>=0.1; extra == 'agent'
Requires-Dist: langchain>=0.1; extra == 'agent'
Requires-Dist: mcp>=0.1; extra == 'agent'
Requires-Dist: openai>=1.0; extra == 'agent'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.0; extra == 'dev'
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: l402
Requires-Dist: httpx>=0.25; extra == 'l402'
Provides-Extra: lightning
Requires-Dist: grpcio>=1.60; extra == 'lightning'
Requires-Dist: httpx>=0.25; extra == 'lightning'
Description-Content-Type: text/markdown

# bitpilot Toolkit

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/bitpilot.svg)](https://pypi.org/project/bitpilot/)
[![Tests](https://github.com/nikhildd32/neetbtc-toolkit/actions/workflows/test.yml/badge.svg)](https://github.com/nikhildd32/neetbtc-toolkit/actions/workflows/test.yml)

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](https://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

```bash
pip install bitpilot
```

With agent framework support:

```bash
pip install bitpilot[agent]
```

With L402 auto-payment client support:

```bash
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

```python
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

```python
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

```python
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

```python
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

```python
# 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

```bash
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](./SECURITY.md) for vulnerability reporting and full threat model.

---

## Documentation

- [Architecture](./ARCHITECTURE.md) — system design, data flows, technology choices
- [Examples](./examples/) — runnable scripts for wallet, watcher, and agent usage
- [Contributing](./CONTRIBUTING.md) — how to contribute
- [Security](./SECURITY.md) — security policy and vulnerability disclosure

---

## License

MIT — see [LICENSE](./LICENSE).
