API reference
The five endpoints, their payloads, the error classes and the machine-readable contract.
Base URL: https://protocolbanks.com/api/v1/agent — auth: Authorization: Bearer pb_… Reads require the read permission; writes require write.
| Endpoint | Method | Purpose |
|---|---|---|
| /state | GET | account, positions, activity, policy |
| /orders | POST | place one order (executes) |
| /pay | POST | validate and prepare a transfer |
| /swap | POST | quote and prepare a swap |
| /invoice | POST | create a pending invoice |
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 }One position per market. A size above the platform cap is clamped; above the key's cap it is 403. A second order on a held market is 409.
POST /pay
{ "to": "0x…", "amountUsd": 25, "token": "USDC", "chain": "base", "memo": "invoice 41" }Returns an intent (kind, to, token, chain, amountUsd, remainingTodayUsd). The agent signs and submits it from its own wallet; the platform never holds funds.
POST /swap
{ "from": {"symbol":"USDC","blockchain":"base"}, "to": {"symbol":"ETH","blockchain":"base"}, "amount": "25", "amountUsd": 25 }Returns the route and the transaction to sign. 409 when no route exists. Quotes are not metered.
POST /invoice
{ "to": "0x…", "amount": 25, "token": "USDC", "description": "agent work", "expiresInHours": 24 }Returns the pending invoice with paymentLink and signed. Read settlement back with GET /api/invoice?id=…&sig=… (the signature is in the link).
Errors
| 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 |
Rate limits
The platform enforces 100 requests per minute per IP. Per-key rate-limit fields are stored but not enforced yet; budget for the global limit.
The contract
OpenAPI 3.1 is served at /api/agent.openapi.json (CORS-open) and validated offline by scripts/verify-openapi.mjs. Use it for codegen, or read the four worked cases in the docs hub.