Skip to main content

​
Discover markets before querying

Always start with the GET /v1/markets endpoint to discover available exchanges, symbols, and data types. Don’t hardcode exchange IDs or symbols — use the discovery API to find what’s available. 
curl "https://api.kiyotaka.ai/v1/markets?exchange=BINANCE_FUTURES&coin=BTC&pageSize=10" \
  -H "X-Kiyotaka-Key: YOUR_API_KEY"
Use the rawSymbol field from the response when constructing data queries.

​
Choose the right symbol parameter

ParameterUse when
rawSymbolYou want data for a specific trading pair on a specific exchange (e.g., BTCUSDT on Binance Futures)
coinYou want data across all pairs for a base asset, or you’re using multi-exchange aggregation
normalizedSymbolYou want a normalized market symbol form across exchanges (e.g., BTC-USDT, BTC-USD)
When aggregating across exchanges, always use coin — rawSymbol values differ between exchanges (BTCUSDT vs BTC-USD vs XBTUSD).

​
Use appropriate intervals for your time range

Smaller intervals over large time ranges produce massive result sets. Match your interval to your time range:
Time RangeRecommended Intervals
Minutes to hoursMINUTE
Hours to daysFIVE_MINUTES, FIFTEEN_MINUTES, HOUR
Days to weeksHOUR, FOUR_HOURS
Weeks to monthsFOUR_HOURS, DAY
Months to yearsDAY, WEEK
Each data type has a maximum points-per-request limit (e.g., 100,000 for candles, 4,000 for orderbook heatmaps). If your time range + interval combination exceeds this, reduce the range or use a larger interval.

​
Always set period when using from

Both from and period are required for time-range queries. If period is 0 or missing, the query may return empty results. 
from=1774800000&period=3600    # 1 hour of data
from=1774800000&period=86400   # 1 day of data
If you omit from and only provide period, the API returns data for the last period seconds from now.

​
Monitor your rate limit usage

Check your quota before heavy operations using the zero-cost usage endpoint: 
curl "https://api.kiyotaka.ai/v1/usage" \
  -H "X-Kiyotaka-Key: YOUR_API_KEY"
Every response also includes X-RateLimit-Remaining and X-RateLimit-Reset headers. Use these to implement client-side throttling.

​
Handle rate limits gracefully

When you receive a 429 response, use the Retry-After header to wait before retrying: 
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Reset: 1712345678
Don’t retry immediately — you’ll waste requests. Wait for the Retry-After seconds or until the X-RateLimit-Reset timestamp.

​
Optimize weight costs

Weight is calculated as: ceil(points / 1000) × cost_multiplier × exchange_multiplier × depth_multiplier To reduce weight:
  • Use larger intervals — fewer points = lower weight
  • Narrow your time range — request only what you need
  • Minimize exchanges when aggregating — each additional exchange adds 20% to the multiplier
  • Keep maxDepth at the included depth unless you need more range — orderbook heatmap adds 20% per extra 3500 levels, liquidation heatmap adds 20% per extra 1500 levels
  • Avoid 10x types (orderbook heatmap) in tight loops — batch your requests

​
Use gapfill intentionally

gapfill=true is supported only for candle types: TRADE_SIDE_AGNOSTIC_AGG and TRADE_AGG. For those types, it fills missing intervals using last-observation-carried-forward (LOCF). This is useful for charting but changes the semantics of your data:
  • Volume is not carried forward — gapfilled bars have zero volume
  • Only the close price is carried forward
  • A lookback window (typically 1 hour) seeds the LOCF — if there’s no data in the lookback, the gap remains
Skip gapfill if gaps in data are meaningful to your analysis (e.g., studying market activity patterns).

​
Get block sizes before querying heatmaps

Always call GET /v1/block-sizes to get the correct block size for your symbol before requesting orderbook heatmap data. Don’t guess block sizes. 
# Step 1: Get the block size
curl "https://api.kiyotaka.ai/v1/block-sizes?exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT" \
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

# Step 2: Use it (4K = raw value, HD = 5x)
curl "https://api.kiyotaka.ai/v1/points?type=BLOCK_BOOK_SNAPSHOT_AGG&exchange=BINANCE_FUTURES&rawSymbol=BTCUSDT&interval=MINUTE&period=1140&blockSize=25&maxDepth=1000&sortDirection=SORT_DIRECTION_DESC" \
  -H "X-Kiyotaka-Key: YOUR_API_KEY"

​
TPO block sizes are fixed

TPO only supports block sizes of 5, 30, 60, or 240 minutes. Other values will return an error. Default is 30 minutes.

​
Treat empty results as normal

If your query matches no data (e.g., a symbol that doesn’t exist on that exchange, or a time range with no activity), the API returns an empty series array — not an error. Always check for empty results in your client code.

​
Secure your API keys

  • Never expose keys in client-side code, browser applications, or public repositories
  • Use environment variables or secret managers to store keys
  • Rotate keys if you suspect they’ve been compromised
  • Use separate keys for different applications to isolate access