Metadata-Version: 2.4
Name: mintbot
Version: 0.1.0
Summary: Python SDK for Mintbot — Lightning-native payments for AI agents
Author-email: Mintbot <dev@mintbot.cash>
License: MIT
Project-URL: Homepage, https://mintbot.cash
Project-URL: Documentation, https://mintbot.cash/docs
Project-URL: Repository, https://github.com/mintbot/mintbot-python
Project-URL: Issues, https://github.com/mintbot/mintbot-python/issues
Keywords: lightning,bitcoin,cashu,ai,agents,payments,mintbot
Classifier: Development Status :: 4 - Beta
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 :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# mintbot

> Lightning-native payments for AI agents. Powered by [Mintbot](https://mintbot.cash).

`mintbot` is a Python SDK for the Mintbot Agent Pay API — a zero-setup payment layer for AI agents using Bitcoin Lightning and Cashu.

---

## Installation

```bash
pip install mintbot
```

Requires Python 3.10+.

---

## Quick Start

```python
from mintbot import AgentWallet

# 1. Create a new wallet (one-time setup)
wallet = AgentWallet.create(agent_name="my-bot")
print(wallet.api_key)  # vf_live_... — SAVE THIS, shown only once!

# 2. Load an existing wallet
wallet = AgentWallet(api_key="vf_live_...")

# 3. Check balance
print(wallet.balance)  # 950 (satoshis)
```

---

## API Reference

### `AgentWallet.create()`

Create a new agent wallet. Returns an authenticated `AgentWallet` instance.

```python
wallet = AgentWallet.create(
    agent_name="translator-bot",   # optional label
    budget_sats=10_000,            # optional spending cap
    base_url="https://api.visionfusen.org",
)
print(wallet.api_key)   # vf_live_... — store securely!
print(wallet._wallet_info.wallet_id)  # w_abc123
```

---

### `AgentWallet(api_key=...)`

Load an existing wallet by API key.

```python
wallet = AgentWallet(api_key="vf_live_...", base_url="https://api.visionfusen.org")
```

---

### `wallet.balance` (property)

Live balance in satoshis.

```python
sats = wallet.balance  # int
```

### `wallet.get_balance_info()`

Full balance info with metadata.

```python
info = wallet.get_balance_info()
print(info.balance_sats)       # 950
print(info.agent_name)         # "my-bot"
print(info.budget_limit_sats)  # None or int
print(info.last_active)        # datetime
```

---

### `wallet.create_invoice(amount)`

Create a Lightning invoice to fund the wallet.

```python
invoice = wallet.create_invoice(amount=1000)  # satoshis
print(invoice.bolt11)    # lnbc1000n1...
print(invoice.quote_id)  # for status polling
print(invoice.status)    # "UNPAID"
```

Balance credits automatically when the invoice is paid.

---

### `wallet.pay(to_wallet, amount, memo=None)`

Internal payment — instant, zero fee, wallet-to-wallet.

```python
result = wallet.pay(
    to_wallet="w_xyz789",
    amount=50,
    memo="translation service",
)
print(result.status)          # "completed"
print(result.new_balance_sats)  # updated balance
```

---

### `wallet.pay_invoice(bolt11, memo=None)`

Pay a BOLT11 Lightning invoice (external payment via Cashu melt).

```python
result = wallet.pay_invoice("lnbc500n1...")
print(result.amount_sats)  # 500
print(result.fee_sats)     # actual routing fee
```

For explicit pre-flight balance checking:

```python
result = wallet.pay_invoice_amount("lnbc500n1...", amount=500)
```

---

### `wallet.pay_address(lightning_address, amount, memo=None)`

Pay a Lightning address — resolved server-side via LNURL-pay.

```python
result = wallet.pay_address(
    lightning_address="user@getalby.com",
    amount=100,
    memo="coffee",
)
print(result.status)   # "completed"
print(result.fee_sats) # routing fee
```

---

### `wallet.withdraw(amount)`

Withdraw funds as a portable Cashu token.

```python
token = wallet.withdraw(amount=200)
print(token)  # cashuAeyJ... — redeemable at the mint
```

For full result metadata:

```python
result = wallet.withdraw_full(amount=200)
print(result.token)
print(result.new_balance_sats)
print(result.tx_id)
```

---

### `wallet.transactions(limit=20, offset=0, tx_type=None)`

Fetch transaction history.

```python
txs = wallet.transactions(limit=10)
for tx in txs:
    print(f"{tx.tx_type}: {tx.amount_sats} sats [{tx.direction}] - {tx.status}")

# Filter by type
txs = wallet.transactions(tx_type="lightning_out")
```

Transaction types: `internal`, `lightning_in`, `lightning_out`, `withdraw`, `mint`

For pagination metadata:

```python
result = wallet.get_transactions(limit=5, offset=10)
print(f"Page {result.offset // result.limit + 1} of {result.total // result.limit + 1}")
```

---

### `AgentWallet.health()`

Check API health (no auth required).

```python
info = AgentWallet.health()
print(info.status)    # "ok"
print(info.version)   # "2.0.0"
print(info.features)  # ["internal-pay", "lightning-in", ...]
```

---

## Error Handling

```python
from mintbot import (
    MintbotError,          # base class
    AuthenticationError,   # invalid API key (401)
    InsufficientBalance,   # not enough funds (402)
    WalletNotFound,        # wallet ID not found (404)
    PaymentError,          # payment failure
    InvoiceError,          # invoice creation failed
    WithdrawalError,       # withdrawal failed
    APIError,              # generic API error
)

try:
    wallet.pay(to_wallet="w_abc", amount=1000)
except InsufficientBalance as e:
    print(f"Need {e.shortfall_sats} more sats (have {e.balance_sats})")
except WalletNotFound as e:
    print(f"Wallet not found: {e.message}")
except MintbotError as e:
    print(f"API error {e.status_code}: {e.message}")
    if e.detail:
        print(f"Detail: {e.detail}")
```

---

## Context Manager

```python
with AgentWallet(api_key="vf_live_...") as wallet:
    print(wallet.balance)
# HTTP client closed automatically
```

---

## Models

| Class | Fields |
|-------|--------|
| `BalanceInfo` | `wallet_id`, `agent_name`, `balance_sats`, `budget_limit_sats`, `created_at`, `last_active` |
| `Invoice` | `bolt11`, `quote_id`, `amount_sats`, `status`, `method`, `wallet_id`, `note` |
| `PaymentResult` | `tx_id`, `amount_sats`, `fee_sats`, `tx_type`, `status`, `new_balance_sats`, `memo`, `created_at` |
| `WithdrawalResult` | `token`, `amount_sats`, `tx_id`, `new_balance_sats`, `wallet_id`, `created_at` |
| `Transaction` | `id`, `direction`, `amount_sats`, `fee_sats`, `tx_type`, `status`, `memo`, `created_at` |
| `HealthInfo` | `status`, `service`, `version`, `timestamp`, `features` |

---

## Links

- **Website:** https://mintbot.cash
- **API base URL:** https://api.visionfusen.org

---

## License

MIT
