ag402-mcp

Ag402 is the payment layer for the Coinbase x402 protocol. It makes AI agents pay for API calls automatically — on Solana, in USDC, with zero code changes.

Agent calls API → 402 Payment Required → Ag402 auto-pays USDC on Solana → 200 OK

Non-custodial. Zero telemetry. Already in production.

Why Ag402

Zero friction

• Zero code changes for buyers, sellers, and MCP developers

• Three CLI commands cover everything: ag402 run, ag402 serve, ag402 install

• No config files, no API keys, no accounts, no signup

• Colab one-click demo — try it in your browser, zero install

Open standard

• Implements Coinbase x402 — the emerging HTTP payment standard

• MIT licensed, fully open source, extensible protocol layer (open402) with zero dependencies

• AI-native docs — ships with llms.txt so LLM agents can read the full CLI reference natively

Battle-tested

• Token RugCheck — live on Solana mainnet with real USDC payments

• 648+ tests, 90%+ coverage, 4 security audits (24/24 issues fixed)

• Multi-endpoint RPC failover + circuit breaker + async delivery retry

Blazing fast

• ~0.5s standard payment (confirmed finality, not 13s finalized)

• ~1ms prepaid payment (local HMAC, no on-chain call)

• Zero overhead on non-402 requests — no body read, no allocation

• Connection pooling, lazy imports, SQLite WAL mode

Security-first

• 6-layer budget protection — per-tx / per-minute / daily / circuit breaker / rollback / key redaction

• Non-custodial — private keys never leave your machine

• Seller-No-Key — sellers only need a public address, zero private key risk

• Zero telemetry — no tracking, no IP logging, no analytics

• Wallet encryption: PBKDF2 (480K iter) + AES

• CI: CodeQL + Trivy + pip-audit + Semgrep + OpenSSF Scorecard

Universal compatibility

• Claude Code, Cursor, Claude Desktop — MCP auto-config

• OpenClaw — native Skill (SKILL.md + TOOLS.md + skill.py), not just MCP

• LangChain, AutoGen, CrewAI, Semantic Kernel — works automatically

• Any Python agent using httpx or requests — zero changes

Zero Code Changes. For Everyone.

No config files. No API keys. No accounts. No code changes.

Try It Now

pip install ag402-core
ag402 init       # Creates wallet + $100 test USDC — zero prompts
ag402 demo       # Watch the full payment flow end-to-end

Or zero install:

Already in Production

Token RugCheck

Live on Solana mainnet. AI agents pay $0.02 USDC per audit to detect rug pulls before purchasing tokens.

• Three-layer audit: machine verdict → LLM analysis → raw on-chain evidence

• Seller: ag402 serve — zero code changes to the audit API

• Buyer: ag402_core.enable() — agents auto-pay, zero code changes

• Try it now: curl -I https://rugcheck.aethercore.dev/v1/audit/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263

Agent → GET /v1/audit/{token}
     ← 402 Payment Required ($0.02)
     → Ag402 pays USDC on Solana
     → Retries with tx_hash proof
     ← 200 OK + full audit report

Not a demo. Real USDC, real Solana mainnet, real users, already running.

How It Works

For Agent Users — Zero Code Changes

Your agent already uses httpx or requests under the hood. Ag402 patches them transparently:

# Option A: CLI wrapper (easiest — zero code changes)
ag402 run -- python my_agent.py

# Option B: One-liner in code
import ag402_core; ag402_core.enable()

That's it. Every HTTP 402 response is now intercepted → paid → retried automatically. Your agent code stays completely untouched.

Works with LangChain, AutoGen, CrewAI, Semantic Kernel, and any framework built on httpx or requests.

For Claude Code / Cursor / OpenClaw — One Command

pip install ag402-core ag402-client-mcp
ag402 install claude-code    # or: cursor / claude-desktop / openclaw

Restart your tool. Three MCP tools appear:

OpenClaw gets the deepest integration — Ag402 ships as a native OpenClaw Skill (SKILL.md + TOOLS.md + skill.py), not a wrapper. The skill registers natively in OpenClaw's skill system, with full tool definitions, prepaid support, and auto-fallback.

For API Sellers — Zero Code Changes

pip install ag402-core ag402-mcp
ag402 serve --target http://localhost:8000 --price 0.05 --address <YourSolanaAddress>

Your existing API runs untouched behind a reverse proxy. The proxy:

• Returns 402 + x402 challenge to unpaid requests

• Verifies payment on-chain (no private key needed — seller only provides a public address)

• Proxies paid requests through to your API

• Handles replay protection, rate limiting, header sanitization

MCP server developers: same command, same result. Wrap your MCP server, get a paywall instantly.

Performance

🆕 Prepaid System — From 500ms to 1ms

The problem: Standard x402 payments require an on-chain Solana transaction for every API call (~0.5s + gas fee). For high-frequency agents making hundreds of calls per hour, this adds up in both latency and cost.

The solution: Buy a prepaid credit pack with one on-chain payment, then use HMAC credentials for subsequent calls — zero gas, ~1ms latency.

Buy:  Agent → one Solana payment → gets HMAC-SHA256 credential (N calls / M days)
Use:  Agent → X-Prepaid-Credential header → local HMAC verify → 200 OK   ← no chain, ~1ms

5 Prepaid Tiers

How it works

1. Buyer purchases a prepaid pack → one Solana tx → receives HMAC credential

2. Each API call includes X-Prepaid-Credential header → server verifies HMAC locally (~1ms)

3. No on-chain tx needed per call → zero gas fees after initial purchase

4. Auto-fallback to standard x402 payment when prepaid credits are exhausted

Quick Start (Buyer)

# Step 1: Browse available packages from any ag402 gateway
ag402 prepaid buy https://your-gateway.example.com p3d_100

# Step 2: Check your credentials
ag402 prepaid status

Available package IDs: p3d_100 (Starter), p7d_500 (Basic), p30d_1000 (Standard), p365d_5000 (Professional), p730d_10k (Enterprise).

In production mode (real USDC), ag402 prepaid buy will:

1. Show the package price and seller address

2. Ask Confirm payment? [Y/n]

3. Broadcast the USDC on-chain automatically

4. Store the credential at ~/.ag402/prepaid_credentials.json

If the gateway times out after payment is broadcast, your credential is not lost — retry or recover:

# Retry automatically picks up the last in-flight purchase
ag402 prepaid recover https://your-gateway.example.com

# Or provide explicit tx_hash and package_id if needed
ag402 prepaid recover https://your-gateway.example.com <tx_hash> <package_id>

# Manage credentials
ag402 prepaid status   # View all credentials grouped by seller (calls remaining / expiry)
ag402 prepaid purge    # Remove expired or depleted credentials

Seller Setup

# Start gateway with prepaid support (generates a signing key if not set)
ag402-gateway --target http://localhost:8000 \
              --price 0.01 \
              --address <YourSolanaAddress> \
              --prepaid-signing-key <secret-key>

# Or via environment variable
AG402_PREPAID_SIGNING_KEY=<secret-key> ag402-gateway ...

Buyers can then discover packages at GET /prepaid/packages and purchase at POST /prepaid/purchase.

Security

• HMAC-SHA256 signatures prevent credential forgery

• Constant-time comparison prevents timing attacks

• Credentials are scoped per buyer-seller pair

• Server-side cache (5 min TTL) for repeat verification

Security — Built for Real Money

Your agent holds private keys and moves real USDC. Security is not a feature — it's the foundation.

4 rounds of security audits · 24 issues found, 24 fixed · 109 dedicated security TDD tests · 648+ total tests · 90%+ coverage

6-Layer Budget Protection

Architecture Principles

CI Pipeline (Every PR)

CodeQL · Trivy · pip-audit · Semgrep · 648+ tests · 90%+ coverage · OpenSSF Scorecard

Protocol

HTTP/1.1 402 Payment Required
WWW-Authenticate: x402 chain="solana" token="USDC" amount="0.05" address="..."

→ Client pays on-chain, retries with:

GET /data HTTP/1.1
Authorization: x402 <solana_tx_hash>

→ Server verifies on-chain → 200 OK

Compatible with the Coinbase x402 open payment standard.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  Your Agent (LangChain / CrewAI / AutoGen / any Python)        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  ag402_core.enable()  ← monkey-patches httpx / requests  │   │
│  └──────────────┬───────────────────────────────────────────┘   │
│                 │ HTTP request                                   │
│                 ▼                                                │
│  ┌──────────────────────────┐    ┌────────────────────────┐     │
│  │  x402 Middleware         │───▶│  BudgetGuard (6 layers)│     │
│  │  Intercepts 402 response │    │  Circuit Breaker       │     │
│  └──────────┬───────────────┘    └────────────────────────┘     │
│             │ Pay                                                │
│             ▼                                                    │
│  ┌──────────────────────────┐    ┌────────────────────────┐     │
│  │  SolanaAdapter           │───▶│  RPC Failover          │     │
│  │  USDC transfer + verify  │    │  Exponential backoff   │     │
│  └──────────┬───────────────┘    └────────────────────────┘     │
│             │ tx_hash                                            │
│             ▼                                                    │
│  Retry original request with  Authorization: x402 <tx_hash>     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  Seller Gateway  (ag402 serve)                                  │
│  ┌────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │ 402 + x402 │  │ On-chain     │  │ Replay Guard           │  │
│  │ Challenge   │  │ Verification │  │ Rate Limiter           │  │
│  └────────────┘  └──────────────┘  │ Header Sanitization    │  │
│                                     └────────────────────────┘  │
│  → Proxies to your API (unchanged)                              │
└─────────────────────────────────────────────────────────────────┘

Full architecture diagrams & state machines → docs/architecture_state.md

Packages

CLI Reference

Full CLI reference → llms.txt (AI-readable, paste into your agent's context)

Documentation

Quick Copy-Paste

Agent user (zero code changes):

pip install ag402-core && ag402 init && ag402 run -- python my_agent.py

Claude Code / Cursor:

pip install ag402-core ag402-client-mcp && ag402 install claude-code

Sell your API (zero code changes):

pip install ag402-core ag402-mcp && ag402 serve --target http://your-api:8000 --price 0.05 --address <Addr>

Community

• GitHub Discussions — questions, ideas, show & tell

• Issue Tracker — bug reports, feature requests

• Contributing Guide — PRs welcome, see "Good First Issues"

Roadmap

TypeScript SDK (Coming Soon)

The next major milestone: ag402-ts — a TypeScript implementation of ag402 for the Node.js/Deno/Bun ecosystem.

// Seller: Express middleware (coming soon)
import { ag402 } from 'ag402-ts';

app.use('/api', ag402({ price: '0.01', address: '<SolanaAddress>' }));

// Buyer: Auto-pay fetch wrapper (coming soon)
import { enableAutoPay } from 'ag402-ts/client';

enableAutoPay(); // All 402 responses are auto-paid
const data = await fetch('https://paid-api.example.com/data');

Why TypeScript?

• MCP ecosystem is ~50% TypeScript (FastMCP-TS, official SDK)

• Vercel/Cloudflare edge functions need native TS support

• npm > PyPI in total package installs

Want to contribute or beta test? Open an issue or reach out on X @AetherCoreDev.

License

MIT — Open source, free forever.