Pagination & caching

Cursor pagination

Pass meta.nextCursor back as cursor until it is null. Keep every other parameter unchanged.

# first page, then repeat with the cursor until meta.nextCursor is null
curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liquidations?sinceMinutes=1440&limit=500" | jq '{n: (.data | length), next: .meta.nextCursor}'

curl -s -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  "https://api.blockmetric.io/v1/liquidations?sinceMinutes=1440&limit=500&cursor=<meta.nextCursor>"

• Paginated endpoints: /liquidations, /positions/top, /whales/feed, /traders, /tape, /radar/events, /security/incidents, /security/wallets, /movements. meta.nextCursor is always present there and null on the last page.
• Cursors are opaque and signed. Do not build or edit them: an edited cursor or one from another endpoint answers 400 invalid_param.
• Paging stops at your plan's history. Older rows are never returned, also not through a cursor; meta.access says where your window starts.
• limit sets the page size; values outside the allowed range are clamped and reported in meta.warnings.

Time windows

Each endpoint takes the window that fits its data. All times are ISO 8601 in UTC.

Polling for new rows

Ask only for what is new, and let the server tell you when nothing changed.

• Feeds: remember the newest time you have seen and pass it as since (whale feed, movements), or the newest id as after where the endpoint offers it.
• Snapshots (liquidation map, order book, screener) change at most every minute. Poll once a minute with If-None-Match.
• Alerts: instead of polling, receive events the moment they happen with webhooks or the live stream.

Caching with ETag

Every 200 has an ETag. Send it back as If-None-Match: while nothing changed you get 304 without a body.

# 1st call: note the ETag header
curl -si -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" "https://api.blockmetric.io/v1/liqmap/BTC" | grep -i etag

# later: 304 Not Modified (no body) while nothing changed
curl -si -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" \
  -H 'If-None-Match: "<etag>"' "https://api.blockmetric.io/v1/liqmap/BTC" | head -1

A 304 still counts as a request against your limits, but transfers nothing. Responses are private to your key; never cache them in a shared CDN.

Smaller answers: compression, fields and CSV

Large lists shrink a lot when you ask for compression and only the fields you need.

• Compression: send Accept-Encoding: gzip (or br, zstd). Browsers, Node fetch, Python requests and curl with --compressed do it for you; JSON lists are often 5 to 8 times smaller.
• fields: only the named fields of every row, e.g. ?fields=coin,mark,fundingApr. Unknown names answer 400 with the list of fields.
• format=csv or format=ndjson: only the rows. The next page is in Link: rel="next" and X-Blockmetric-Next-Cursor; the cursor of a JSON page works too. Errors stay JSON.

# three fields of every market as CSV; --compressed asks for gzip
curl -s --compressed -H "Authorization: Bearer $BLOCKMETRIC_API_KEY" "https://api.blockmetric.io/v1/markets?fields=coin,mark,fundingApr&format=csv"

Row lists: /markets, /funding, /liquidations, /positions/top, /whales/feed, /radar/events, /coins, /candles/{coin}, /long-short, /whales, /traders, /tape, /screener, /funding/predicted, /funding/spreads, /security/incidents, /security/wallets, /movements. Your plan, its history and the licence apply exactly as for JSON; only the encoding changes.