paykit 0.1.0

Payment SDK for Autonomous AI Agents

PayKit

Vendor-Agnostic Payment SDK for Autonomous AI Agents

PayKit provides a unified payment infrastructure for AI agents. One SDK to handle wallets, transfers, spending controls, and cross-chain payments across multiple providers.

Why PayKit?

Challenge	Solution
AI agents need to spend money	Programmatic USDC wallets with no private keys to manage
Agents can hallucinate or overspend	Safety guards with atomic enforcement
Different payment protocols exist	Universal routing (direct, x402, cross-chain)
Vendor lock-in	Provider abstraction (Circle, Coinbase, more)
No visibility into agent spending	Built-in ledger and transaction history

Installation

pip install paykit

With Coinbase support:

pip install paykit[coinbase]

Quick Start

import asyncio
from decimal import Decimal
from paykit import PayKit

async def main():
    # Initialize (reads CIRCLE_API_KEY from environment)
    client = PayKit()
    
    # Create a wallet for your agent
    wallet_set, wallet = await client.create_agent_wallet(agent_name="my-agent")
    print(f"Wallet: {wallet.address}")
    
    # Add spending limits (safety first!)
    await client.add_budget_guard(wallet.id, daily_limit=Decimal("100.00"))
    
    # Make a payment
    result = await client.pay(
        wallet_id=wallet.id,
        recipient="0x742d35Cc6634C0532925a3b844Bc9e7595f5e4a0",
        amount=Decimal("10.00")
    )
    print(f"Payment: {result.status}")

asyncio.run(main())

Core Features

Wallet Management

Create and manage USDC wallets programmatically. No seed phrases or private keys.

# Create wallets for agents
wallet_set, wallet = await client.create_agent_wallet(agent_name="trading-bot")

# Check balance
balance = await client.get_balance(wallet.id)

# List all wallets
wallets = client.wallet.list_wallets()

Safety Guards

Protect against runaway spending with atomic enforcement:

# Budget limits
await client.add_budget_guard(
    wallet.id,
    daily_limit=Decimal("100.00"),
    hourly_limit=Decimal("25.00"),
    total_limit=Decimal("1000.00")
)

# Rate limits (prevent infinite loops)
await client.add_rate_limit_guard(wallet.id, max_per_minute=5, max_per_hour=20)

# Transaction size limits
await client.add_single_tx_guard(wallet.id, max_amount=Decimal("50.00"))

# Recipient whitelist
await client.add_recipient_guard(
    wallet.id,
    mode="whitelist",
    domains=["api.openai.com", "api.anthropic.com"]
)

# Human approval for large payments
await client.add_confirm_guard(wallet.id, threshold=Decimal("500.00"))

Guard	Purpose
BudgetGuard	Spending limits (daily/hourly/total)
RateLimitGuard	Transaction frequency limits
SingleTxGuard	Per-transaction min/max amounts
RecipientGuard	Whitelist or blacklist recipients
ConfirmGuard	Human-in-the-loop approval

Universal Payment Routing

One pay() method handles all payment types:

# Direct USDC transfer (blockchain address)
await client.pay(wallet_id=w, recipient="0x...", amount=Decimal("10.00"))

# x402 API payment (HTTP URL)
await client.pay(wallet_id=w, recipient="https://api.example.com/data", amount=Decimal("0.10"))

# Cross-chain transfer (CCTP)
from paykit import Network
await client.pay(
    wallet_id=w,
    recipient="0x...",
    amount=Decimal("50.00"),
    destination_chain=Network.BASE
)

Payment Intents

Authorize now, execute later:

# Create authorization
intent = await client.create_payment_intent(
    wallet_id=wallet.id,
    recipient="0x...",
    amount=Decimal("500.00")
)

# Confirm when ready
result = await client.confirm_payment_intent(intent.id)

# Or cancel
await client.cancel_payment_intent(intent.id)

Batch Payments

Execute multiple payments concurrently:

from paykit import PaymentRequest

results = await client.batch_pay([
    PaymentRequest(wallet_id=w, recipient="0xA...", amount=Decimal("10.00")),
    PaymentRequest(wallet_id=w, recipient="0xB...", amount=Decimal("20.00")),
    PaymentRequest(wallet_id=w, recipient="0xC...", amount=Decimal("30.00")),
], concurrency=10)

print(f"Success: {results.success_count}, Failed: {results.failed_count}")

Transaction Ledger

Complete observability:

# Get transaction history
history = await client.ledger.get_history(wallet_id=wallet.id)

# Get total spent
total = await client.ledger.get_total_spent(wallet_id=wallet.id)

# Sync with blockchain
await client.sync_transaction(entry_id="...")

Multi-Provider Architecture

PayKit abstracts wallet providers. Switch providers without code changes.

Supported Providers

Provider	Status	Install	Features
Circle	Stable	Default	CCTP, gasless transfers
Coinbase	Beta	pip install paykit[coinbase]	EVM + Solana

Provider Configuration

Circle (Default):

from paykit import PayKit
from paykit.providers import CircleProvider, CircleConfig

provider = CircleProvider(CircleConfig(
    api_key="your-circle-api-key",
    entity_secret="your-entity-secret",  # Auto-generated if not provided
))
client = PayKit(provider=provider)

Coinbase:

from paykit.providers import CoinbaseProvider, CoinbaseConfig

provider = CoinbaseProvider(CoinbaseConfig(
    api_key="your-cdp-api-key-id",
    api_secret="your-cdp-api-key-secret",
    wallet_secret="your-wallet-secret",
))
client = PayKit(provider=provider)

Environment Variables:

# Circle
export CIRCLE_API_KEY="..."
export ENTITY_SECRET="..."  # Optional, auto-generated

# Coinbase
export CDP_API_KEY_ID="..."
export CDP_API_KEY_SECRET="..."
export CDP_WALLET_SECRET="..."

# Provider selection
export PAYKIT_PROVIDER="circle"  # or "coinbase"

Direct Provider Access

from paykit.providers import get_provider, ProviderType

# Get provider
provider = get_provider(ProviderType.CIRCLE)

# Direct operations
wallet = await provider.create_wallet(wallet_set_id, "ETH-SEPOLIA")
balances = await provider.get_balances(wallet.id)
result = await provider.transfer(wallet.id, "0x...", Decimal("10.00"))

Configuration

Environment Variables

Variable	Required	Description	Default
CIRCLE_API_KEY	Yes*	Circle API key	-
ENTITY_SECRET	No	Circle entity secret	Auto-generated
PAYKIT_PROVIDER	No	Provider: circle, coinbase	circle
PAYKIT_NETWORK	No	Default network	ARC-TESTNET
PAYKIT_STORAGE_BACKEND	No	Storage: memory, redis	memory
PAYKIT_REDIS_URL	No	Redis connection URL	redis://localhost:6379
PAYKIT_LOG_LEVEL	No	Logging level	INFO

Supported Networks

Testnets:

• ARC-TESTNET (Circle Arc - recommended for testing)
• ETH-SEPOLIA, BASE-SEPOLIA, ARB-SEPOLIA
• MATIC-AMOY, AVAX-FUJI
• SOL-DEVNET

Mainnets:

• ETH, BASE, ARB, MATIC, AVAX, SOL

Error Handling

from paykit import (
    PayKitError,      # Base exception
    GuardError,         # Blocked by safety guard
    InsufficientBalanceError,
    WalletError,
    PaymentError,
    ConfigurationError,
)

try:
    result = await client.pay(wallet_id=w, recipient="0x...", amount=Decimal("1000.00"))
except GuardError as e:
    print(f"Blocked: {e}")  # Budget exceeded, rate limited, etc.
except InsufficientBalanceError as e:
    print(f"Low balance: {e}")
except PayKitError as e:
    print(f"Payment failed: {e}")

Examples

See the examples/ directory:

• basic_payment.py - Simple payment flow
• using_guards.py - Safety guard configuration
• gemini_agent.py - Google Gemini integration
• x402_client_demo.py - x402 protocol usage
• ledger_tracking.py - Transaction observability

Documentation

Document	Description
Quickstart	Get started in 5 minutes
API Reference	Complete API documentation
SDK Usage Guide	Detailed usage patterns
CCTP Usage	Cross-chain transfer guide
Gas Requirements	Network gas information
Architecture	Design philosophy

Development

# Clone repository
git clone https://github.com/paykit/paykit.git
cd paykit

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run tests with coverage
pytest --cov=src/paykit

# Type checking
mypy src/paykit

# Linting
ruff check src/paykit
ruff format src/paykit

Project Structure

src/paykit/
├── client.py           # Main PayKit client
├── providers/          # Wallet provider implementations
│   ├── base.py         # Abstract provider interface
│   ├── circle.py       # Circle implementation
│   └── coinbase.py     # Coinbase implementation
├── guards/             # Safety guard system
├── protocols/          # Payment protocol adapters
├── ledger/             # Transaction history
├── storage/            # Persistence backends
└── webhooks/           # Event handling

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

MIT License - see LICENSE for details.

Links

• PyPI Package
• GitHub Repository
• Documentation
• Circle Developer Docs
• Coinbase CDP Docs