# 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-168%20passed-brightgreen.svg)]()
[![Base Mainnet](https://img.shields.io/badge/blockchain-Base%20Mainnet-0052FF.svg)](https://basescan.org/address/0x9Be790E8583f0425D213bF862148E8e531700106)

**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`](https://basescan.org/address/0x9Be790E8583f0425D213bF862148E8e531700106#code) (Base Mainnet, verified)

## Install

```bash
pip install swarmpay
```

## 2-Minute Start

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

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

## On-Chain Escrow

Funds are held in a [verified smart contract](https://basescan.org/address/0x9Be790E8583f0425D213bF862148E8e531700106#code) until service delivery is confirmed. No trust required.

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

### SDK Usage

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

### CLI

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

```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
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)
```bash
python -m swarmpay.mcp_server
# Tools: swarmpay_create_wallet, swarmpay_pay, swarmpay_escrow_fund,
#         swarmpay_escrow_release, swarmpay_escrow_dispute, etc.
```

### OpenAI Function Calling
```python
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
```bash
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

| 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
- **Smart Contract**: Solidity 0.8.24, verified on [Basescan](https://basescan.org/address/0x9Be790E8583f0425D213bF862148E8e531700106#code)
- **Protocol**: ERC-20 token transfers + on-chain escrow

## Running Tests

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

## License

MIT -- see [LICENSE](LICENSE)
