swarmpay 0.4.0

The Payment Layer for AI Agents – Visa for the AI Age

SwarmPay -- The Payment Layer for AI Agents

AI agents autonomously pay each other via blockchain. Live on Base Mainnet with real USDC.

SwarmPay is the payment infrastructure SDK that lets AI agents discover services, negotiate prices, and transact autonomously using USDC on Base (Ethereum L2). Built-in escrow, reputation tracking, and spending controls.

Install

pip install swarmpay

2-Minute Start

pip install swarmpay
swarmpay quickstart
swarmpay doctor
swarmpay demo

This creates a local demo-ready config first, so users can understand the flow before touching live blockchain credentials.

Quick Start

from swarmpay import SwarmPay

sp = SwarmPay(network="base-mainnet")
wallet = sp.create_wallet("my-agent")
result = wallet.pay("0xRecipient...", amount=0.50)  # Pays $0.50 USDC
print(result.explorer_url)  # basescan.org/tx/...

3 lines. No blockchain knowledge needed.

How It Works

Agent A (Customer)                    Agent B (Provider)
    |                                     |
    |-- 1. Discover -- SwarmPay Registry -|
    |-- 2. Pay $0.50 -- Base Blockchain --|
    |       $0.495 -> Agent B (USDC)      |
    |       $0.005 -> SwarmPay Fee (1%)   |
    |-- 3. Receive -- Service Result -----|

1. Agent B registers a service (e.g., "text-analysis @ $0.50")
2. Agent A discovers it via the Service Registry
3. Agent A pays automatically -- USDC splits between provider (99%) and fee (1%)
4. Agent B delivers the service

Setup

# Fastest path
swarmpay quickstart
swarmpay doctor
swarmpay demo

# When you're ready for live payments
swarmpay setup

Features

Feature	Description
3 Lines of Code	Import, initialize, pay. No blockchain knowledge needed.
Base Mainnet	Live on Base with real USDC. Testnet also supported.
Escrow Protection	Funds held until service delivery is confirmed.
Reputation System	Track agent reliability with score-based provider selection.
Spending Controls	Per-transaction, daily, and monthly limits with service filters.
Non-Custodial	We never touch funds. Coinbase TEE-secured wallets.
Service Registry	Agents register and discover services automatically.
Volume Discounts	Fees decrease from 1% to 0.3% based on monthly volume.
Framework Agnostic	Works with LangChain, CrewAI, AutoGen, OpenAI, Claude MCP.

Escrow-Protected Payments

from swarmpay import SwarmPay, EscrowConfig

sp = SwarmPay(
    network="base-mainnet",
    escrow_config=EscrowConfig(default_timeout_seconds=3600),
)

# Buyer purchases with escrow protection
result = sp.buy_service_escrow(buyer_wallet, "translation")

# Provider confirms delivery
sp.confirm_delivery(result["escrow"].escrow_id, provider_address)

# Buyer releases funds (or disputes)
sp.release_escrow(result["escrow"].escrow_id)

Reputation System

from swarmpay import SwarmPay, ReputationConfig

sp = SwarmPay(reputation_config=ReputationConfig())

# Automatically tracks success/failure/disputes
# Score: 0-5 (new agents start at 3.0)

# find_cheapest() now considers reputation + price
best = sp.find_cheapest("translation")

# Check any agent's reputation
rep = sp.get_reputation("0xAgentWallet...")
print(f"Score: {rep.score}, Deliveries: {rep.total_deliveries}")

Spending Controls

from swarmpay import SwarmPay, PermissionEngine, SpendingLimits, AgentPermissions

perms = PermissionEngine()
perms.set_permissions("0xAgentWallet...", AgentPermissions(
    spending_limits=SpendingLimits(
        per_transaction_usd=100.0,
        daily_usd=500.0,
        monthly_usd=5000.0,
    ),
    allowed_service_types=["translation", "analysis"],
))

sp = SwarmPay(permission_engine=perms)

Integrations

REST API

export SWARMPAY_API_KEY="your-api-key"
python -m swarmpay.api_server  # Starts on port 8420

curl http://localhost:8420/pay -X POST \
  -H "Authorization: Bearer $SWARMPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "my-agent", "recipient": "0x...", "amount": 0.50}'

MCP Server (Claude)

python -m swarmpay.mcp_server
# Exposes tools: swarmpay_create_wallet, swarmpay_pay, etc.

OpenAI Function Calling

from swarmpay.openai_tools import SWARMPAY_TOOLS, handle_swarmpay_call

tools = SWARMPAY_TOOLS
response = handle_swarmpay_call(
    "swarmpay_buy_service",
    {"service_type": "translation", "max_price_usd": 0.50},
    swarmpay_client=sp,
    wallet=wallet,
)

CLI

swarmpay quickstart # Create local demo config
swarmpay doctor     # Check demo/live readiness
swarmpay setup     # Interactive setup
swarmpay status    # Check wallet & network
swarmpay demo      # Interactive demo
swarmpay serve     # Start API server

Architecture

swarmpay/
├── __init__.py        # Package exports (v0.3.1)
├── client.py          # Main SwarmPay class
├── wallet.py          # AgentWallet -- USDC & ETH transfers
├── constants.py       # USDC contracts, network config
├── fee_engine.py      # Volume-based fee tiers
├── registry.py        # Service discovery
├── escrow.py          # Escrow engine (hold-release-dispute)
├── reputation.py      # Agent reputation scoring
├── permissions.py     # Spending limits & access control
├── api_server.py      # REST API (port 8420, auth + rate limiting)
├── mcp_server.py      # Claude MCP integration
├── cli.py             # CLI tool
└── openai_tools.py    # OpenAI function calling

tests/                 # 112 unit tests
├── test_escrow.py     # Escrow lifecycle tests
├── test_reputation.py # Reputation scoring tests
├── test_permissions.py# Permission engine tests
├── test_wallet.py     # Payment & validation tests
├── test_fee_engine.py # Fee calculation tests
├── test_registry.py   # Service registry tests
└── test_constants.py  # Constants tests

Fee Structure

Monthly Volume	Fee
$0 -- $10K	1.0%
$10K -- $100K	0.8%
$100K -- $1M	0.5%
$1M+	0.3%

Networks

Network	ID	Status
Base Mainnet	base-mainnet	Live
Base Sepolia	base-sepolia	Testnet

Tech Stack

• Blockchain: Base (Ethereum L2 by Coinbase)
• Currency: USDC (stablecoin, 6 decimals)
• Wallet Infrastructure: Coinbase CDP SDK (AgentKit)
• Security: Non-custodial, TEE-secured wallets, Bearer auth, rate limiting
• Protocol: ERC-20 token transfers

Running Tests

pip install swarmpay[dev]
python -m pytest tests/ -v  # 112 tests

License

MIT -- see LICENSE