agentwallet
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseAgentWallet
AgentWallet
AgentWallet provides server wallets for AI agents. Wallets are provisioned after email OTP verification. All signing happens server-side and is policy-controlled.
AgentWallet为AI Agent提供服务端钱包。钱包需通过邮箱OTP验证后才能开通。所有签名操作在服务端完成,并受策略控制。
TL;DR - Quick Reference
快速参考(TL;DR)
FIRST: Check if already connected by reading . If file exists with , you're connected - DO NOT ask user for email.
~/.agentwallet/config.jsonapiTokenNeed to connect (no config file)? Ask user for email → POST to → user enters OTP → POST to → save API token.
/api/connect/start/api/connect/completex402 Payments? Use the ONE-STEP endpoint (recommended) - just send target URL + body, server handles everything.
/x402/fetch首先:检查是否已连接,读取文件。如果文件存在且包含,说明已连接——请勿再向用户索要邮箱。
~/.agentwallet/config.jsonapiToken需要连接(无配置文件)? 向用户索要邮箱 → 发送POST请求至 → 用户输入OTP → 发送POST请求至 → 保存API令牌。
/api/connect/start/api/connect/completex402支付? 使用推荐的一键式端点——只需发送目标URL和请求体,服务端会处理所有操作。
/x402/fetchx402/fetch - ONE-STEP PAYMENT PROXY (RECOMMENDED)
x402/fetch - 一键式支付代理(推荐)
This is the simplest way to call x402 APIs. Send the target URL and body - the server handles 402 detection, payment signing, and retry automatically.
bash
curl -s -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/x402/fetch" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://enrichx402.com/api/exa/search","method":"POST","body":{"query":"AI agents","numResults":3}}'That's it! The response contains the final API result:
json
{
"success": true,
"response": {
"status": 200,
"body": {"results": [...]},
"contentType": "application/json"
},
"payment": {
"chain": "eip155:8453",
"amountFormatted": "0.01 USDC",
"recipient": "0x..."
},
"paid": true,
"attempts": 2,
"duration": 1234
}这是调用x402 API最简单的方式。 发送目标URL和请求体即可,服务端会自动处理402检测、支付签名和重试逻辑。
bash
curl -s -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/x402/fetch" \
-H "Authorization: Bearer TOKEN" \
-H "Content-Type: application/json" \
-d '{"url":"https://enrichx402.com/api/exa/search","method":"POST","body":{"query":"AI agents","numResults":3}}'操作完成! 响应结果包含最终的API返回数据:
json
{
"success": true,
"response": {
"status": 200,
"body": {"results": [...]},
"contentType": "application/json"
},
"payment": {
"chain": "eip155:8453",
"amountFormatted": "0.01 USDC",
"recipient": "0x..."
},
"paid": true,
"attempts": 2,
"duration": 1234
}x402/fetch Request Options
x402/fetch 请求选项
| Field | Type | Required | Description |
|---|---|---|---|
| string | Yes | Target API URL (must be HTTPS in production) |
| string | No | HTTP method: GET, POST, PUT, DELETE, PATCH (default: GET) |
| object | No | Request body (auto-serialized to JSON) |
| object | No | Additional headers to send |
| string | No | |
| boolean | No | Preview payment cost without paying |
| number | No | Request timeout in ms (default: 30000, max: 120000) |
| string | No | For deduplication |
| 字段 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| string | 是 | 目标API URL(生产环境必须为HTTPS) |
| string | 否 | HTTP方法:GET、POST、PUT、DELETE、PATCH(默认:GET) |
| object | 否 | 请求体(自动序列化为JSON格式) |
| object | 否 | 需额外发送的请求头 |
| string | 否 | |
| boolean | 否 | 预览支付成本但不实际支付 |
| number | 否 | 请求超时时间(毫秒,默认:30000,最大值:120000) |
| string | 否 | 用于请求去重 |
Dry Run (Preview Cost)
试运行(预览成本)
Add to the request body. Returns payment details without executing:
"dryRun": truejson
{
"success": true,
"dryRun": true,
"payment": {
"required": true,
"chain": "eip155:8453",
"amountFormatted": "0.01 USDC",
"policyAllowed": true
}
}在请求体中添加,返回支付详情但不执行实际支付:
"dryRun": truejson
{
"success": true,
"dryRun": true,
"payment": {
"required": true,
"chain": "eip155:8453",
"amountFormatted": "0.01 USDC",
"policyAllowed": true
}
}Error Codes
错误码
| Code | HTTP | Description |
|---|---|---|
| 400 | URL malformed or blocked (localhost, internal IPs) |
| 403 | Policy check failed (amount too high, etc.) |
| 403 | Wallet is frozen |
| 504 | Target API timed out |
| 502 | Target API returned 5xx error |
| 402 | Payment was rejected by target API |
| 400 | No compatible payment network |
| 代码 | HTTP状态码 | 描述 |
|---|---|---|
| 400 | URL格式错误或被拦截(如本地主机、内部IP) |
| 403 | 策略校验失败(如金额过高) |
| 403 | 钱包已冻结 |
| 504 | 目标API请求超时 |
| 502 | 目标API返回5xx错误 |
| 402 | 支付被目标API拒绝 |
| 400 | 无兼容的支付网络 |
Config File Reference
配置文件参考
Store credentials at :
~/.agentwallet/config.jsonjson
{
"username": "your-username",
"email": "your@email.com",
"evmAddress": "0x...",
"solanaAddress": "...",
"apiToken": "mf_...",
"moltbookLinked": false,
"moltbookUsername": null,
"xHandle": null
}| Field | Description |
|---|---|
| Your unique AgentWallet username |
| Email used for OTP verification |
| EVM wallet address |
| Solana wallet address |
| Fund API token for authenticated requests (starts with |
| Whether a Moltbook account is linked |
| Linked Moltbook username (if any) |
| X/Twitter handle from Moltbook (if linked) |
Security: Never commit to git. Set . Treat like a password.
chmod 600apiToken凭证存储在路径下:
~/.agentwallet/config.jsonjson
{
"username": "your-username",
"email": "your@email.com",
"evmAddress": "0x...",
"solanaAddress": "...",
"apiToken": "mf_...",
"moltbookLinked": false,
"moltbookUsername": null,
"xHandle": null
}| 字段 | 描述 |
|---|---|
| 你的AgentWallet唯一用户名 |
| 用于OTP验证的邮箱 |
| EVM钱包地址 |
| Solana钱包地址 |
| 用于鉴权请求的Fund API令牌(以 |
| 是否关联了Moltbook账户 |
| 关联的Moltbook用户名(如有) |
| 来自Moltbook的X/Twitter账号(如有关联) |
安全提示: 请勿将该文件提交至git仓库。设置权限为。请像对待密码一样保管。
chmod 600apiTokenConnect Flow
连接流程
Web flow: Ask user for email → direct to → user enters 6-digit OTP → page displays credentials (, , etc.). User should save the API token securely.
https://agentwallet.mcpay.tech/connect?email=EMAILAGENTWALLET_USERNAMEAGENTWALLET_API_TOKENAPI flow (for CLI/agents):
Step 1 - Send OTP:
bash
curl -X POST https://agentwallet.mcpay.tech/api/connect/start \
-H "Content-Type: application/json" \
-d '{"email":"your@email.com"}'Returns in response. For referrals, add to body.
username"ref":"REFERRER_USERNAME"Step 2 - Ask user for OTP, then complete:
bash
curl -X POST https://agentwallet.mcpay.tech/api/connect/complete \
-H "Content-Type: application/json" \
-d '{"username":"USERNAME_FROM_STEP_1","email":"your@email.com","otp":"USER_OTP"}'Returns , , . Save the for all wallet operations.
apiTokenevmAddresssolanaAddressapiToken网页流程: 向用户索要邮箱 → 跳转至 → 用户输入6位OTP → 页面显示凭证(、等)。用户需安全保存API令牌。
https://agentwallet.mcpay.tech/connect?email=EMAILAGENTWALLET_USERNAMEAGENTWALLET_API_TOKENAPI流程(适用于CLI/Agent):
步骤1 - 发送OTP:
bash
curl -X POST https://agentwallet.mcpay.tech/api/connect/start \
-H "Content-Type: application/json" \
-d '{"email":"your@email.com"}'响应结果中返回。若为推荐注册,可在请求体中添加。
username"ref":"REFERRER_USERNAME"步骤2 - 向用户索要OTP,完成连接:
bash
curl -X POST https://agentwallet.mcpay.tech/api/connect/complete \
-H "Content-Type: application/json" \
-d '{"username":"USERNAME_FROM_STEP_1","email":"your@email.com","otp":"USER_OTP"}'返回、、。保存用于后续所有钱包操作。
apiTokenevmAddresssolanaAddressapiTokenReferral & Airdrop Program
推荐与空投计划
Share your referral link:
https://agentwallet.mcpay.tech/connect?ref=YOUR_USERNAME&email=THEIR_EMAILBoth referrer and new agent earn airdrop points. Points: referral (200), first tx (50), daily active (10), weekly streak (100).
Tiers: Bronze (0-4, 1x), Silver (5-24, 1.5x), Gold (25-99, 2x), Diamond (100+, 3x).
Check rewards:
bash
curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/referrals \
-H "Authorization: Bearer FUND_API_TOKEN"分享你的推荐链接:
https://agentwallet.mcpay.tech/connect?ref=YOUR_USERNAME&email=THEIR_EMAIL推荐者和新用户均可获得空投积分。积分规则:推荐成功(200分)、首次交易(50分)、每日活跃(10分)、连续周活跃(100分)。
等级划分:青铜(0-4分,1倍倍率)、白银(5-24分,1.5倍倍率)、黄金(25-99分,2倍倍率)、钻石(100分以上,3倍倍率)。
查询奖励:
bash
curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/referrals \
-H "Authorization: Bearer FUND_API_TOKEN"Network Pulse
网络状态
Public network stats: — returns active agents, transaction counts, volume, trending APIs.
GET https://agentwallet.mcpay.tech/api/network/pulsePersonal stats (authenticated): — returns rank, transaction history, volume, referral info, streak.
GET https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/stats公开网络统计数据: —— 返回活跃Agent数量、交易次数、交易量及热门API信息。
GET https://agentwallet.mcpay.tech/api/network/pulse个人统计数据(需鉴权): —— 返回排名、交易历史、交易量、推荐信息及连续活跃天数。
GET https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/statsSkill Files
Skill文件
| File | URL |
|---|---|
| SKILL.md (this file) | |
| HEARTBEAT.md | |
| package.json (metadata) | |
| 文件 | 链接 |
|---|---|
| SKILL.md(本文档) | |
| HEARTBEAT.md | |
| package.json(元数据) | |
Heartbeat
心跳检测
Run periodically to check for skill updates, wallet status, and recent activity:
bash
curl https://agentwallet.mcpay.tech/heartbeat.mdBase URL:
https://agentwallet.mcpay.tech/api/v1定期运行以检查Skill更新、钱包状态及近期活动:
bash
curl https://agentwallet.mcpay.tech/heartbeat.md基础URL:
https://agentwallet.mcpay.tech/api/v1Authentication
鉴权方式
Use your Fund API token (starts with ) as:
mf_Authorization: Bearer FUND_API_TOKENCheck connection (public, no auth): — returns with wallet addresses if connected.
GET https://agentwallet.mcpay.tech/api/wallets/USERNAMEconnected: true/false使用你的Fund API令牌(以开头),格式为:
mf_Authorization: Bearer FUND_API_TOKEN检查连接状态(公开接口,无需鉴权): —— 返回,若已连接则同时返回钱包地址。
GET https://agentwallet.mcpay.tech/api/wallets/USERNAMEconnected: true/falseFunding Wallets
钱包充值
Direct users to to fund via Coinbase Onramp (card, bank, or Coinbase account). Supports Base (USDC) and Solana (SOL).
https://agentwallet.mcpay.tech/u/YOUR_USERNAMECheck balance after funding:
bash
curl https://agentwallet.mcpay.tech/api/wallets/USERNAME/balances \
-H "Authorization: Bearer FUND_API_TOKEN"引导用户访问,通过Coinbase Onramp进行充值(支持银行卡、银行账户或Coinbase账户)。支持Base链(USDC)和Solana链(SOL)。
https://agentwallet.mcpay.tech/u/YOUR_USERNAME充值后查询余额:
bash
curl https://agentwallet.mcpay.tech/api/wallets/USERNAME/balances \
-H "Authorization: Bearer FUND_API_TOKEN"Wallet Operations
钱包操作
Balances: (auth required)
GET /api/wallets/USERNAME/balancesActivity: (auth optional — authenticated sees all events, public sees limited). Event types: , , , .
GET /api/wallets/USERNAME/activity?limit=50otp.*policy.*wallet.action.*x402.authorization.signed余额查询: (需鉴权)
GET /api/wallets/USERNAME/balances活动记录: (可选鉴权——鉴权后可查看所有事件,未鉴权仅查看有限信息)。事件类型包括:、、、。
GET /api/wallets/USERNAME/activity?limit=50otp.*policy.*wallet.action.*x402.authorization.signedActions (Policy Controlled)
策略控制操作
EVM Transfer
EVM转账
bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/transfer" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"0x...","amount":"1000000","asset":"usdc","chainId":8453}'Fields: (address), (smallest units — ETH: 18 decimals, USDC: 6 decimals), ( or ), , (optional).
toamountasset"eth""usdc"chainIdidempotencyKeySupported USDC chains: Ethereum (1), Sepolia (11155111), Optimism (10), Polygon (137), Arbitrum (42161), Base (8453), Base Sepolia (84532).
bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/transfer" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"0x...","amount":"1000000","asset":"usdc","chainId":8453}'字段说明:(接收地址)、(最小单位——ETH:18位小数,USDC:6位小数)、(或)、、(可选)。
toamountasset"eth""usdc"chainIdidempotencyKey支持USDC的EVM链:以太坊(1)、Sepolia(11155111)、Optimism(10)、Polygon(137)、Arbitrum(42161)、Base(8453)、Base Sepolia(84532)。
Solana Transfer
Solana转账
bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/transfer-solana" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"RECIPIENT","amount":"1000000000","asset":"sol","network":"devnet"}'Fields: (address), (smallest units — SOL: 9 decimals, USDC: 6 decimals), ( or ), ( or ), (optional).
toamountasset"sol""usdc"network"mainnet""devnet"idempotencyKeybash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/transfer-solana" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"RECIPIENT","amount":"1000000000","asset":"sol","network":"devnet"}'字段说明:(接收地址)、(最小单位——SOL:9位小数,USDC:6位小数)、(或)、(或)、(可选)。
toamountasset"sol""usdc"network"mainnet""devnet"idempotencyKeyEVM Contract Call
EVM合约调用
bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/contract-call" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"0x...","data":"0x...","value":"0","chainId":8453}'bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/contract-call" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"to":"0x...","data":"0x...","value":"0","chainId":8453}'Sign Message
消息签名
bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/sign-message" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"chain":"solana","message":"hello"}'bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/sign-message" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{"chain":"solana","message":"hello"}'Solana Devnet Faucet
Solana测试网水龙头
Request free devnet SOL for testing. Sends 0.1 SOL to your Solana wallet on devnet. Rate limited to 3 requests per 24 hours.
bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/faucet-sol" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{}'Response:
{"actionId":"...","status":"confirmed","amount":"0.1 SOL","txHash":"...","explorer":"...","remaining":2}Response format for all actions:
{"actionId":"...","status":"confirmed","txHash":"...","explorer":"..."}申请免费的测试网SOL用于测试。向你的Solana测试网钱包发送0.1 SOL。每24小时最多请求3次。
bash
curl -X POST "https://agentwallet.mcpay.tech/api/wallets/USERNAME/actions/faucet-sol" \
-H "Authorization: Bearer TOKEN" -H "Content-Type: application/json" \
-d '{}'响应示例:
{"actionId":"...","status":"confirmed","amount":"0.1 SOL","txHash":"...","explorer":"...","remaining":2}所有操作的响应格式:
{"actionId":"...","status":"confirmed","txHash":"...","explorer":"..."}x402 Manual Flow (Advanced)
x402手动流程(进阶)
Use this only if you need fine-grained control. For most cases, use x402/fetch above.
仅当需要精细控制时使用此流程。大多数场景下推荐使用上述x402/fetch。
Protocol Versions
协议版本
| Version | Payment Header | Network Format |
|---|---|---|
| v1 | | Short names ( |
| v2 | | CAIP-2 ( |
| 版本 | 支付请求头 | 网络格式 |
|---|---|---|
| v1 | | 短名称( |
| v2 | | CAIP-2格式( |
Flow
流程
- Call target API → get 402 response. Payment info is in the HEADER (body may be empty
payment-required).{} - Sign: with
POST /api/wallets/USERNAME/actions/x402/pay. The{"requirement": "<header value or JSON>", "preferredChain": "evm"}field accepts both base64 strings and JSON objects.requirement - Retry original request with the header from response field and
usage.headervalue.paymentSignature
Signing endpoint: (x402/pay with SLASH, not dash)
/api/wallets/{USERNAME}/actions/x402/pay- 调用目标API → 收到402响应。支付信息位于请求头中(响应体可能为空
payment-required)。{} - 签名:发送POST请求至,请求体为
/api/wallets/USERNAME/actions/x402/pay。{"requirement": "<请求头值或JSON>", "preferredChain": "evm"}字段支持base64字符串或JSON对象。requirement - 使用响应中字段指定的请求头和
usage.header值,重试原请求。paymentSignature
签名端点: (注意使用斜杠而非短横线)
/api/wallets/{USERNAME}/actions/x402/paySign Request Options
签名请求选项
| Field | Type | Description |
|---|---|---|
| string or object | Payment requirement (base64 or JSON) |
| | Preferred blockchain |
| number | Specific EVM chain ID |
| string | For deduplication |
| boolean | Sign without storing (for testing) |
| 字段 | 类型 | 描述 |
|---|---|---|
| string或object | 支付要求(base64格式或JSON) |
| | 首选区块链 |
| number | 特定EVM链ID |
| string | 用于请求去重 |
| boolean | 仅签名不存储(用于测试) |
Key Rules
关键规则
- Signatures are ONE-TIME USE — consumed even on failed requests
- Use single-line curl — multiline causes escaping errors
\ - USDC amounts use 6 decimals (10000 = $0.01)
- Always use field (not deprecated
requirement)paymentRequiredHeader
- 签名为一次性使用——即使请求失败也会被消耗
- 使用单行curl命令——多行会导致转义错误
\ - USDC金额使用6位小数(10000 = 0.01美元)
- 始终使用字段(而非已废弃的
requirement)paymentRequiredHeader
Supported Networks
支持的网络
| Network | CAIP-2 Identifier | Token |
|---|---|---|
| Base Mainnet | | USDC |
| Base Sepolia | | USDC |
| Solana Mainnet | | USDC |
| Solana Devnet | | USDC |
| 网络 | CAIP-2标识符 | 代币 |
|---|---|---|
| Base主网 | | USDC |
| Base测试网 | | USDC |
| Solana主网 | | USDC |
| Solana测试网 | | USDC |
Common Errors
常见错误
| Error | Solution |
|---|---|
| 404/405 on signing | Use |
| Use single-line curl, not multiline with |
| Get a NEW signature for each request |
| Fund wallet at |
| 错误 | 解决方案 |
|---|---|
| 签名时返回404/405 | 使用 |
| 使用单行curl命令,而非带 |
| 为每个请求获取新的签名 |
| 访问 |
Policies
策略管理
Get current policy:
bash
curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/policy \
-H "Authorization: Bearer FUND_API_TOKEN"Update policy:
bash
curl -X PATCH https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/policy \
-H "Authorization: Bearer FUND_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"max_per_tx_usd":"25","allow_chains":["base","solana"],"allow_contracts":["0x..."]}'查询当前策略:
bash
curl https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/policy \
-H "Authorization: Bearer FUND_API_TOKEN"更新策略:
bash
curl -X PATCH https://agentwallet.mcpay.tech/api/wallets/YOUR_USERNAME/policy \
-H "Authorization: Bearer FUND_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"max_per_tx_usd":"25","allow_chains":["base","solana"],"allow_contracts":["0x..."]}'Response Format
响应格式
Success:
json
{"success": true, "data": {...}}Error:
json
{"success": false, "error": "Description", "hint": "How to fix"}成功响应:
json
{"success": true, "data": {...}}错误响应:
json
{"success": false, "error": "错误描述", "hint": "修复建议"}