# Route402 Python SDK

Python SDK for Route402 - USDC payment infrastructure for AI agents on Base blockchain.

## Installation

```bash
pip install route402
```

## Quick Start

```python
from route402 import Route402Client

# Initialize client
client = Route402Client(api_key="apk_your_key_here")

# Create payment
payment = client.create_payment(
    seller="0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    amount="0.05",  # 0.05 USDC
    reference="order-123"
)

print(f"Payment ID: {payment.id}")
print(f"Status: {payment.status}")
print(f"Amount: {payment.amount} USDC")
print(f"Fee: {payment.fee_amount} USDC")
print(f"Net: {payment.net_amount} USDC")
```

## Features

- ✅ Create and manage USDC payments
- ✅ Check payment status
- ✅ Export transactions as CSV (for accounting)
- ✅ Type-safe with dataclasses
- ✅ Built-in error handling
- ✅ Supports Base mainnet

## Usage

### Initialize Client

```python
from route402 import Route402Client

client = Route402Client(
    api_key="apk_your_key_here",
    api_url="https://api.route402.com"  # Optional, uses default
)
```

### Create Payment

```python
payment = client.create_payment(
    seller="0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    amount="0.10",
    chain_id=8453,  # Base mainnet (default)
    reference="invoice-456"  # Optional
)

# Check status
if payment.is_confirmed:
    print("Payment confirmed!")
```

### Get Payment Status

```python
payment = client.get_payment("pay_abc123")

print(f"Status: {payment.status}")
print(f"Confirmed: {payment.is_confirmed}")
print(f"TX Hash: {payment.tx_hash}")
```

### List Payments

```python
# Get all payments
payments = client.list_payments(limit=10)

# Filter by status
from route402 import PaymentStatus

confirmed = client.list_payments(
    status=PaymentStatus.CONFIRMED,
    limit=100
)

for payment in confirmed:
    print(f"{payment.id}: {payment.amount} USDC")
```

### Export CSV for Accounting

```python
# Export all payments
csv_data = client.export_payments_csv()

# Export with filters
csv_data = client.export_payments_csv(
    start_date="2025-01-01",
    end_date="2025-12-31",
    status=PaymentStatus.CONFIRMED
)

# Save to file
with open("transactions.csv", "w") as f:
    f.write(csv_data)
```

### Check Supported Chains

```python
chains = client.get_chains()

for chain in chains:
    print(f"{chain['name']} (ID: {chain['chainId']})")
    print(f"Router: {chain['router']}")
    print(f"USDC: {chain['usdc']}")
```

## Error Handling

```python
from route402 import Route402Client, APIError, PaymentError, ValidationError

client = Route402Client(api_key="apk_xxx")

try:
    payment = client.create_payment(
        seller="0x123...",
        amount="0.05"
    )
except ValidationError as e:
    print(f"Invalid input: {e}")
except APIError as e:
    print(f"API error ({e.status_code}): {e.message}")
except PaymentError as e:
    print(f"Payment failed: {e}")
```

## Types

### Payment

```python
@dataclass
class Payment:
    id: str
    chain_id: int
    buyer: str
    seller: str
    amount: str
    fee_bps: int
    tx_hash: Optional[str]
    status: PaymentStatus
    reference: Optional[str]
    created_at: datetime
    confirmed_at: Optional[datetime]

    # Computed properties
    @property
    def fee_amount(self) -> float:
        """Fee amount in USDC"""

    @property
    def net_amount(self) -> float:
        """Net amount after fee"""

    @property
    def is_confirmed(self) -> bool:
        """Is payment confirmed"""

    @property
    def is_pending(self) -> bool:
        """Is payment pending"""
```

### PaymentStatus

```python
class PaymentStatus(str, Enum):
    PENDING = "PENDING"
    BROADCASTED = "BROADCASTED"
    MINED = "MINED"
    CONFIRMED = "CONFIRMED"
    FAILED = "FAILED"
```

### Chain

```python
class Chain(int, Enum):
    BASE = 8453
    POLYGON_AMOY = 80002  # Testnet
```

## Requirements

- Python 3.8+
- `requests>=2.31.0`
- `eth-account>=0.10.0`
- `web3>=6.0.0`

## Links

- **Website:** https://route402.com
- **Documentation:** https://docs.route402.com
- **API Reference:** https://docs.route402.com/api
- **GitHub:** https://github.com/route402/route402
- **Support:** hello@route402.com

## License

MIT
