Ag402

Give your AI agent a wallet. It pays for APIs automatically.

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
• One command to start paying: ag402 run -- python my_agent.py
• One command to start selling: ag402 serve --target ... --price ... --address ...
• One command to install MCP tools: ag402 install claude-code
• 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
• 748+ tests, 90%+ coverage, 4 rounds of internal security review (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
• TypeScript/Node.js agents — @ag402/fetch npm package, zero dependencies

Zero Code Changes. For Everyone.

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

Try It Now

Python (zero code changes):

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

TypeScript/Node.js:

npm install @ag402/fetch

import { createX402Fetch, InMemoryWallet } from "@ag402/fetch";
const apiFetch = createX402Fetch({ wallet: new InMemoryWallet(100) }); // $100 budget
const res = await apiFetch("https://paid-api.example.com/data");
// 402 → auto-pays USDC → retries → 200 OK

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>

Or zero install (Python):

Already in Production

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 TypeScript/Node.js Developers — Two Lines

npm install @ag402/fetch

import { createX402Fetch, InMemoryWallet } from "@ag402/fetch";

const apiFetch = createX402Fetch({
  wallet: new InMemoryWallet(100), // $100 budget
  config: { maxAmountPerCall: 1.00, maxTotalSpend: 50.00 },
});

const res = await apiFetch("https://paid-api.example.com/data");
// 402 Payment Required → auto-pays → retries → 200 OK

Swap InMemoryWallet with your own Wallet implementation and MockPaymentProvider with @ag402/solana (coming soon — see Roadmap) for real on-chain payments. Zero runtime dependencies — Node.js 18+, Bun, Deno.

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)

# Purchase a prepaid pack from any ag402 gateway
ag402 prepaid buy https://your-gateway.example.com p3d_100

# Check your credentials
ag402 prepaid status

Available package IDs: p3d_100 (Starter), p7d_500 (Basic), p30d_1000 (Pro), p365d_5000 (Business), 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
ag402 serve --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 serve --target http://localhost:8000 --price 0.01 --address <Addr>

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 internal security review · 24 issues found, 24 fixed · 109 dedicated security TDD tests · 748+ total tests · 90%+ coverage

6-Layer Budget Protection

Architecture Principles

CI Pipeline (Every PR)

CodeQL · Trivy · pip-audit · Semgrep · 748+ 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 tx_hash="abc123..." chain="solana" payer_address="..." request_id="..."

→ 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                                            │
│             ▼                                                    │
│  Retries with: Authorization: x402 tx_hash="..." chain="solana" │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  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

Package	Registry	Role
open402		Protocol standard — zero dependencies
ag402-core		Payment engine + CLI + wallet (buyer)
ag402-mcp		Reverse-proxy gateway (seller) — zero code changes
ag402-client-mcp		MCP client for AI tools (buyer)
@ag402/fetch		TypeScript/Node.js buyer SDK — zero runtime deps

CLI Reference

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

Documentation

Community

• GitHub Discussions — questions, ideas, show & tell
• Issue Tracker — bug reports, feature requests
• Contributing Guide — PRs welcome, see "Good First Issues"

Roadmap

License

MIT — Open source, free forever.