# SwarmPay -- The Payment Layer for AI Agents

[![PyPI](https://img.shields.io/pypi/v/swarmpay.svg)](https://pypi.org/project/swarmpay/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-112%20passed-brightgreen.svg)]()
[![Base Mainnet](https://img.shields.io/badge/blockchain-Base%20Mainnet-0052FF.svg)]()

**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

```bash
pip install swarmpay
```

## Quick Start

```python
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

```bash
# 1. Install
pip install swarmpay[coinbase]

# 2. Configure
export CDP_API_KEY_ID="your-key-id"
export CDP_API_KEY_SECRET="your-key-secret"
export CDP_WALLET_SECRET="your-wallet-secret"
# Get keys at: https://portal.cdp.coinbase.com

# 3. Use
python -c "from swarmpay import SwarmPay; print('Ready!')"
```

## 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

```python
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

```python
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

```python
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
```bash
python -m swarmpay.api_server  # Starts on port 8420

curl http://localhost:8420/pay -X POST \
  -H "Authorization: Bearer $SWARMPAY_API_KEY" \
  -d '{"from": "my-agent", "to": "0x...", "amount": 0.50}'
```

### MCP Server (Claude)
```bash
python -m swarmpay.mcp_server
# Exposes tools: swarmpay_create_wallet, swarmpay_pay, etc.
```

### OpenAI Function Calling
```python
from swarmpay.openai_tools import SWARMPAY_TOOLS, handle_swarmpay_call

tools = SWARMPAY_TOOLS
response = handle_swarmpay_call("swarmpay_pay", {
    "from_agent": "my-agent",
    "to": "0x...",
    "amount": 0.50
})
```

### CLI
```bash
swarmpay setup     # Interactive setup
swarmpay status    # Check wallet & network
swarmpay playground  # Interactive demo
```

## 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

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

## License

MIT -- see [LICENSE](LICENSE)
