Ag402 MCP

Ag402

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

______________________________________________________________________

Ag402 是支付层 Coinbase x402 协议。它使人工智能代理自动支付API调用的费用——在索拉纳，以USDC计算，无代码更改。

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

非监禁。零遥测。已经在生产中。

______________________________________________________________________

为什么选择Ag402

零摩擦

• 买家、卖家和MCP开发人员无需更改代码
• 开始付款的一个命令： ag402 run -- python my_agent.py
• 开始销售的一个命令： ag402 serve --target ... --price ... --address ...
• 安装MCP工具的一个命令： ag402 install claude-code
• 没有配置文件，没有API密钥，没有帐户，没有注册
• Colab一键演示 --在浏览器中尝试，无需安装

开放标准

• 实现 Coinbase x402 --新兴的HTTP支付标准
• MIT许可、完全开源、可扩展的协议层(open402)零依赖
• AI原生文档 --船舶与 llms.txt 因此LLM代理可以本地读取完整的CLI参考

战斗测试

• 令牌RugCheck — 在Solana主网上直播 实际美元支付
• 775+次测试，90%以上的覆盖率，4轮内部安全审查（24/24问题已修复）
• 多端点RPC故障转移+断路器+异步传递重试

快速燃烧

• ~0.5秒 标准付款(confirmed 结局，而不是13秒 finalized)
• ~1ms 预付费支付（本地HMAC，无链上呼叫）
• 非402请求的开销为零——无正文读取，无分配
• 连接池、延迟导入、SQLite WAL模式

安全第一

• 6层预算保护——每tx/每分钟/每天/断路器/回滚/密钥编辑
• 非保管-私钥永远不会离开您的机器
• 卖家无密钥——卖家只需要一个公共地址，零私钥风险
• 零遥测——无跟踪、无IP记录、无分析
• 钱包加密：PBKDF2（480K iter）+AES
• CI:CodeQL+Trivy+pip审计+Semgrep+OpenSSF记分卡

通用兼容性

• 克劳德代码、光标、克劳德桌面——MCP自动配置
• OpenClaw-- 本土技能 （SKILL.md+TOOLS.md+SKILL.py），而不仅仅是MCP
• LangChain、AutoGen、CrewAI、语义内核——自动工作
• 任何使用Python的代理 httpx 或 requests --零变化
• Types/Node.js代理 — @ag402/fetch npm包，零依赖

______________________________________________________________________

零代码更改。为了每个人。

没有配置文件。没有API密钥。没有账户。代码更改最少。

______________________________________________________________________

现在试试

Python（零代码更改）：

pip install ag402-core
ag402 setup      # Interactive wizard: creates wallet, selects network, configures keys
ag402 demo       # Watch the full payment flow end-to-end

对于非交互式/CI使用，请运行 ag402 init 相反，零提示，自动创建带有100美元测试USDC的钱包。

Types/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

克劳德代码/光标：

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

出售您的API（零代码更改）：

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

或者零安装（Python）： 

______________________________________________________________________

已投入生产

令牌RugCheck

在Solana主网上直播。 人工智能代理付费 0.02美元直流电 在购买代币之前，每次审计都会检测到拉客行为。

• 三层审核：机器判定→ LLM分析→ 原始链上证据
• 卖家: ag402 serve -审核API的零代码更改
• 买方: ag402_core.enable() --代理商自动支付，零代码更改
• 立即尝试: 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 --特色示例

实时BTC/ETH/SOL交易信号 对于AI代理，请访问 每次通话0.001美元 --非常适合演示x402小额支付。

• 超低成本：每次API调用0.001美元-非常适合测试和演示
• 真实交易信号：BTC、ETH、SOL市场分析和预测
• 卖家：DeepBlue使用x402协议进行即时小额支付
• 买方：代理通过ag402自动支付——无需更改代码
• 生态系统整合：在ag402文档中作为展示示例

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

不是演示。真正的USDC，真正的Solana主网，真正的用户，已经在运行。

______________________________________________________________________

运作原理

对于代理用户——零代码更改

您的代理已在使用 httpx 或 requests 引擎盖下。Ag402透明地修补它们：

# 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()

就是这样。现在每个HTTP 402响应都被拦截了→ paid → 自动重试。您的代理代码将保留 完全未受影响.

适用于 LangChain, 自动生成, CrewAI, 语义内核，以及任何基于 httpx 或 requests.

框架示例

LangChain — tool functions call x402 APIs, no payment code needed

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

完整示例： examples/langchain_integration.py --开始 examples/start_local_demo.py 首先是一个独立的本地演示。

AutoGen — register tools on UserProxyAgent, ag402 patches the HTTP layer

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

完整示例： examples/autogen_integration.py --开始 examples/start_local_demo.py 第一。

CrewAI — decorate tools with @tool, crew runs with no payment code

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

完整示例： examples/crewai_integration.py --开始 examples/start_local_demo.py 第一。

对于克劳德代码/光标/OpenClaw——一个命令

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

重新启动工具。出现三个MCP工具：

开爪 实现了最深入的集成——Ag402作为 原生OpenClaw技能 (SKILL.md + TOOLS.md + skill.py)，而不是包装纸。该技能在OpenClaw的技能系统中本地注册，具有完整的工具定义、预付费支持和自动回退功能。

对于Types/Node.js开发人员——两行

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

交换 InMemoryWallet 用你自己的 Wallet 实施与 MockPaymentProvider 随着 @ag402/solana 用于真实的链上USDC支付。零运行时依赖性——Node.js 18+、Bun、Deno。

对于API卖家-零代码更改

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

您现有的API在反向代理后不受影响地运行。代理人：

• 退货 402+x402挑战 未支付的请求
• 验证链上的付款 （不需要私钥——卖家只提供一个公共地址）
• 代理通过您的API支付请求
• 处理重放保护、速率限制、报头净化

MCP服务器开发人员：相同的命令，相同的结果。包装您的MCP服务器，立即获得付费墙。

______________________________________________________________________

演出

预付费系统——从500ms到1ms

问题： 标准x402付款要求每个API呼叫都有一笔链上索拉纳交易（约0.5秒+天然气费）。对于每小时拨打数百个电话的高频代理来说，这会增加延迟和成本。

解决方案： 购买带有链上支付的预付信用包，然后使用HMAC凭据进行后续通话-- 零气体，约1ms延迟.

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预付等级

运作原理

1. 买方 购买预付包裹→ 一个索拉纳tx→ 接收HMAC凭据
2. 每次API调用 包括 X-Prepaid-Credential 头球→ 服务器在本地验证HMAC（~1ms）
3. 没有链上tx 每次通话所需→ 首次购买后零天然气费用
4. 自动回退 预付信用额度用尽时，按照标准x402付款

快速入门（买方）

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

# Check your credentials
ag402 prepaid status

可用包ID： p3d_100 （起动机）， p7d_500 （基本）， p30d_1000 （Pro）， p365d_5000 （商业）， p730d_10k （企业）。

在 生产模式 （实际美元）， ag402 prepaid buy 将：

1. 显示包裹价格和卖家地址
2. 问 Confirm payment? [Y/n]
3. 自动在链上广播USDC
4. 将凭据存储在 ~/.ag402/prepaid_credentials.json

如果支付广播后网关超时，您的凭据不会丢失——请重试或恢复：

# 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  

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

卖家设置

# Start gateway with prepaid support
ag402 serve --target http://localhost:8000 \
            --price 0.01 \
            --address  \
            --prepaid-signing-key 

# Or via environment variable
AG402_PREPAID_SIGNING_KEY= ag402 serve --target http://localhost:8000 --price 0.01 --address 

然后，买家可以在以下网址发现包裹 GET /prepaid/packages 并在以下网址购买 POST /prepaid/purchase.

安全

• HMAC-SHA256签名防止凭证伪造
• 持续的时间比较可防止计时攻击
• 凭证的范围按买方-卖方对确定
• 服务器端缓存（5分钟TTL）用于重复验证

______________________________________________________________________

安全——为真钱打造

您的代理人持有私钥并移动真实的USDC。安全不是一个功能，而是基础。

4轮内部安全审查 ·发现24个问题， 24固定 · 109个专用安全TDD测试 ·775+总测试·90%+覆盖率

6层预算保护

建筑原理

CI管道（每个PR）

CodeQL·Trivy·pip审计·Semgrep·775+测试·90%+覆盖率·OpenSSF记分卡

______________________________________________________________________

协议

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

与兼容 Coinbase x402 开放式支付标准。

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────────────────┐
│  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)                              │
└─────────────────────────────────────────────────────────────────┘

完整的架构图和状态机→ docs/architecture_state.md

______________________________________________________________________

包裹

______________________________________________________________________

CLI 参考

完整CLI参考→ llms.txt （AI可读，粘贴到代理的上下文中）

______________________________________________________________________

文档

______________________________________________________________________

故障排除

ag402医生

跑 ag402 doctor 第一。它端到端验证您的环境，并打印一份PASS/FAIL报告，其中包含每个问题的可操作修复建议：

• Python版本和所需的软件包安装
• Solana加密依赖关系(solana, solders, spl-token)
• RPC连接（ping您配置的端点和任何备份）
• 钱包文件存在和完整性（检测损坏或丢失的密钥）
• 预算配置健全（标记限制设置为0美元或高于1000美元上限）

ag402 doctor          # full health check

如果 ag402 doctor 通过但仍然看到错误，请启用详细模式： AG402_DEBUG=1 ag402 run -- python my_agent.py

配置优先

Ag402按以下顺序解析配置（最高优先级获胜）：

1. 环境变量 --例如。 X402_DAILY_LIMIT=50, AG402_RPC_URL=https://...
2. .env 文件 --进程启动时从当前工作目录加载
3. 代码默认值 --融入其中的价值观 ag402-core 本身（例如每天10美元的限额）

环境变量始终覆盖 .env 价值观。 .env 值始终覆盖代码默认值。要验证哪些值处于活动状态，请运行 ag402 status （显示已解决的限制和配置源）或 ag402 doctor.

常见错误

还在卡住吗？

• ag402 doctor --全面的环境健康检查，并提出可行的建议
• --搜索现有问题或提交新问题
• 集 AG402_DEBUG=1 用于包括完整堆栈跟踪的详细输出

______________________________________________________________________

社区

• --问题、想法、展示和讲述
• 问题追踪 --错误报告、功能请求
• 贡献指南 --欢迎公关，请参阅“好的第一期”

______________________________________________________________________

路线图

______________________________________________________________________

许可证

麻省理工学院 --开源，永远免费。