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 on-chain escrow, reputation tracking, and spending controls.

Escrow Contract: 0x9Be790E8583f0425D213bF862148E8e531700106 (Base Mainnet, verified)

Install

# macOS (recommended)
brew install pipx && pipx install swarmpay

# Linux / Windows / venv
pip install swarmpay

2-Minute Start

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

On-Chain Escrow

Funds are held in a verified smart contract until service delivery is confirmed. No trust required.

Buyer                     Contract                    Provider
  |-- approve USDC -------->|                            |
  |-- fundEscrow() -------->| holds funds                |
  |                         |<-- confirmDelivery() ------|
  |-- releaseEscrow() ----->| pays provider + fee        |

SDK Usage

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)

CLI

swarmpay escrow list                              # List active escrows
swarmpay escrow fund <provider> <amount>          # Create escrow
swarmpay escrow confirm <escrow_id>               # Provider confirms delivery
swarmpay escrow release <escrow_id>               # Buyer releases funds
swarmpay escrow dispute <escrow_id> <reason>      # Open dispute
swarmpay escrow refund <escrow_id>                # Refund (after timeout/dispute)

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
# Tools: swarmpay_create_wallet, swarmpay_pay, swarmpay_escrow_fund,
#         swarmpay_escrow_release, swarmpay_escrow_dispute, 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
swarmpay escrow list  # Manage escrows

Architecture

swarmpay/
├── __init__.py         # Package exports (v0.4.2)
├── client.py           # Main SwarmPay class
├── wallet.py           # AgentWallet -- USDC & ETH transfers
├── constants.py        # USDC contracts, escrow addresses, network config
├── fee_engine.py       # Volume-based fee tiers
├── registry.py         # Service discovery
├── escrow.py           # Off-chain escrow engine
├── onchain_escrow.py   # On-chain escrow (Base Mainnet contract)
├── reputation.py       # Agent reputation scoring
├── permissions.py      # Spending limits & access control
├── webhooks.py         # Webhook event notifications
├── dashboard.py        # Dashboard feed & summaries
├── 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

contracts/
└── SwarmpayEscrow.sol  # Solidity escrow contract (verified on Basescan)

tests/                  # 168 unit + integration tests

Fee Structure

Networks

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
• Smart Contract: Solidity 0.8.24, verified on Basescan
• Protocol: ERC-20 token transfers + on-chain escrow

Running Tests

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

License

MIT -- see LICENSE