使用说明

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包，零依赖

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

你是。..	您的操作	代码更改
代理用户（LangChain、CrewAI、AutoGen、任何Python代理）	`pip install ag402-core && ag402 run -- python my_agent.py`	零 --您的代理代码未被修改
Types/Node.js代理开发人员	`npm install @ag402/fetch` --包裹 `fetch()` 随着 `createX402Fetch()`	~2条线 --替换 `fetch` 随着 `createX402Fetch(...)`
克劳德代码/光标用户	`ag402 install claude-code` （或 `cursor`)	零 --MCP工具自动出现
OpenClaw用户	`ag402 install openclaw`	零 --原生技能+MCP，自动配置
API卖方（将API货币化）	`ag402 serve --target http://your-api:8000 --price 0.05 --address <Addr>`	零 --反向代理处理一切
MCP服务器开发人员	`ag402 serve --target http://your-mcp:3000 --price 0.01 --address <Addr>`	零 --包装您现有的MCP服务器，即时支付墙

没有配置文件。没有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 <Addr>

或者零安装（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工具：

MCP工具	它的作用
`fetch_with_autopay`	HTTP请求→ 自动支付402 API
`wallet_status`	检查USDC余额+预算使用情况
`transaction_history`	查看最近的付款

开爪实现了最深入的集成——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 <YourSolanaAddress>

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

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

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

演出

度量	值	如何
支付延迟	~0.5秒	`confirmed` 最终性——比之前快26倍 `finalized` （约13秒）
预付延迟	~1ms	本地HMAC-SHA256——完全没有链上调用
非402开销	零	仅检查状态代码——不读取正文、不分配、不延迟
RPC弹性	多端点	指数级回退→ 自动故障转移到备份RPC→ 断路器
交付保证	异步重试	付款成功，但上游失败？后台工作人员重试回退

预付费系统——从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预付等级

套餐	时长	通话时间	价格（美元）	每次通话费用
起始	3天	100	1.50美元	0.015美元
基本	7天	500	5.00	0.010美元
专业	30天	1000	8.00美元	0.008美元
业务	365天	5000	35.00美元	0.007美元
企业	730天	10000	60.00美元	0.006美元

运作原理

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

显示包裹价格和卖家地址
问 Confirm payment? [Y/n]
自动在链上广播USDC
将凭据存储在 ~/.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 <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

卖家设置

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

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

安全

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

安全——为真钱打造

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

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

6层预算保护

图层	功能	默认值
每笔交易上限	单笔付款的硬上限	$5.00
每分钟费率限制	美元+计数上限	2.00美元/5txns
每日支出上限	每日最大支出	$10.00 （上限：1000美元）
断路器	连续故障后自动停止	3失败→ 60s冷却
自动回滚	失败付款时立即撤销	始终开启
密钥编辑	从所有日志中删除私钥	始终打开

建筑原理

原理	如何
无监护权的	私钥永远不会离开你的机器。没有服务器。没有账号。
卖家无密钥	卖家只需要一个公共地址——零私钥风险
钱包加密	PBKDF2-HMAC-SHA256（480K迭代）+Fernet/AES
零遥测	没有跟踪，没有IP记录，没有分析。期间。
重放保护	时间戳+随机数+持久tx_hash去重（SQLite）
SSRF保护	阻止私有IP、非HTTPS、保留范围
表头净化	剥离Cookie，X-Forwarded-For，代理前授权

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

包裹

包	注册表	角色
`open402`		协议标准-- 零依赖性
`ag402-core`		支付引擎+CLI+钱包（买家）
`ag402-mcp`		反向代理网关（卖方）-- 零代码更改
`ag402-client-mcp`		人工智能工具MCP客户端（买方）
`@ag402/fetch`		Types/Node.js买家SDK-- 零运行时间deps

CLI 参考

命令	描述
`ag402 init`	非交互式设置——用于AI代理（无提示）
`ag402 setup`	交互式向导——面向人类
`ag402 demo`	完整的E2E支付演示
`ag402 run -- <cmd>`	运行任何带有自动x402支付的脚本
`ag402 pay <url>`	单次付费请求
`ag402 serve`	启动支付网关（卖家）
`ag402 install <tool>`	一个命令MCP设置（claude代码/光标/openclaw）
`ag402 status`	仪表板：余额、预算、安全
`ag402 balance`	快速余额检查
`ag402 history`	交易历史
`ag402 doctor`	环境健康检查
`ag402 upgrade`	迁移测试→ 生产
`ag402 export`	导出历史记录（JSON/CSV）
`ag402 prepaid buy <url> <pkg>`	购买预付信用包
`ag402 prepaid status`	查看所有预付费凭证（通话剩余/到期）
`ag402 prepaid purge`	删除过期或耗尽的凭据
`ag402 prepaid recover <url>`	网关超时后恢复凭据
`ag402 prepaid pending`	显示任何机上（未确认）购买

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

文档

资源	描述
llms.txt	AI可读CLI参考——粘贴到代理的上下文中
TypeScript SDK自述	`@ag402/fetch` --Node.js/Bun/Deno买家SDK
克劳德代码指南	逐步集成MCP
光标指南	逐步集成MCP
OpenClaw指南	本土技能+MCP集成
建筑	系统图和状态机
x402协议规范	完整协议规范
开放式法律技能	原生OpenClaw技能定义
局域网指南	本地Solana验证器设置
安全	安全策略和审计历史
更新日志	版本历史
贡献	贡献指南

故障排除

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按以下顺序解析配置（最高优先级获胜）：

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

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

常见错误

错误	原因	修复
`ag402: command not found`	PATH在之后未更新 `pip install`	快跑 `python -m ag402_core.cli` 或重新启动shell
`Wallet file not found`	安装未完成	运行 `ag402 setup` （交互式）或 `ag402 init` （非交互式）
`Insufficient wallet balance`	测试钱包为空	运行 `ag402 init` --汽车存款$100测试USDC
`Cannot connect to Solana network`	RPC无法访问	使用 `ag402 demo` （模拟，无需网络）或 `ag402 demo --localnet`
`Solana RPC timed out`	Devnet拥塞	重试，或切换到 `ag402 demo --localnet` 用于稳定的本地测试
`Incorrect wallet password`	密码输入错误	设置 `AG402_UNLOCK_PASSWORD=yourpass` 跳过提示
`Daily spending limit reached`	完毕 `X402_DAILY_LIMIT`	快跑 `ag402 config` 查看限制；集 `X402_DAILY_LIMIT=100` 增加
`Missing dependency: solana`	Solana deps未安装	运行 `pip install 'ag402-core[crypto]'` 用于链上支付

还在卡住吗？

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

社区

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

路线图

里程碑	状态	描述
✅ 索拉纳USDC付款	已发货	标准x402链上支付（~0.5秒）
✅ 预付费系统	已发货	HMAC凭据，约1ms，每次呼叫零气体
✅ 克劳德代码/光标/OpenClaw	已发货	一键安装，原生MCP支持
✅ 4次内部安全审查	已发货	24/24问题已修复，775+次测试
✅ TypeScript SDK	已发货	`@ag402/fetch` --zero-dep Node.js/Bun/Deno买家SDK。100次测试，双ESM+CJS，全协议实用程序
✅ `@ag402/solana`	已发货	`@ag402/solana` --真正的索拉纳USDC `PaymentProvider` 对于TypeScript。17个测试，双ESM+CJS，主网/开发网防护
🔜 多链	计划中	基础、多边形、Arbitrum USDC支持
🔜 条纹回退	计划中	非加密用户的菲亚特支付回退
🔜 Dashboard	Planned	面向卖家的Web UI-收入、分析、API密钥

许可证

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

使用说明

Ag402

为什么选择Ag402

零摩擦

开放标准

战斗测试

快速燃烧

安全第一

通用兼容性

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

现在试试

已投入生产

令牌RugCheck

DeepBlue API --特色示例

运作原理

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

框架示例

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

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

对于API卖家-零代码更改

演出

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

5预付等级

运作原理

快速入门（买方）

卖家设置

安全

安全——为真钱打造

6层预算保护

建筑原理

CI管道（每个PR）

协议

建筑

包裹

CLI 参考

文档

故障排除

ag402医生

配置优先

常见错误

还在卡住吗？

社区

路线图

许可证

相关 MCP

Markdown微信排版发布工具

谷歌表格集成工具

JavaScript逆向标准化服务

OBS控制服务器

Kali Linux MCP服务器

Metabase MCP 服务器