# AutoPay Protocol

> Non-custodial crypto subscription payment protocol built on USDC.
> Users keep full custody of funds. Merchants receive automatic recurring payments.
> Works alongside Stripe, not instead of it. Multi-chain (Base, Flow EVM, Arbitrum, Polkadot Hub, Tempo).
> Protocol fee: 2.5% per charge. SDK: `@autopayprotocol/sdk` on npm.

AutoPay lets merchants accept recurring USDC payments without building payment infrastructure. Users approve USDC spending to the PolicyManager smart contract, create a subscription policy (merchant, amount, interval, spending cap), and a relayer charges them automatically each billing cycle. The first charge executes immediately on subscription creation.

Funds never leave the user's wallet until charged. Users can revoke policies at any time. After 3 consecutive failed charges (insufficient balance/allowance), policies are auto-cancelled.

## Getting Started

- [Overview](https://autopayprotocol.com/docs/overview.md): What AutoPay is, how it works, who these docs are for
- [Subscriber Guide](https://autopayprotocol.com/docs/subscriber-guide.md): How to subscribe, fund your wallet, manage subscriptions
- [Merchant Guide](https://autopayprotocol.com/docs/merchant-guide.md): Accept payments, create plans, manage subscribers

## SDK Integration

- [Backend SDK Guide](https://autopayprotocol.com/docs/sdk-backend.md): Install `@autopayprotocol/sdk`, create checkout URLs, verify webhooks, handle events
- [Checkout Example](https://autopayprotocol.com/docs/merchant-checkout-example.md): Full working merchant integration with webhook handling

## Agent Economy

- [Agent SDK Quickstart](https://autopayprotocol.com/docs/agent-sdk-quickstart.md): Build autonomous AI agents that pay for services with USDC
- [Agent SDK Reference](https://autopayprotocol.com/docs/agent-sdk-reference.md): Full API reference for agent integrations
- [MCP Server Reference](https://autopayprotocol.com/docs/mcp-reference.md): Model Context Protocol server for AI tool use
- [Middleware Reference](https://autopayprotocol.com/docs/middleware-reference.md): Express/Fastify middleware for payment-gated endpoints
- [Agent Architecture](https://autopayprotocol.com/docs/AGENT_ARCHITECTURE.md): How agents, MCP, and middleware fit together

## Relayer (Self-Hosting)

- [Local Setup](https://autopayprotocol.com/docs/relayer-local-setup.md): Run the relayer locally with Docker
- [Configuration](https://autopayprotocol.com/docs/relayer-configuration.md): Environment variables, chain config, feature flags
- [Operations](https://autopayprotocol.com/docs/relayer-operations.md): Monitoring, troubleshooting, database management
- [Deployment](https://autopayprotocol.com/docs/relayer-deployment.md): Deploy to Railway, Docker, or any Node.js host

## Key Concepts

- [Webhook Events](https://autopayprotocol.com/docs/sdk-backend.md): policy.created, charge.succeeded, charge.failed, policy.revoked, policy.completed, policy.cancelled_by_failure
- [Checkout Flow](https://autopayprotocol.com/docs/sdk-backend.md): Hosted checkout page — redirect users, parse success callback

## API Reference

- Relayer API root: GET / returns full endpoint listing
- Plan management: GET/POST/PUT/PATCH/DELETE /merchants/:address/plans
- Subscribers: GET /merchants/:address/subscribers
- Charges: GET /merchants/:address/charges
- Webhooks: GET/PUT /merchants/:address/webhook
- Payer policies: GET /payers/:address/policies
- Auth: EIP-191 wallet signatures (GET /auth/nonce, then sign)
- API keys: POST /merchants/:address/api-keys for programmatic access

## Contract Addresses

- Base (8453): PolicyManager `0x037A24595E96B10d9FB2c7c2668FE5e7F354c86a`, USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Flow EVM (747): PolicyManager `0x5EDAF928C94A249C5Ce1eaBaD0fE799CD294f345`, USDC `0xF1815bd50389c46847f0Bda824eC8da914045D14`
- Arbitrum One (42161): PolicyManager `0xCE3550099De882607B50d6F57d4ECd3985dcd521`, USDC `0xaf88d065e77c8cC2239327C5EDb3A432268e5831`
- Polkadot Hub (420420419): PolicyManager `0x5EDAF928C94A249C5Ce1eaBaD0fE799CD294f345`, USDC `0x0000053900000000000000000000000001200000`
- Tempo (4217): PolicyManager `0x5EDAF928C94A249C5Ce1eaBaD0fE799CD294f345`, USDC.e `0x20c000000000000000000000b9537d11c60e8b50` (bridged via Stargate/LayerZero — LiFi not yet supported)
- Base Sepolia (84532, testnet): PolicyManager `0x5EDAF928C94A249C5Ce1eaBaD0fE799CD294f345`, USDC `0x036CbD53842c5426634e7929541eC2318f3dCF7e`

## SDK Quick Reference

```typescript
import { createCheckoutUrl, verifyWebhook, formatUSDC, parseUSDC } from '@autopayprotocol/sdk'

// Create a checkout URL
const url = createCheckoutUrl({
  merchant: '0x...',
  amount: 9.99,
  interval: 'monthly',
  metadataUrl: 'https://relayer.autopayprotocol.com/metadata/0x.../pro',
  successUrl: 'https://yoursite.com/success',
  cancelUrl: 'https://yoursite.com/cancel',
})

// Verify webhook in your server
const event = verifyWebhook(rawBody, signature, webhookSecret)
if (event.type === 'charge.succeeded') {
  // Grant/extend access
}
```

## AI Coding Agent Integration

This llms.txt file is designed to be consumed by any AI coding agent. Point your agent at `https://autopayprotocol.com/llms.txt` and it will discover all the documentation it needs.

- **Claude Code**: `mkdir -p .claude/skills/autopay-integrate && curl -s https://autopayprotocol.com/claude-skill.md -o .claude/skills/autopay-integrate/SKILL.md`, then use `/autopay-integrate <task>`.
- **Cursor**: Settings → Docs → Add `https://autopayprotocol.com/llms.txt` as `AutoPay`, then use `@AutoPay <task>` in chat. Or add `.cursor/rules/autopay.mdc` referencing the URL.
- **GitHub Copilot**: Create `.github/copilot-instructions.md` telling Copilot to fetch `https://autopayprotocol.com/llms.txt` and use `@autopayprotocol/sdk` for any AutoPay work.
- **OpenAI Codex / ChatGPT / Codex CLI**: Add `Read https://autopayprotocol.com/llms.txt before writing AutoPay code` to `AGENTS.md` or the system prompt.
- **Windsurf**: Add the URL to `.windsurfrules`, or use `@web https://autopayprotocol.com/llms.txt` in Cascade.
- **Aider**: `/web https://autopayprotocol.com/llms.txt` to pull the index into context.
- **Continue**: Add `https://autopayprotocol.com/llms.txt` as a `@docs` context provider.

Example prompts (work in any agent once configured):

```
Build an Express webhook handler for AutoPay
Create a Next.js checkout page with an existing plan
Write a Python Flask subscription server
Add AutoPay to my Fastify server with payment-gated routes
```

## Optional

- [npm: @autopayprotocol/sdk](https://www.npmjs.com/package/@autopayprotocol/sdk): SDK package on npm
- [LiFi Bridge](https://li.fi/): Cross-chain USDC bridging (30+ chains)
- [RainbowKit](https://www.rainbowkit.com/): Wallet connection UI