# Tab Payments SDK

Python SDK for [Tab](https://usetab.dev) - Micropayments for AI Agents.

## Installation

```bash
pip install tab-payments
```

## Quick Start

```python
from tab_payments import TabClient

# Initialize with your API key
client = TabClient(api_key="tab_live_xxx")

# Check your balance
balance = client.balance()
print(f"Balance: {balance['balance_formatted']}")

# Pay another agent
payment = client.pay(
    to="agent_abc123",
    amount_microcents=5_000_000,  # $0.05
    memo="Tool usage fee"
)
print(f"Payment token: {payment['payment_token']}")

# Verify a payment (as a tool provider)
result = client.verify(payment_token="tab_pay_xxx")
if result['valid']:
    print(f"Payment verified from {result['from_agent']}")
```

## Async Usage

```python
from tab_payments import AsyncTabClient

async with AsyncTabClient(api_key="tab_live_xxx") as client:
    balance = await client.balance()
    print(f"Balance: {balance['balance_formatted']}")
```

## Understanding Microcents

Tab uses microcents for sub-cent precision:
- 1 cent = 1,000,000 microcents
- $1.00 = 100,000,000 microcents
- $0.001 = 1,000 microcents

## Error Handling

```python
from tab_payments import (
    TabClient,
    TabError,
    InsufficientBalanceError,
    InvalidPaymentError,
    AuthenticationError,
)

client = TabClient(api_key="tab_live_xxx")

try:
    payment = client.pay(to="agent_xxx", amount_microcents=1_000_000)
except InsufficientBalanceError:
    print("Not enough balance!")
except InvalidPaymentError:
    print("Invalid payment parameters")
except AuthenticationError:
    print("Invalid API key")
except TabError as e:
    print(f"Tab error: {e.message}")
```

## API Reference

### TabClient

#### `balance() -> dict`
Returns your current balance.

Response:
```python
{
    "agent_id": "agent_xxx",
    "balance_microcents": 100000000,
    "balance_formatted": "$1.00"
}
```

#### `pay(to: str, amount_microcents: int, memo: str = None) -> dict`
Transfer microcents to another agent.

Response:
```python
{
    "id": "txn_xxx",
    "payment_token": "tab_pay_xxx",
    "amount_microcents": 5000000,
    "balance_after_microcents": 95000000
}
```

#### `verify(payment_token: str, expected_amount_microcents: int = None) -> dict`
Verify a payment token (for tool providers).

Response:
```python
{
    "valid": True,
    "from_agent": "agent_xxx",
    "amount_microcents": 5000000
}
```

## License

MIT
