Candlebox

API reference

The base address is this site's own address. Send your key in the X-API-Key header on every call. Times are Unix seconds in UTC.

Get a free key

Candles

GET /v1/candles

ParameterMeaning
mintThe coin's address. Required.
interval1s, 5s, 15s, 30s, 1m, 5m, 15m, 1h, 4h or 1d. Default 1s.
fromStart time. With it, candles run forward from here and next_from gives the next page.
toEnd time, inclusive. Without from, you get the newest candles up to this time.
limitWidth of the window in candles, 1 to 2000. Default 500.

Seconds with no trades have no candle. Candles always run oldest first.

Response fieldMeaning
candles[].tCandle start time.
candles[].o h l cOpen, high, low and close, in SOL per token.
candles[].volume_solSOL traded in the candle.
candles[].volume_tokenTokens traded in the candle.
candles[].buys, sellsTrade counts by side.
candles[].closedFalse while the candle's time window is still open.
first_trade_atTime of the first trade on record.
complete_from_first_tradeTrue when the coin's creation was seen, the recorder has been connected since, and no history has aged out.
gapsPeriods overlapping this window when the recorder was disconnected, as from and to.
history_fromOldest time kept for this candle size. Sizes under 1m are kept 7 days and larger sizes 90 days.
next_fromPass as from for the next page, or null when there is no more.

Coins

GET /v1/coins/new

Newest coins first. limit is 1 to 200, default 50. Pass the last created_at as before to page back.

GET /v1/coins/{mint}

One coin.

FieldMeaning
mint, creatorAddresses.
name, symbol, uriWhatever the creator typed. Treat as untrusted text, and null if creation was not seen.
sourceThe launchpad. Currently pump.
created_atWhen creation was seen.
first_trade_at, last_trade_atBounds of recorded trading.
tradesTrades recorded.
complete_from_first_tradeAs in candles.

Stream

WS /v1/stream/new

Send the key as a header. Browsers can't set websocket headers, so they can pass ?key= instead; keep that key out of public pages. Each message is one JSON object with a type. The stream carries events from the moment you connect, so use /v1/coins/new to catch up after a reconnect.

TypeFields
helloingest: state of the recorder when you connected.
coinmint name symbol uri creator created_at slot signature
first_trademint t price_sol amount_sol side slot signature

Usage and limits

GET /v1/usage

Your plan, calls this month and open streams. This call is free. Metered responses also carry X-RateLimit-Limit and X-RateLimit-Remaining for the month. Calls reset on the first of each month, UTC.

Errors

Errors return {"error": {"code", "message"}}.

StatusCodeMeaning
400bad_mint bad_interval bad_rangeCheck the parameter named in the message.
401missing_key invalid_keyNo key, or not an active one.
404unknown_mintNo trades recorded for this coin.
426upgrade_requiredThe stream needs a websocket client.
429rate_limited monthly_limit stream_limitOver a plan limit. rate_limited includes Retry-After.