mintbot 0.1.0__tar.gz

mintbot-0.1.0/PKG-INFO

@@ -0,0 +1,297 @@
+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

mintbot-0.1.0/README.md

@@ -0,0 +1,269 @@
+# 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

mintbot-0.1.0/mintbot/__init__.py

@@ -0,0 +1,61 @@
+"""
+mintbot — Python SDK for Mintbot Agent Pay.
+
+Quick start::
+
+    from mintbot import AgentWallet
+
+    # Create a new wallet
+    wallet = AgentWallet.create(agent_name="my-bot")
+    print(wallet.api_key)  # mb_live_... — save this!
+
+    # Load existing wallet
+    wallet = AgentWallet(api_key="mb_live_...")
+    print(wallet.balance)  # 950
+
+See https://mintbot.cash for full documentation.
+"""
+from .wallet import AgentWallet
+from .models import (
+    BalanceInfo,
+    HealthInfo,
+    Invoice,
+    PaymentResult,
+    Transaction,
+    TransactionList,
+    WalletInfo,
+    WithdrawalResult,
+)
+from .exceptions import (
+    MintbotError,
+    AuthenticationError,
+    InsufficientBalance,
+    WalletNotFound,
+    PaymentError,
+    InvoiceError,
+    WithdrawalError,
+    APIError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "AgentWallet",
+    # Models
+    "BalanceInfo",
+    "HealthInfo",
+    "Invoice",
+    "PaymentResult",
+    "Transaction",
+    "TransactionList",
+    "WalletInfo",
+    "WithdrawalResult",
+    # Exceptions
+    "MintbotError",
+    "AuthenticationError",
+    "InsufficientBalance",
+    "WalletNotFound",
+    "PaymentError",
+    "InvoiceError",
+    "WithdrawalError",
+    "APIError",
+]

mintbot-0.1.0/mintbot/exceptions.py

@@ -0,0 +1,57 @@
+"""
+mintbot.exceptions — Custom exceptions for the Mintbot SDK.
+"""
+
+
+class MintbotError(Exception):
+    """Base exception for all Mintbot errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, detail: str | None = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.detail = detail
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self.message!r})"
+
+
+class AuthenticationError(MintbotError):
+    """Raised when the API key is invalid or missing."""
+
+
+class InsufficientBalance(MintbotError):
+    """Raised when the wallet does not have enough funds."""
+
+    def __init__(
+        self,
+        message: str,
+        balance_sats: int = 0,
+        required_sats: int = 0,
+        shortfall_sats: int = 0,
+        **kwargs,
+    ):
+        super().__init__(message, **kwargs)
+        self.balance_sats = balance_sats
+        self.required_sats = required_sats
+        self.shortfall_sats = shortfall_sats
+
+
+class WalletNotFound(MintbotError):
+    """Raised when a wallet ID cannot be found."""
+
+
+class PaymentError(MintbotError):
+    """Raised when a payment fails."""
+
+
+class InvoiceError(MintbotError):
+    """Raised when invoice creation or resolution fails."""
+
+
+class WithdrawalError(MintbotError):
+    """Raised when a Cashu token withdrawal fails."""
+
+
+class APIError(MintbotError):
+    """Generic API error for unexpected responses."""