# SwarmPay – The Payment Layer for AI Agents

[![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-50%20passed-brightgreen.svg)]()
[![Base](https://img.shields.io/badge/blockchain-Base%20(L2)-0052FF.svg)]()

**AI agents autonomously pay each other via blockchain. A 1% platform fee is collected per transaction.**

SwarmPay is the Visa for the AI Agents a payment infrastructure SDK that lets AI agents discover services, negotiate prices, and transact autonomously using USDC on Base (Ethereum L2).

## Quick Start

```python
# pip install swarmpay
from swarmpay import SwarmPay

sp = SwarmPay()
wallet = sp.create_wallet("my-agent")
wallet.pay("0xRecipient...", amount=0.50)  # Pays $0.50 USDC
```

That's it. 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. Clone & setup
git clone https://github.com/ginokino/swarmpay-sdk.git
cd swarmpay-sdk
python3.12 -m venv .venv
source .venv/bin/activate

# 2. Install
pip install -r requirements.txt

# 3. Configure
cp .env.example .env
# Add your Coinbase CDP keys to .env
# Get keys at: https://portal.cdp.coinbase.com

# 4. Run
python examples/quickstart.py
```

## Features

| Feature | Description |
|---|---|
| **3 Lines of Code** | Import, initialize, pay. No blockchain knowledge needed. |
| **USDC Payments** | Native USDC support on Base (6 decimal precision). |
| **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. |

## Integrations

### Python SDK
```python
from swarmpay import SwarmPay

sp = SwarmPay()
wallet = sp.create_wallet("my-agent")

# Register a service
sp.register_service(wallet, "text-analysis", price_usd=0.50,
                    description="NLP text analysis")

# Find and buy services
result = sp.buy_service(wallet, "text-analysis")
print(result["payment"].success)  # True
```

### REST API
```bash
python -m swarmpay.api_server  # Starts on port 8420

curl http://localhost:8420/wallets -X POST \
  -d '{"agent_id": "my-agent"}'

curl http://localhost:8420/pay -X POST \
  -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.
```

### OpenClaw (Personal AI Agent)
```bash
# Install the SwarmPay skill
cd openclaw-skill && bash install.sh

# Start SwarmPay API
python -m swarmpay.api_server

# Tell OpenClaw to refresh skills, then:
# "Create a wallet for my-agent"
# "Pay 0x... $0.50"
# "Find text-analysis services"
```

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

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

## Architecture

```
swarmpay/
├── __init__.py        # Package exports (v0.2.0)
├── 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
├── mcp_server.py      # Claude MCP integration
├── api_server.py      # REST API (port 8420)
└── openai_tools.py    # OpenAI function calling

openclaw-skill/
├── SKILL.md           # OpenClaw skill definition
└── install.sh         # One-click installer

examples/
├── quickstart.py      # Basic demo
└── agent_to_agent.py  # Multi-agent economy demo

tests/                 # 50 unit tests
├── test_constants.py
├── test_fee_engine.py
├── test_registry.py
└── test_wallet.py
```

## Fee Structure

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

## Tech Stack

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

## USDC Contract Addresses

| Network | Address |
|---|---|
| Base Mainnet | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Base Sepolia | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |

## Running Tests

```bash
source .venv/bin/activate
python -m pytest tests/ -v  # 50 tests
```

## License

MIT – see [LICENSE](LICENSE)
