API 参考
五个端点、请求与响应、错误分类，以及机器可读契约。
Base URL：https://protocolbanks.com/api/v1/agent —— 认证：Authorization: Bearer pb_…。读操作需要 read 权限，写操作需要 write。
| 端点 | 方法 | 用途 |
|---|---|---|
| /state | GET | 账户、持仓、活动、策略 |
| /orders | POST | 下单一笔（会执行） |
| /pay | POST | 校验并准备转账 |
| /swap | POST | 报价并准备兑换 |
| /invoice | POST | 创建待支付发票 |
GET /state
{
"ok": true, "mode": "paper",
"account": { "totalEquity": 500, "tradingWallet": 500, "maxLoss": 500 },
"positions": [], "activity": [],
"policy": { "allowedOps": ["read","trade"], "maxNotionalUsd": 50, "dailyCapUsd": 200, "allowedCoins": [], "spentTodayUsd": 0 }
}POST /orders
{ "coin": "BTC", "side": "long", "sizeUsd": 20, "reason": "signal-v3" }{ "ok": true, "fill": { "coin": "BTC", "side": "long", "avgPx": 81062.5, "size": 0.000247, "notional": 20 }, "fee": 0.016, "mode": "paper", "remainingTodayUsd": 180 }每个市场只能有一个持仓。超过平台仓位上限会被压缩；超过 Key 上限返回 403；同一市场重复下单返回 409。
POST /pay
{ "to": "0x…", "amountUsd": 25, "token": "USDC", "chain": "base", "memo": "invoice 41" }返回转账意图（kind、to、token、chain、amountUsd、remainingTodayUsd）。由 Agent 在自己的钱包里签名提交，平台不持有资金。
POST /swap
{ "from": {"symbol":"USDC","blockchain":"base"}, "to": {"symbol":"ETH","blockchain":"base"}, "amount": "25", "amountUsd": 25 }返回路由与待签名交易；无路由时 409。报价不计量。
POST /invoice
{ "to": "0x…", "amount": 25, "token": "USDC", "description": "agent work", "expiresInHours": 24 }返回待支付发票、paymentLink 与 signed。用 GET /api/invoice?id=…&sig=… 回读结算（签名在链接里）。
错误
| Status | Meaning | What to do |
|---|---|---|
| 400 | Malformed body, bad address, non-positive amount | Fix the request |
| 401 | Missing or invalid key | Re-issue the key |
| 403 | The key's policy refuses (op, cap, allowlist) | Surface it; do not retry unchanged |
| 409 | The platform guard refuses (positions, breakers, funds, market, no route) | Surface it; back off |
| 429 | Rate limit (100 requests/minute per IP) | Honour Retry-After |
速率限制
平台按 IP 限制 100 请求/分钟。Key 上的速率字段已存储但尚未强制执行，请按全局限制规划。
契约
OpenAPI 3.1 契约在 /api/agent.openapi.json（开放 CORS），可用 scripts/verify-openapi.mjs 离线校验，也可用于代码生成。