API documentation

Public page. Auth for the API itself is an X-API-Key header; keys are issued per consumer.

Read API

endpoint	returns
`GET /v1/wallet/{address}/score`	tier, hit_rate, realized_pnl_usd, closed_positions, median_multiple, weights_version, computed_ts
`GET /v1/wallet/{address}`	class, first_seen, funder, flags, tx_count
`GET /v1/token/{address}`	status, labels[], age_seconds, deployer, initial/last mcap, pools[]
`GET /v1/token/{address}/cluster`	distinct_buyers, sum_quote_usd, buyers[], funding_cluster, window_start
`GET /v1/candles/{pool}?interval=1m&from=&to=`	own candles — quote-asset stamped
`GET /v1/leaderboard?window=7d`	ranked by realized PnL (closed, scam-excluded)
`GET /v1/signals?type=&token=&wallet=&limit=`	signal history with full state snapshots
`GET /v1/health`	ingest lag, stream lengths, gap counts, last reconciliation
`WS /v1/stream`	live signals, fixed predicate schema evaluated server-side

Answers come from precomputed Redis state and target < 5 ms server-side. If an answer is not cached the response is {"status":"not_indexed"} — the API never falls through to the database on the read path, which is what keeps consumer traffic off the pipeline. /v1/signals is the one documented exception: signal history is the record, not a cached answer.

Stream API — fixed predicate schema

Subscribe with named fields and operators only. There are no expressions and nothing from client input is evaluated beyond this schema. Predicates are checked server-side, one pass per event. An unknown field is rejected at subscribe time rather than ignored — a filter you mistyped must fail loudly, not silently firehose you.

field	type	operators	notes
`wallet_set`	string	in / == / !=	named server-side list, e.g. list:james_tracked
`min_wallet_tier`	number	>= <= > < == !=	satisfied by the BEST wallet in the cluster
`min_quote_usd_each`	number	>= <= > < == !=	satisfied by the SMALLEST buy — every buy must clear it
`sum_quote_usd`	number	>= <= > < == !=	total quote value across the window
`distinct_buyers`	number	>= <= > < == !=	distinct wallets, not trades
`token_age_seconds`	number	>= <= > < == !=	since first sighting
`mcap_usd`	number	>= <= > < == !=	derived from pool price × supply
`funding_cluster`	boolean	== !=	two or more buyers share a funding parent
`wallet_tx_count_max`	number	>= <= > < == !=	satisfied by the BUSIEST wallet; from the on-chain nonce
`deployer_flag`	boolean	== !=
`venue`	string	== != in	v2 \| v3 \| v4
`quote_asset`	string	== != in	registry address

Subscribe frame

{
  "action": "subscribe",
  "id": "james-cluster-1",
  "event_types": ["cluster_buy", "fresh_cluster", "serial_deployer_launch",
                  "rug_warning", "insider_distribution", "narrative_cluster",
                  "token_deployed", "first_liquidity"],
  "filters": [
    { "field": "wallet_set",          "op": "in",  "value": "list:james_tracked" },
    { "field": "min_wallet_tier",     "op": ">=",  "value": 2 },
    { "field": "min_quote_usd_each",  "op": ">=",  "value": 50 },
    { "field": "distinct_buyers",     "op": ">=",  "value": 3 },
    { "field": "token_age_seconds",   "op": "<=",  "value": 21600 },
    { "field": "mcap_usd",            "op": "<=",  "value": 500000 },
    { "field": "funding_cluster",     "op": "==",  "value": false },
    { "field": "wallet_tx_count_max", "op": "<=",  "value": 10 }
  ]
}

Delivery guarantees

At-least-once to connected subscribers; dedup on signal_id.
Missed-while-disconnected is not replayed in v1 — resync via the Read API.
Every emitted signal is written to the log before delivery is attempted. A failed delivery still leaves the log entry, with delivered_to: [].