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

• 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

• 775+ 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 setup      # Interactive wizard: creates wallet, selects network, configures keys
ag402 demo       # Watch the full payment flow end-to-end

For non-interactive / CI use, run ag402 init instead — zero prompts, auto-creates wallet with $100 test USDC.

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

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

DeepBlue API — Featured Example

Real-time BTC/ETH/SOL trading signals for AI agents at $0.001 USDC per call — perfect for demonstrating x402 micropayments.

• Ultra-low cost: $0.001 per API call — ideal for testing and demonstrations

• Real trading signals: BTC, ETH, SOL market analysis and predictions

• Seller: DeepBlue uses x402 protocol for instant micropayments

• Buyer: Agents auto-pay via ag402 — zero code changes needed

• Ecosystem integration: Featured in ag402 documentation as a showcase example

Agent → GET /api/signals/BTC
     ← 402 Payment Required ($0.001)
     → Ag402 pays USDC on Solana
     → Retries with payment proof
     ← 200 OK + trading signals

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.

Framework Examples

import ag402_core
ag402_core.enable()  # one line — before any tool calls

from langchain.tools import tool
import httpx

@tool
def get_weather(city: str) -> str:
    """Get weather from a paid API. ag402 handles the 402 automatically."""
    resp = httpx.get("https://weather-api.example.com/data", params={"city": city})
    resp.raise_for_status()
    return resp.json()["summary"]

# Build your agent normally — no payment logic anywhere
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_openai import ChatOpenAI
# ... standard LangChain setup

Full example: examples/langchain_integration.py — start examples/start_local_demo.py first for a self-contained local demo.

import ag402_core
ag402_core.enable()

from autogen import AssistantAgent, UserProxyAgent
import httpx

assistant = AssistantAgent("assistant", llm_config={...})
user_proxy = UserProxyAgent("user", human_input_mode="NEVER", ...)

@user_proxy.register_for_execution()
@assistant.register_for_llm(description="Get weather data.")
def get_weather(city: str) -> str:
    resp = httpx.get("https://weather-api.example.com/data", params={"city": city})
    return resp.json()["summary"]  # 402 was auto-paid before this line

Full example: examples/autogen_integration.py — start examples/start_local_demo.py first.

import ag402_core
ag402_core.enable()

from crewai.tools import tool
import httpx

@tool("Weather Data Tool")
def get_weather(city: str) -> str:
    """Fetch weather from a paid API."""
    resp = httpx.get("https://weather-api.example.com/data", params={"city": city})
    return f"{resp.json()['city']}: {resp.json()['temp']}°C"

# Build Agents, Tasks, Crew normally — ag402 is invisible

Full example: examples/crewai_integration.py — start examples/start_local_demo.py first.

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 for real on-chain USDC 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 · 775+ total tests · 90%+ coverage

6-Layer Budget Protection

Architecture Principles

CI Pipeline (Every PR)

CodeQL · Trivy · pip-audit · Semgrep · 775+ 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

CLI Reference

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

Documentation

Troubleshooting

ag402 doctor

Run ag402 doctor first. It validates your environment end-to-end and prints a PASS/FAIL report with actionable fix suggestions for each issue:

• Python version and required package installation

• Solana cryptography dependencies (solana, solders, spl-token)

• RPC connectivity (pings your configured endpoint and any backups)

• Wallet file presence and integrity (detects corruption or missing keys)

• Budget configuration sanity (flags limits set to $0 or above the $1,000 ceiling)

ag402 doctor          # full health check

If ag402 doctor passes but you still see errors, enable verbose mode: AG402_DEBUG=1 ag402 run -- python my_agent.py

Configuration priority

Ag402 resolves configuration in this order (highest priority wins):

1. Environment variables — e.g. X402_DAILY_LIMIT=50, AG402_RPC_URL=https://...

2. .env file — loaded from the current working directory at process start

3. Code defaults — the values baked into ag402-core itself (e.g. $10 daily limit)

Environment variables always override .env values. .env values always override code defaults. To verify what values are active, run ag402 status (shows resolved limits and config source) or ag402 doctor.

Common errors

Still stuck?

• ag402 doctor — full environment health check with actionable suggestions

• GitHub Issues — search existing issues or file a new one

• Set AG402_DEBUG=1 for verbose output including full stack traces

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.