FOR AI AGENTS & DEVELOPERS
把 CarryPilot 接进你的 Agent
CarryPilot 除了是一个人用的交易平台，同时也是一个可被其他 AI Agent 调用的研究服务：查 Hyperliquid 资金费率现状、查扣完成本后的市场中性套利机会。免费部分只读免鉴权；完整报告走 x402 按次付费。三种协议任选。
🔗 链上证据（Injective Testnet，点开即可自行核实）
下面每一项都是可独立验证的真实链上数据/交易，不是截图或编造——地址页/交易页都是 Blockscout 公开浏览器链接。
| 项目 | 地址 / 哈希 | 说明 |
|---|
| USDC 合约（testnet） | 0x0C38…4C5d ↗ | Circle FiatTokenV2_2，支持 EIP-3009 免 gas 授权 |
| x402 payer 付款方钱包 | 0x55Fb…93Ac ↗ | 模拟"外部 AI Agent 付款方"，持 20 testnet USDC |
| x402 收款金库 / facilitator | 0xF352…86cE ↗ | 402 报价里的 payTo / 结算方，持 1 testnet INJ 付 gas |
| INJ 充值交易（facilitator gas） | 0x6272…a76d ↗ | 1 INJ → facilitator · 区块 134,670,989 · 2026-07-25 16:24:49 UTC · 成功 |
| x402 结算交易（付费成交） | 0xbdf6…dd73 ↗ | 0.01 USDC · payer→facilitator · EIP-3009 代付 gas · 已确认上链 |
✅ x402 全链路已实测跑通并确认上链：402 报价握手 → EIP-3009 免 gas 签名 → facilitator 代付 gas 链上结算，0.01 USDC 由 payer 转入 facilitator（payer 20.00→19.99、facilitator 0→0.01，账实相符）。Injective testnet RPC/LCD 直连无地域封锁。
①Agent Card（服务发现）
任何调用方第一步都应该先拉这个文件——它是机器可读的"名片"：身份、技能、约束、以及下面三种协议各自的入口地址。
GET /.well-known/agent-card.json
{
"protocolVersion": "0.2",
"name": "CarryPilot",
"description": "AI 资金费率套利研究 Agent...",
"url": "/api/a2a",
"preferredTransport": "JSONRPC",
"additionalInterfaces": [
{ "url": "/api/a2a", "transport": "JSONRPC" },
{ "url": "/mcp", "transport": "MCP" },
{ "url": "/api/agent/query", "transport": "HTTP+JSON" }
],
"skills": [
{ "id": "funding_rates", "name": "资金费率查询", "examples": ["BTC 现在资金费率多少", "哪些币费率最高"] },
{ "id": "arbitrage_opportunity", "name": "套利机会查询", "examples": ["现在有什么套利机会", "BTC 值得做套利吗"] }
],
"constraints": { "venues": ["hyperliquid"], "strategy": "S1_SPOT_PERP", "readOnly": true },
"payments": { "protocol": "x402", "asset": "USDC", "network": "injective-testnet", "endpoint": "/api/agent/report" }
}
两个技能背后都是同一套确定性引擎：扣完手续费+滑点+资金准备金之后的真实净 APR，不是毛费率。没机会的时候会诚实地说"没机会"，不会为了有话说而编造。
②HTTP（最简单，适合快速试探）
一句自然语言，一个 JSON 结果。没有协议开销，适合脚本、curl、或者你自己的 agent 内部再包一层。
GET /api/agent/query?q=<text> 或 POST /api/agent/query {"query":"..."}
curl "/api/agent/query?q=BTC资金费率多少"
{
"query": "BTC资金费率多少",
"coin": "BTC",
"generatedAt": "2026-07-25T03:32:48.582Z",
"disclaimer": "...",
"intent": "funding_rates",
"found": true,
"hourlyFundingPct": 0.00086329,
"annualizedPct": 7.5624204,
"hasSpot": true,
"message": "BTC 当前资金费率 0.00086%/h（年化约 7.6%），多头付给空头（做空可收）。有现货可对冲，可构建站内套利组合。"
}
套利机会查询同一个端点，换个问法即可：?q=现在有什么套利机会 或 ?q=BTC值得做吗。
③A2A（Agent2Agent 协议）
标准 A2A JSON-RPC 2.0，message/send 方法。适合已经在用 A2A 生态（agent card 发现 + 多 agent 编排）的 host。
POST /api/a2a
curl -X POST /api/a2a \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"message": {
"role": "user",
"parts": [{ "kind": "text", "text": "现在有什么套利机会" }]
}
}
}'
返回的 result 是一条 role: "agent" 的 message，两个 part 都给：text（人类可读一句话）+ data（结构化字段，给你的代码解析）。
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"kind": "message",
"role": "agent",
"messageId": "...",
"parts": [
{ "kind": "text", "text": "当前全市场无扣完成本后为正的套利机会——..." },
{ "kind": "data", "data": { "intent": "arbitrage_opportunity", "accepted": [], "...": "..." } }
]
}
}
本 Agent 所有调用都同步完成，不维护长任务状态：tasks/get/tasks/cancel 会返回 -32001。
④MCP（Model Context Protocol）
Streamable HTTP，无状态。如果你的 agent host 本身是 Claude / Codex / 其他支持 MCP 的框架，这是最省事的接入方式——不用自己写 HTTP 客户端，配个 URL 就行。
{
"mcpServers": {
"carrypilot": { "url": "/mcp" }
}
}
暴露的 tool
| Tool | 参数 | 说明 |
|---|
get_funding_rates | coin?: string | 某标的（或全市场费率绝对值最高的几个）当前资金费率/年化/是否可对冲 |
find_arbitrage | coin?: string | 扣完成本后的市场中性套利候选：净APR、成本覆盖率、拒绝原因 |
用官方 SDK 直连测试：
// npm i @modelcontextprotocol/sdk
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(new StreamableHTTPClientTransport(new URL("/mcp")));
const { tools } = await client.listTools();
const result = await client.callTool({ name: "find_arbitrage", arguments: {} });
⑤x402：按次付费拿完整报告
免费三个入口只回答"你问的那一句"。完整报告（全市场候选 + 全费率表，不是摘要）走 x402 协议收 USDC——HTTP 402 起手，链上 EIP-3009 免 gas 签名支付，全程无需人工介入，AI agent 可以自己付钱自己拿数据。
GET /api/agent/report
当前状态：Injective testnet（eip155:1439），x402 全链路已实测跑通并确认上链——402 报价 → EIP-3009 免 gas 签名 → facilitator 代付 gas 链上结算，0.01 USDC 由 payer 转入 facilitator（见 scripts/x402-a2a-test.ts，结算 tx 0xbdf6030e…459dd73）。
第 1 步：不带支付直接请求 → 收到 402 报价
curl /api/agent/report
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <base64 同下面 JSON>
{
"x402Version": 2,
"resource": { "url": ".../api/agent/report", "description": "CarryPilot 完整套利报告" },
"accepts": [{
"scheme": "exact",
"network": "eip155:1439",
"amount": "10000",
"asset": "0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d",
"payTo": "0x402e6cB590137156eA549D4b7eDa9231C70A2c98",
"maxTimeoutSeconds": 120,
"extra": { "name": "USDC", "version": "2", "assetTransferMethod": "eip3009" }
}]
}
amount: "10000" = 0.01 USDC（6位小数）。network: eip155:1439 是 Injective EVM Testnet。
第 2 步：按报价签一个 EIP-3009 transferWithAuthorization，带着重放
手写签名比较繁琐（EIP-712 typed data），推荐直接用官方 client（本项目也是这么测的）：
// npm i @injectivelabs/x402 viem
import { createInjectiveClient } from "@injectivelabs/x402/client";
const client = createInjectiveClient({ privateKey: YOUR_PAYER_PRIVATE_KEY });
const res = await client.fetch("/api/agent/report");
// res.status === 200，body 就是完整报告
const receipt = JSON.parse(atob(res.headers.get("payment-response")));
// receipt.transaction 是链上结算的 tx hash
Client 内部做的事：解析 402 里的 accepts → 构造 EIP-712 typed data → 用你的私钥签名（链下，不花 gas）→ 把签名放进 PAYMENT-SIGNATURE header 重新请求 → 服务端 facilitator 校验签名/余额/nonce → 提交链上交易结算 → 你收到 200 + 完整数据 + 结算回执。
没有 SDK？自己手撸
报头名是 PAYMENT-SIGNATURE（新）或 X-PAYMENT（兼容旧版），内容是 base64 编码的 PaymentPayload（scheme/network/payload.authorization + payload.signature）。EIP-712 domain 是 USDC 合约自己的（name "USDC", version "2"），签名对象是标准 EIP-3009 TransferWithAuthorization（from/to/value/validAfter/validBefore/nonce）。
测试网参数
| 值 |
|---|
| Chain ID | 1439（eip155:1439） |
| RPC | https://k8s.testnet.json-rpc.injective.network |
| USDC 合约 | 0x0C382e685bbeeFE5d3d9C29e29E341fEE8E84C5d（Circle FiatTokenV2_2，支持 EIP-3009） |
| 测试网 USDC 水龙头 | faucet.circle.com（选 Injective Testnet） |
| 测试网 INJ 水龙头（付 gas 用，仅 facilitator 自建时需要） | testnet.faucet.injective.network |
源码参考：scripts/x402-spike.ts（协议可行性验证）、scripts/x402-settle-demo.ts（真实付款结算 demo，含链上 tx hash）。
⑥错误码
A2A（JSON-RPC 2.0 标准错误码）
| code | 含义 | 触发场景 |
|---|
-32700 | Parse error | 请求体不是合法 JSON |
-32600 | Invalid Request | jsonrpc 字段不是 "2.0" |
-32601 | Method not found | 方法不是 message/send |
-32602 | Invalid params | message.parts 里没有 text part |
-32001 | Task not found | 调用了 tasks/get/tasks/cancel——本 Agent 同步完成，不留任务状态 |
x402
| HTTP | 含义 |
|---|
402 + insufficient_funds | payer 钱包 USDC 余额不够 |
402 + Payment network not accepted | 签名的 network/asset 跟报价对不上 |
501 | 本部署没配置 x402（金库/facilitator key 缺失） |
⑦限制与免责
⚠ 所有输出是研究结论，不构成投资建议或收益承诺。资金费率随市场快速变化；免费端点数据有 60 秒缓存。
- 只覆盖 Hyperliquid 站内策略（现货多 + 永续空，市场中性），不做跨所套利
- 只读查询：本文档所有端点都不下单、不动资金；下单需要钱包签名会话，是给人用的 App 里的能力，没有对外开放给 agent
- 请合理控制请求频率；生产集成建议本地缓存问答结果，异常流量会被限制访问