CryptoGrindCryptoGrindDocs
Open Dashboard

Getting started

Conventions

One set of rules across every family — learn them once and the whole API behaves the same way.

Endpoint shape

Each event family exposes the same three surfaces:

  • GET /v1/{family}/recent — last ≤500 events held in memory, filterable.
  • GET /v1/{family}/history — durable event log, keyset-paginated.
  • WS /v1/{family}/live — filtered live stream.

Prices and metadata differ slightly (latest/live and a single meta GET respectively) — see their reference pages.

Filtering

Filters are query params and they mirror the platform's bot config 1:1 — the same thresholds, type allowlists, exchange allowlists (with the same leg semantics), blacklists and volume/liquidity gates. Unknown params are ignored; conflicting params intersect (AND).

text
?min_pct=10&spread_type=spot/futures&allowed_exchanges=mexc,gate,binance&exclude_symbol=FOO

Pagination

history uses keyset pagination. The response includes next_before; pass it back as before to fetch the next older page. An empty data array means you've reached the end. limit caps page size (per-tier maximum).

The delay parameter

?delay=N hides events fresher than N seconds — useful to deliberately consume delayed data, or required by your tier. Your tier clamps the minimum delay per family: the effective delay is max(requested, tier_min).

On /v1/spreads/live, Builder tier clamps the minimum delay for OPEN events to 60s. See Access tiers.

Timestamps & symbols

  • All timestamps are unix seconds (UTC) unless suffixed _ms.
  • Symbols are canonical BASE_QUOTE, e.g. BTC_USDT.
  • CEX exchanges are UPPERCASE (BINANCE); DEX legs are DEX-{CHAIN} (DEX-SOLANA).

The trace watermark

Every payload carries a trace string unique to your consumer. It identifies redistributed data back to your key — keep it intact.