Route402 Python SDK

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

Installation

pip install route402

Quick Start

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

from route402 import Route402Client

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

Create Payment

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

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

# 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

# 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

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

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

@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

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

Chain

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