Skip to main content

Conventions

Every resource in this API reads the same way. Learn it once.

The envelope​

A list response is always:

{
"data": [ … ],
"meta": {
"limit": 50,
"has_more": true,
"next_cursor": "eyJ0IjoiMjAyNi0wOS0yMlQwNjo0MDowMFoiLCJpZCI6IjQyIn0"
}
}

data is the array, meta is everything about the page. A single-resource response carries the object under data with no meta.

Paging​

Paging is keyset, not offset. Pass the previous page's next_cursor back:

curl -s "$BASE/v1/transfers?protocol=acme&token=0x…&limit=100" -H "x-api-key: $KEY"
curl -s "$BASE/v1/transfers?protocol=acme&token=0x…&limit=100&cursor=eyJ0Ijoi…" -H "x-api-key: $KEY"
ParameterDefaultMax
limit50200
cursor—opaque; pass it back verbatim

The cursor encodes the sort key of the last row, so rows are never repeated or skipped when data is written mid-page — which offset paging cannot promise on a table that is still being indexed. A cursor that has been edited answers 400 INVALID_CURSOR.

Sorting and filtering​

sort accepts a per-resource allowlist of columns and order is asc or desc. A column outside the allowlist answers 400 INVALID_SORT rather than sorting by something arbitrary.

Filters are additive, and an absent filter is simply not applied.

Required filters​

Large tables require enough of a filter to stop a request from scanning the whole history: typically a protocol, a token, and a time window. Without them the answer is 400 MISSING_REQUIRED_FILTER, naming what was missing. A window wider than the resource allows answers 400 WINDOW_TOO_WIDE.

This is a guard, not a limit on what you can read — page through the windows.

Incremental sync​

Resources that change over time accept ?since=, an RFC 3339 timestamp: everything written after that instant, in write order. It is the cheap way to keep a local copy fresh without re-reading a window.

Each resource documents its own cadence in the reference, because the underlying ingestion differs a lot: prices update every minute, while transfers land in batches a few times a day. since returns what exists, not what will exist.

Every query parameter​

These are shared by every list resource. A parameter absent from the request is simply not applied — there is no "empty means all" special case to remember.

FilterDescriptionRequired
limitPage size. Default 50, maximum 200. A larger value is clamped, not rejected.No
cursorOpaque keyset cursor. Copy meta.next_cursor back verbatim — it encodes the sort key of the last row, so editing it answers 400 INVALID_CURSOR.No
sortColumn to sort by, from that resource's own allowlist. Anything outside it answers 400 INVALID_SORT rather than sorting by something arbitrary.No
orderasc or desc. Default desc — newest first, which is what a client polling for new rows wants.No
sinceRFC 3339 timestamp. Returns only rows written after that instant, in write order: the cheap way to keep a local copy fresh.No
protocolProtocol id (UUID) or slug — either is accepted wherever a protocol is named.Yes on protocol-scoped resources
tokenToken contract address.Yes on high-volume resources
networkNetwork name. Narrows the result; on /v1/protocols it also narrows the tokens array of each item.No
from, toTime window, RFC 3339. A window wider than the resource allows answers 400 WINDOW_TOO_WIDE — page through narrower windows.Yes on high-volume resources

What "required" means here. Large tables refuse to be scanned whole: without enough of a filter to bound the read, the answer is 400 MISSING_REQUIRED_FILTER, and it names what was missing. It is a guard against one request holding a connection that also serves the product — not a limit on what you can read. Page through the windows and you can read all of it.

Each resource's entry in the API reference lists the filters it accepts on top of these, and marks which of them it requires.

Values​

  • Timestamps are RFC 3339 with an explicit offset: 2026-09-22T06:40:00Z.
  • On-chain amounts are never floats. They arrive as { "raw": "1250000000000000000", "decimals": 18 } — the integer as a string, plus the scale. Formatting is the client's decision; rounding on our side would be a lie at the eighteenth decimal place.
  • Identifiers are the protocol's id (UUID) or slug, and either is accepted wherever a protocol is named.

Headers​

HeaderMeaning
X-Request-IdEchoed on every response; quote it in a support request
RateLimit-Limit / RateLimit-Remaining / RateLimit-ResetYour current window
Retry-AfterSeconds to wait, sent with 429