mintbot 0.1.0

Python SDK for Mintbot — Lightning-native payments for AI agents

mintbot

Lightning-native payments for AI agents. Powered by Mintbot.

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

pip install mintbot

Requires Python 3.10+.

---

Quick Start

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.

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.

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

---

wallet.balance (property)

Live balance in satoshis.

sats = wallet.balance  # int

wallet.get_balance_info()

Full balance info with metadata.

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.

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.

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).

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

For explicit pre-flight balance checking:

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.

result = wallet.pay_address(
    lightning_address="[e-mail]",
    amount=100,
    memo="coffee",
)
print(result.status)   # "completed"
print(result.fee_sats) # routing fee

---

wallet.withdraw(amount)

Withdraw funds as a portable Cashu token.

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

For full result metadata:

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.

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:

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).

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

---

Error Handling

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

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