Conventions

Every Agent API endpoint follows the same conventions: one success envelope, one error envelope, cursor pagination, and predictable rate limits. Learn them once and every endpoint behaves the same way.

Success envelope

Successful responses wrap your payload in data and put everything else in meta:

{
  "data": [
    { "symbol": "BTC", "quantity": 0.5 }
  ],
  "meta": {
    "requestId": "req_8f2a1c",
    "timestamp": "2026-07-03T09:15:00Z",
    "asOf": "2026-07-03T09:14:30Z",
    "pagination": {
      "cursor": "eyJvZmZzZXQiOjEwMH0",
      "hasMore": true,
      "count": 100
    }
  }
}

• requestId — include it when contacting support about a specific call.
• timestamp — when the response was produced.
• asOf — how fresh the underlying data is. Market data is a snapshot, not a live tick; check asOf before treating a number as current.
• pagination — present only on paginated list responses.

Error envelope

Errors are structured for recovery, not just reporting:

{
  "error": {
    "code": "invalid_param",
    "message": "limit must be between 1 and 100",
    "hint": "You sent limit=250. Use limit=100 and paginate with the cursor.",
    "param": "limit",
    "nextActions": ["Retry with limit <= 100"],
    "retryable": false
  },
  "meta": {
    "requestId": "req_9d4b7e",
    "timestamp": "2026-07-03T09:16:00Z"
  }
}

How to use each field:

• code — stable machine-readable identifier; branch your error handling on this, not on message.
• message — human-readable summary, fine for logs.
• hint — a plain-language explanation of what went wrong and how to fix it. If you're building an automated client (or an AI agent), surface the hint — it's written to be acted on.
• param — present when a specific request parameter caused the error.
• nextActions — concrete suggested next steps, ready to follow.
• retryable — if true, the same request may succeed on retry (back off first). If false, retrying without changing something won't help.

Pagination

List endpoints use cursor pagination:

• limit — items per page, 1–100.
• cursor — an opaque token from the previous page's meta.pagination.cursor. Don't parse or construct it.

Keep requesting with the returned cursor until hasMore is false:

GET /...?limit=100
GET /...?limit=100&cursor=eyJvZmZzZXQiOjEwMH0

meta.pagination gives you cursor (for the next page), hasMore, and count (items in this page).

Rate limits

Every response includes X-RateLimit-* headers so you can pace yourself before hitting the ceiling. If you do exceed a limit, you get a 429 with a Retry-After header — wait that long, then retry. Rate-limit errors are retryable: true by definition.

Your key's exact limits are also returned by GET /capabilities — see Authentication & keys.

Related