{"id":47469011,"url":"https://github.com/AetherCore-Dev/ag402","last_synced_at":"2026-04-08T06:00:47.646Z","repository":{"id":340133485,"uuid":"1164547868","full_name":"AetherCore-Dev/ag402","owner":"AetherCore-Dev","description":"Zero latency!  Zero code change! Empower your AI agent with payment ability via x402 protocol!  (Openclaw, Claude code, Cursor, Langchain, CrewAI, AutoGen...)","archived":false,"fork":false,"pushed_at":"2026-03-11T14:40:48.000Z","size":714,"stargazers_count":6,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-11T20:23:36.393Z","etag":null,"topics":["agent","ai-agents","claude-code","machine-to-machine","mcp","openclaw","payment","python","solana","usdc","x402"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AetherCore-Dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T07:57:55.000Z","updated_at":"2026-03-11T14:40:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/AetherCore-Dev/ag402","commit_stats":null,"previous_names":["aethercore-dev/ag402"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/AetherCore-Dev/ag402","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AetherCore-Dev%2Fag402","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AetherCore-Dev%2Fag402/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AetherCore-Dev%2Fag402/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AetherCore-Dev%2Fag402/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AetherCore-Dev","download_url":"https://codeload.github.com/AetherCore-Dev/ag402/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AetherCore-Dev%2Fag402/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31542381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai-agents","claude-code","machine-to-machine","mcp","openclaw","payment","python","solana","usdc","x402"],"created_at":"2026-03-24T21:00:22.764Z","updated_at":"2026-04-08T06:00:47.639Z","avatar_url":"https://github.com/AetherCore-Dev.png","language":"Python","funding_links":[],"categories":["⚙️ Protocol Implementations"],"sub_categories":["Python"],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eAg402\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cstrong\u003eGive your AI agent a wallet. It pays for APIs automatically.\u003c/strong\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://github.com/AetherCore-Dev/ag402/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/AetherCore-Dev/ag402?style=social\" alt=\"GitHub Stars\" /\u003e\u003c/a\u003e\u0026nbsp;\n    \u003ca href=\"https://pypi.org/project/ag402-core/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/ag402-core?label=downloads\" alt=\"PyPI Downloads\" /\u003e\u003c/a\u003e\u0026nbsp;\n    \u003ca href=\"https://github.com/AetherCore-Dev/ag402/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/AetherCore-Dev/ag402/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/tests-775%2B_passing-brightgreen\" alt=\"Tests\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/coverage-90%25+-brightgreen\" alt=\"Coverage\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/security_reviews-4_rounds-blue\" alt=\"Security Audits\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue\" alt=\"Python\" /\u003e\n    \u003cimg src=\"https://img.shields.io/badge/node-18%2B-brightgreen\" alt=\"Node.js\" /\u003e\n    \u003ca href=\"https://pypi.org/project/ag402-core/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/ag402-core\" alt=\"PyPI\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/AetherCore-Dev/ag402/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/AetherCore-Dev/ag402\" alt=\"License\" /\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/AetherCore-Dev/ag402/commits/main\"\u003e\u003cimg src=\"https://img.shields.io/github/last-commit/AetherCore-Dev/ag402\" alt=\"Last Commit\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"https://colab.research.google.com/github/AetherCore-Dev/ag402/blob/main/examples/ag402_quickstart.ipynb\"\u003e\u003cimg src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\" /\u003e\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n---\n\n**Ag402** is the payment layer for the [Coinbase x402](https://github.com/coinbase/x402) protocol. It makes AI agents pay for API calls automatically — on Solana, in USDC, with zero code changes.\n\n```\nAgent calls API → 402 Payment Required → Ag402 auto-pays USDC on Solana → 200 OK\n```\n\n\u003e **Non-custodial. Zero telemetry. Already in production.**\n\n\u003c!-- TODO: Add terminal GIF demo here — record with `vhs` or `asciinema` --\u003e\n\u003c!-- ag402 init → ag402 demo — 15 seconds, shows the full colored payment flow --\u003e\n\n---\n\n## Why Ag402\n\n### Zero friction\n- Zero code changes for buyers, sellers, and MCP developers\n- One command to start paying: `ag402 run -- python my_agent.py`\n- One command to start selling: `ag402 serve --target ... --price ... --address ...`\n- One command to install MCP tools: `ag402 install claude-code`\n- No config files, no API keys, no accounts, no signup\n- [Colab one-click demo](https://colab.research.google.com/github/AetherCore-Dev/ag402/blob/main/examples/ag402_quickstart.ipynb) — try it in your browser, zero install\n\n### Open standard\n- Implements [Coinbase x402](https://github.com/coinbase/x402) — the emerging HTTP payment standard\n- MIT licensed, fully open source, extensible protocol layer (`open402`) with zero dependencies\n- **AI-native docs** — ships with [`llms.txt`](llms.txt) so LLM agents can read the full CLI reference natively\n\n### Battle-tested\n- [Token RugCheck](https://github.com/AetherCore-Dev/token-rugcheck) — **live on Solana mainnet** with real USDC payments\n- 775+ tests, 90%+ coverage, 4 rounds of internal security review (24/24 issues fixed)\n- Multi-endpoint RPC failover + circuit breaker + async delivery retry\n\n### Blazing fast\n- **~0.5s** standard payment (`confirmed` finality, not 13s `finalized`)\n- **~1ms** prepaid payment (local HMAC, no on-chain call)\n- Zero overhead on non-402 requests — no body read, no allocation\n- Connection pooling, lazy imports, SQLite WAL mode\n\n### Security-first\n- 6-layer budget protection — per-tx / per-minute / daily / circuit breaker / rollback / key redaction\n- Non-custodial — private keys never leave your machine\n- Seller-No-Key — sellers only need a public address, zero private key risk\n- Zero telemetry — no tracking, no IP logging, no analytics\n- Wallet encryption: PBKDF2 (480K iter) + AES\n- CI: CodeQL + Trivy + pip-audit + Semgrep + OpenSSF Scorecard\n\n### Universal compatibility\n- Claude Code, Cursor, Claude Desktop — MCP auto-config\n- OpenClaw — **native Skill** (SKILL.md + TOOLS.md + skill.py), not just MCP\n- LangChain, AutoGen, CrewAI, Semantic Kernel — works automatically\n- Any Python agent using `httpx` or `requests` — zero changes\n- **TypeScript/Node.js agents** — `@ag402/fetch` npm package, zero dependencies\n\n---\n\n## Zero Code Changes. For Everyone.\n\n| You are... | What you do | Code changes |\n|:-----------|:------------|:-------------|\n| **Agent user** (LangChain, CrewAI, AutoGen, any Python agent) | `pip install ag402-core \u0026\u0026 ag402 run -- python my_agent.py` | **Zero** — your agent code is untouched |\n| **TypeScript/Node.js agent developer** | `npm install @ag402/fetch` — wrap `fetch()` with `createX402Fetch()` | **~2 lines** — replace `fetch` with `createX402Fetch(...)` |\n| **Claude Code / Cursor user** | `ag402 install claude-code` (or `cursor`) | **Zero** — MCP tools appear automatically |\n| **OpenClaw user** | `ag402 install openclaw` | **Zero** — native Skill + MCP, auto-configured |\n| **API seller** (monetize your API) | `ag402 serve --target http://your-api:8000 --price 0.05 --address \u003cAddr\u003e` | **Zero** — reverse proxy handles everything |\n| **MCP server developer** | `ag402 serve --target http://your-mcp:3000 --price 0.01 --address \u003cAddr\u003e` | **Zero** — wrap your existing MCP server, instant paywall |\n\nNo config files. No API keys. No accounts. Minimal code changes.\n\n---\n\n## Try It Now\n\n**Python (zero code changes):**\n```bash\npip install ag402-core\nag402 setup      # Interactive wizard: creates wallet, selects network, configures keys\nag402 demo       # Watch the full payment flow end-to-end\n```\n\n\u003e For non-interactive / CI use, run `ag402 init` instead — zero prompts, auto-creates wallet with $100 test USDC.\n\n**TypeScript/Node.js:**\n```bash\nnpm install @ag402/fetch\n```\n```typescript\nimport { createX402Fetch, InMemoryWallet } from \"@ag402/fetch\";\nconst apiFetch = createX402Fetch({ wallet: new InMemoryWallet(100) }); // $100 budget\nconst res = await apiFetch(\"https://paid-api.example.com/data\");\n// 402 → auto-pays USDC → retries → 200 OK\n```\n\n**Claude Code / Cursor:**\n```bash\npip install ag402-core ag402-client-mcp \u0026\u0026 ag402 install claude-code\n```\n\n**Sell your API (zero code changes):**\n```bash\npip install ag402-core ag402-mcp \u0026\u0026 ag402 serve --target http://your-api:8000 --price 0.05 --address \u003cAddr\u003e\n```\n\nOr zero install (Python): [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/AetherCore-Dev/ag402/blob/main/examples/ag402_quickstart.ipynb)\n\n---\n\n## Already in Production\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"55%\"\u003e\n\n### [Token RugCheck](https://github.com/AetherCore-Dev/token-rugcheck)\n\n**Live on Solana mainnet.** AI agents pay **$0.02 USDC** per audit to detect rug pulls before purchasing tokens.\n\n- Three-layer audit: machine verdict → LLM analysis → raw on-chain evidence\n- **Seller**: `ag402 serve` — zero code changes to the audit API\n- **Buyer**: `ag402_core.enable()` — agents auto-pay, zero code changes\n- **Try it now**: `curl -I https://rugcheck.aethercore.dev/v1/audit/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263`\n\n\u003c/td\u003e\n\u003ctd width=\"45%\"\u003e\n\n```\nAgent → GET /v1/audit/{token}\n     ← 402 Payment Required ($0.02)\n     → Ag402 pays USDC on Solana\n     → Retries with tx_hash proof\n     ← 200 OK + full audit report\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e Not a demo. Real USDC, real Solana mainnet, real users, already running.\n\n---\n\n## How It Works\n\n### For Agent Users — Zero Code Changes\n\nYour agent already uses `httpx` or `requests` under the hood. Ag402 patches them transparently:\n\n```bash\n# Option A: CLI wrapper (easiest — zero code changes)\nag402 run -- python my_agent.py\n\n# Option B: One-liner in code\nimport ag402_core; ag402_core.enable()\n```\n\nThat's it. Every HTTP 402 response is now intercepted → paid → retried automatically. Your agent code stays **completely untouched**.\n\nWorks with **LangChain**, **AutoGen**, **CrewAI**, **Semantic Kernel**, and any framework built on `httpx` or `requests`.\n\n#### Framework Examples\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eLangChain\u003c/b\u003e — tool functions call x402 APIs, no payment code needed\u003c/summary\u003e\n\n```python\nimport ag402_core\nag402_core.enable()  # one line — before any tool calls\n\nfrom langchain.tools import tool\nimport httpx\n\n@tool\ndef get_weather(city: str) -\u003e str:\n    \"\"\"Get weather from a paid API. ag402 handles the 402 automatically.\"\"\"\n    resp = httpx.get(\"https://weather-api.example.com/data\", params={\"city\": city})\n    resp.raise_for_status()\n    return resp.json()[\"summary\"]\n\n# Build your agent normally — no payment logic anywhere\nfrom langchain.agents import AgentExecutor, create_tool_calling_agent\nfrom langchain_openai import ChatOpenAI\n# ... standard LangChain setup\n```\n\nFull example: [`examples/langchain_integration.py`](examples/langchain_integration.py) — start [`examples/start_local_demo.py`](examples/start_local_demo.py) first for a self-contained local demo.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAutoGen\u003c/b\u003e — register tools on UserProxyAgent, ag402 patches the HTTP layer\u003c/summary\u003e\n\n```python\nimport ag402_core\nag402_core.enable()\n\nfrom autogen import AssistantAgent, UserProxyAgent\nimport httpx\n\nassistant = AssistantAgent(\"assistant\", llm_config={...})\nuser_proxy = UserProxyAgent(\"user\", human_input_mode=\"NEVER\", ...)\n\n@user_proxy.register_for_execution()\n@assistant.register_for_llm(description=\"Get weather data.\")\ndef get_weather(city: str) -\u003e str:\n    resp = httpx.get(\"https://weather-api.example.com/data\", params={\"city\": city})\n    return resp.json()[\"summary\"]  # 402 was auto-paid before this line\n```\n\nFull example: [`examples/autogen_integration.py`](examples/autogen_integration.py) — start [`examples/start_local_demo.py`](examples/start_local_demo.py) first.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCrewAI\u003c/b\u003e — decorate tools with @tool, crew runs with no payment code\u003c/summary\u003e\n\n```python\nimport ag402_core\nag402_core.enable()\n\nfrom crewai.tools import tool\nimport httpx\n\n@tool(\"Weather Data Tool\")\ndef get_weather(city: str) -\u003e str:\n    \"\"\"Fetch weather from a paid API.\"\"\"\n    resp = httpx.get(\"https://weather-api.example.com/data\", params={\"city\": city})\n    return f\"{resp.json()['city']}: {resp.json()['temp']}°C\"\n\n# Build Agents, Tasks, Crew normally — ag402 is invisible\n```\n\nFull example: [`examples/crewai_integration.py`](examples/crewai_integration.py) — start [`examples/start_local_demo.py`](examples/start_local_demo.py) first.\n\n\u003c/details\u003e\n\n### For Claude Code / Cursor / OpenClaw — One Command\n\n```bash\npip install ag402-core ag402-client-mcp\nag402 install claude-code    # or: cursor / claude-desktop / openclaw\n```\n\nRestart your tool. Three MCP tools appear:\n\n| MCP Tool | What It Does |\n|----------|-------------|\n| `fetch_with_autopay` | HTTP request → auto-pays 402 APIs |\n| `wallet_status` | Check USDC balance + budget usage |\n| `transaction_history` | View recent payments |\n\n**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.\n\n### For TypeScript/Node.js Developers — Two Lines\n\n```bash\nnpm install @ag402/fetch\n```\n\n```typescript\nimport { createX402Fetch, InMemoryWallet } from \"@ag402/fetch\";\n\nconst apiFetch = createX402Fetch({\n  wallet: new InMemoryWallet(100), // $100 budget\n  config: { maxAmountPerCall: 1.00, maxTotalSpend: 50.00 },\n});\n\nconst res = await apiFetch(\"https://paid-api.example.com/data\");\n// 402 Payment Required → auto-pays → retries → 200 OK\n```\n\nSwap `InMemoryWallet` with your own `Wallet` implementation and `MockPaymentProvider` with [`@ag402/solana`](https://www.npmjs.com/package/@ag402/solana) for real on-chain USDC payments. Zero runtime dependencies — Node.js 18+, Bun, Deno.\n\n### For API Sellers — Zero Code Changes\n\n```bash\npip install ag402-core ag402-mcp\nag402 serve --target http://localhost:8000 --price 0.05 --address \u003cYourSolanaAddress\u003e\n```\n\nYour existing API runs untouched behind a reverse proxy. The proxy:\n- Returns **402 + x402 challenge** to unpaid requests\n- **Verifies payment on-chain** (no private key needed — seller only provides a public address)\n- Proxies paid requests through to your API\n- Handles replay protection, rate limiting, header sanitization\n\n**MCP server developers**: same command, same result. Wrap your MCP server, get a paywall instantly.\n\n---\n\n## Performance\n\n| Metric | Value | How |\n|--------|-------|-----|\n| **Payment latency** | **~0.5s** | `confirmed` finality — 26x faster than `finalized` (~13s) |\n| **Prepaid latency** | **~1ms** | Local HMAC-SHA256 — no on-chain call at all |\n| **Non-402 overhead** | **Zero** | Checks status code only — no body read, no allocation, no latency |\n| **RPC resilience** | **Multi-endpoint** | Exponential backoff → auto-failover to backup RPC → circuit breaker |\n| **Delivery guarantee** | **Async retry** | Payment succeeds but upstream fails? Background worker retries with backoff |\n\n### Prepaid System — From 500ms to 1ms\n\n**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.\n\n**The solution:** Buy a prepaid credit pack with one on-chain payment, then use HMAC credentials for subsequent calls — **zero gas, ~1ms latency**.\n\n```\nBuy:  Agent → one Solana payment → gets HMAC-SHA256 credential (N calls / M days)\nUse:  Agent → X-Prepaid-Credential header → local HMAC verify → 200 OK   ← no chain, ~1ms\n```\n\n#### 5 Prepaid Tiers\n\n| Package | Duration | Calls | Price (USDC) | Cost per Call |\n|---------|----------|-------|-------------|---------------|\n| Starter | 3 days | 100 | $1.50 | $0.015 |\n| Basic | 7 days | 500 | $5.00 | $0.010 |\n| Pro | 30 days | 1,000 | $8.00 | $0.008 |\n| Business | 365 days | 5,000 | $35.00 | $0.007 |\n| Enterprise | 730 days | 10,000 | $60.00 | $0.006 |\n\n#### How it works\n\n1. **Buyer** purchases a prepaid pack → one Solana tx → receives HMAC credential\n2. **Each API call** includes `X-Prepaid-Credential` header → server verifies HMAC locally (~1ms)\n3. **No on-chain tx** needed per call → zero gas fees after initial purchase\n4. **Auto-fallback** to standard x402 payment when prepaid credits are exhausted\n\n#### Quick Start (Buyer)\n\n```bash\n# Purchase a prepaid pack from any ag402 gateway\nag402 prepaid buy https://your-gateway.example.com p3d_100\n\n# Check your credentials\nag402 prepaid status\n```\n\nAvailable package IDs: `p3d_100` (Starter), `p7d_500` (Basic), `p30d_1000` (Pro), `p365d_5000` (Business), `p730d_10k` (Enterprise).\n\nIn **production mode** (real USDC), `ag402 prepaid buy` will:\n1. Show the package price and seller address\n2. Ask `Confirm payment? [Y/n]`\n3. Broadcast the USDC on-chain automatically\n4. Store the credential at `~/.ag402/prepaid_credentials.json`\n\nIf the gateway times out after payment is broadcast, your credential is not lost — retry or recover:\n\n```bash\n# Retry automatically picks up the last in-flight purchase\nag402 prepaid recover https://your-gateway.example.com\n\n# Or provide explicit tx_hash and package_id if needed\nag402 prepaid recover https://your-gateway.example.com \u003ctx_hash\u003e \u003cpackage_id\u003e\n```\n\n```bash\n# Manage credentials\nag402 prepaid status   # View all credentials grouped by seller (calls remaining / expiry)\nag402 prepaid purge    # Remove expired or depleted credentials\n```\n\n#### Seller Setup\n\n```bash\n# Start gateway with prepaid support\nag402 serve --target http://localhost:8000 \\\n            --price 0.01 \\\n            --address \u003cYourSolanaAddress\u003e \\\n            --prepaid-signing-key \u003csecret-key\u003e\n\n# Or via environment variable\nAG402_PREPAID_SIGNING_KEY=\u003csecret-key\u003e ag402 serve --target http://localhost:8000 --price 0.01 --address \u003cAddr\u003e\n```\n\nBuyers can then discover packages at `GET /prepaid/packages` and purchase at `POST /prepaid/purchase`.\n\n#### Security\n\n- HMAC-SHA256 signatures prevent credential forgery\n- Constant-time comparison prevents timing attacks\n- Credentials are scoped per buyer-seller pair\n- Server-side cache (5 min TTL) for repeat verification\n\n---\n\n## Security — Built for Real Money\n\nYour agent holds private keys and moves real USDC. Security is not a feature — it's the foundation.\n\n**4 rounds of internal security review** · 24 issues found, **24 fixed** · **109 dedicated security TDD tests** · 775+ total tests · 90%+ coverage\n\n### 6-Layer Budget Protection\n\n| Layer | What It Does | Default |\n|-------|-------------|---------|\n| Per-transaction cap | Hard ceiling on single payment | **$5.00** |\n| Per-minute rate limit | Dollar + count cap | **$2.00 / 5 txns** |\n| Daily spend cap | Maximum daily spend | **$10.00** (ceiling: $1,000) |\n| Circuit breaker | Auto-stop after consecutive failures | **3 fails → 60s cooldown** |\n| Auto-rollback | Instant reversal on failed payments | Always on |\n| Key redaction | Private keys scrubbed from all logs | Always on |\n\n### Architecture Principles\n\n| Principle | How |\n|-----------|-----|\n| **Non-custodial** | Private keys never leave your machine. No server. No account. |\n| **Seller-No-Key** | Sellers only need a public address — zero private key risk |\n| **Wallet encryption** | PBKDF2-HMAC-SHA256 (480K iterations) + Fernet/AES |\n| **Zero telemetry** | No tracking, no IP logging, no analytics. Period. |\n| **Replay protection** | Timestamp + nonce + persistent tx_hash dedup (SQLite) |\n| **SSRF protection** | Blocks private IPs, non-HTTPS, reserved ranges |\n| **Header sanitization** | Strips Cookie, X-Forwarded-For, Authorization before proxy |\n\n### CI Pipeline (Every PR)\n\nCodeQL · Trivy · pip-audit · Semgrep · 775+ tests · 90%+ coverage · OpenSSF Scorecard\n\n---\n\n## Protocol\n\n```\nHTTP/1.1 402 Payment Required\nWWW-Authenticate: x402 chain=\"solana\" token=\"USDC\" amount=\"0.05\" address=\"...\"\n\n→ Client pays on-chain, retries with:\n\nGET /data HTTP/1.1\nAuthorization: x402 tx_hash=\"abc123...\" chain=\"solana\" payer_address=\"...\" request_id=\"...\"\n\n→ Server verifies on-chain → 200 OK\n```\n\nCompatible with the [Coinbase x402](https://github.com/coinbase/x402) open payment standard.\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  Your Agent (LangChain / CrewAI / AutoGen / any Python)        │\n│  ┌──────────────────────────────────────────────────────────┐   │\n│  │  ag402_core.enable()  ← monkey-patches httpx / requests  │   │\n│  └──────────────┬───────────────────────────────────────────┘   │\n│                 │ HTTP request                                   │\n│                 ▼                                                │\n│  ┌──────────────────────────┐    ┌────────────────────────┐     │\n│  │  x402 Middleware         │───▶│  BudgetGuard (6 layers)│     │\n│  │  Intercepts 402 response │    │  Circuit Breaker       │     │\n│  └──────────┬───────────────┘    └────────────────────────┘     │\n│             │ Pay                                                │\n│             ▼                                                    │\n│  ┌──────────────────────────┐    ┌────────────────────────┐     │\n│  │  SolanaAdapter           │───▶│  RPC Failover          │     │\n│  │  USDC transfer + verify  │    │  Exponential backoff   │     │\n│  └──────────┬───────────────┘    └────────────────────────┘     │\n│             │ tx_hash                                            │\n│             ▼                                                    │\n│  Retries with: Authorization: x402 tx_hash=\"...\" chain=\"solana\" │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│  Seller Gateway  (ag402 serve)                                  │\n│  ┌────────────┐  ┌──────────────┐  ┌────────────────────────┐  │\n│  │ 402 + x402 │  │ On-chain     │  │ Replay Guard           │  │\n│  │ Challenge   │  │ Verification │  │ Rate Limiter           │  │\n│  └────────────┘  └──────────────┘  │ Header Sanitization    │  │\n│                                     └────────────────────────┘  │\n│  → Proxies to your API (unchanged)                              │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n[Full architecture diagrams \u0026 state machines → docs/architecture_state.md](docs/architecture_state.md)\n\n---\n\n## Packages\n\n| Package | Registry | Role |\n|---------|----------|------|\n| [`open402`](https://pypi.org/project/open402/) | [![PyPI](https://img.shields.io/pypi/v/open402)](https://pypi.org/project/open402/) | Protocol standard — **zero dependencies** |\n| [`ag402-core`](https://pypi.org/project/ag402-core/) | [![PyPI](https://img.shields.io/pypi/v/ag402-core)](https://pypi.org/project/ag402-core/) | Payment engine + CLI + wallet (buyer) |\n| [`ag402-mcp`](https://pypi.org/project/ag402-mcp/) | [![PyPI](https://img.shields.io/pypi/v/ag402-mcp)](https://pypi.org/project/ag402-mcp/) | Reverse-proxy gateway (seller) — **zero code changes** |\n| [`ag402-client-mcp`](https://pypi.org/project/ag402-client-mcp/) | [![PyPI](https://img.shields.io/pypi/v/ag402-client-mcp)](https://pypi.org/project/ag402-client-mcp/) | MCP client for AI tools (buyer) |\n| [`@ag402/fetch`](https://www.npmjs.com/package/@ag402/fetch) | [![npm](https://img.shields.io/npm/v/@ag402/fetch)](https://www.npmjs.com/package/@ag402/fetch) | TypeScript/Node.js buyer SDK — **zero runtime deps** |\n\n---\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `ag402 init` | Non-interactive setup — for AI agents (zero prompts) |\n| `ag402 setup` | Interactive wizard — for humans |\n| `ag402 demo` | Full E2E payment demo |\n| `ag402 run -- \u003ccmd\u003e` | Run any script with automatic x402 payment |\n| `ag402 pay \u003curl\u003e` | Single paid request |\n| `ag402 serve` | Start payment gateway (seller) |\n| `ag402 install \u003ctool\u003e` | One-command MCP setup (claude-code / cursor / openclaw) |\n| `ag402 status` | Dashboard: balance, budget, security |\n| `ag402 balance` | Quick balance check |\n| `ag402 history` | Transaction history |\n| `ag402 doctor` | Environment health check |\n| `ag402 upgrade` | Migrate test → production |\n| `ag402 export` | Export history (JSON/CSV) |\n| `ag402 prepaid buy \u003curl\u003e \u003cpkg\u003e` | Purchase a prepaid credit pack |\n| `ag402 prepaid status` | View all prepaid credentials (calls left / expiry) |\n| `ag402 prepaid purge` | Remove expired or depleted credentials |\n| `ag402 prepaid recover \u003curl\u003e` | Recover a credential after gateway timeout |\n| `ag402 prepaid pending` | Show any in-flight (unconfirmed) purchase |\n\n[Full CLI reference → llms.txt](llms.txt) (AI-readable, paste into your agent's context)\n\n---\n\n## Documentation\n\n| Resource | Description |\n|----------|-------------|\n| **[llms.txt](llms.txt)** | AI-readable CLI reference — paste into your agent's context |\n| **[TypeScript SDK README](sdk/typescript/README.md)** | `@ag402/fetch` — Node.js/Bun/Deno buyer SDK |\n| **[Claude Code Guide](docs/guide-claude-code.md)** | Step-by-step MCP integration |\n| **[Cursor Guide](docs/guide-cursor.md)** | Step-by-step MCP integration |\n| **[OpenClaw Guide](docs/guide-openclaw.md)** | Native Skill + MCP integration |\n| **[Architecture](docs/architecture_state.md)** | System diagrams \u0026 state machines |\n| **[x402 Protocol Spec](docs/x402_protocol_spec.md)** | Full protocol specification |\n| **[OpenClaw Skill](adapters/openclaw/ag402-skill/)** | Native OpenClaw skill definition |\n| **[Localnet Guide](docs/guide-localnet.md)** | Local Solana validator setup |\n| **[SECURITY](SECURITY.md)** | Security policy \u0026 audit history |\n| **[CHANGELOG](CHANGELOG.md)** | Version history |\n| **[CONTRIBUTING](CONTRIBUTING.md)** | Contribution guide |\n\n---\n\n## Troubleshooting\n\n### ag402 doctor\n\nRun `ag402 doctor` first. It validates your environment end-to-end and prints a PASS/FAIL report with actionable fix suggestions for each issue:\n\n- Python version and required package installation\n- Solana cryptography dependencies (`solana`, `solders`, `spl-token`)\n- RPC connectivity (pings your configured endpoint and any backups)\n- Wallet file presence and integrity (detects corruption or missing keys)\n- Budget configuration sanity (flags limits set to $0 or above the $1,000 ceiling)\n\n```bash\nag402 doctor          # full health check\n```\n\nIf `ag402 doctor` passes but you still see errors, enable verbose mode: `AG402_DEBUG=1 ag402 run -- python my_agent.py`\n\n### Configuration priority\n\nAg402 resolves configuration in this order (highest priority wins):\n\n1. **Environment variables** — e.g. `X402_DAILY_LIMIT=50`, `AG402_RPC_URL=https://...`\n2. **`.env` file** — loaded from the current working directory at process start\n3. **Code defaults** — the values baked into `ag402-core` itself (e.g. $10 daily limit)\n\nEnvironment 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`.\n\n### Common errors\n\n| Error | Cause | Fix |\n|-------|-------|-----|\n| `ag402: command not found` | PATH not updated after `pip install` | Run `python -m ag402_core.cli` or restart your shell |\n| `Wallet file not found` | Setup not completed | Run `ag402 setup` (interactive) or `ag402 init` (non-interactive) |\n| `Insufficient wallet balance` | Test wallet is empty | Run `ag402 init` — auto-deposits $100 test USDC |\n| `Cannot connect to Solana network` | RPC unreachable | Use `ag402 demo` (mock, no network needed) or `ag402 demo --localnet` |\n| `Solana RPC timed out` | Devnet congestion | Retry, or switch to `ag402 demo --localnet` for stable local testing |\n| `Incorrect wallet password` | Mistyped password | Set `AG402_UNLOCK_PASSWORD=yourpass` to skip the prompt |\n| `Daily spending limit reached` | Over `X402_DAILY_LIMIT` | Run `ag402 config` to view limits; set `X402_DAILY_LIMIT=100` to increase |\n| `Missing dependency: solana` | Solana deps not installed | Run `pip install 'ag402-core[crypto]'` for on-chain payments |\n\n### Still stuck?\n\n- `ag402 doctor` — full environment health check with actionable suggestions\n- [GitHub Issues](https://github.com/AetherCore-Dev/ag402/issues) — search existing issues or file a new one\n- Set `AG402_DEBUG=1` for verbose output including full stack traces\n\n---\n\n## Community\n\n- [GitHub Discussions](https://github.com/AetherCore-Dev/ag402/discussions) — questions, ideas, show \u0026 tell\n- [Issue Tracker](https://github.com/AetherCore-Dev/ag402/issues) — bug reports, feature requests\n- [Contributing Guide](CONTRIBUTING.md) — PRs welcome, see \"Good First Issues\"\n\n---\n\n## Roadmap\n\n| Milestone | Status | Description |\n|-----------|--------|-------------|\n| ✅ Solana USDC payments | **Shipped** | Standard x402 on-chain payments (~0.5s) |\n| ✅ Prepaid system | **Shipped** | HMAC credentials, ~1ms, zero gas per call |\n| ✅ Claude Code / Cursor / OpenClaw | **Shipped** | One-command install, native MCP support |\n| ✅ 4 internal security reviews | **Shipped** | 24/24 issues fixed, 775+ tests |\n| ✅ **TypeScript SDK** | **Shipped** | [`@ag402/fetch`](https://www.npmjs.com/package/@ag402/fetch) — zero-dep Node.js/Bun/Deno buyer SDK. 100 tests, dual ESM+CJS, full protocol utilities |\n| ✅ **`@ag402/solana`** | **Shipped** | [`@ag402/solana`](https://www.npmjs.com/package/@ag402/solana) — real Solana USDC `PaymentProvider` for TypeScript. 17 tests, dual ESM+CJS, mainnet/devnet guards |\n| 🔜 Multi-chain | Planned | Base, Polygon, Arbitrum USDC support |\n| 🔜 Stripe fallback | Planned | Fiat payment fallback for non-crypto users |\n| 🔜 Dashboard | Planned | Web UI for sellers — revenue, analytics, API keys |\n\n---\n\n## License\n\n[MIT](LICENSE) — Open source, free forever.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAetherCore-Dev%2Fag402","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAetherCore-Dev%2Fag402","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAetherCore-Dev%2Fag402/lists"}