Skip to main content
Follow these guidelines to build reliable, efficient, and secure integrations with the Falcon API.

​
Performance

Optimizing your queries reduces response size, improves latency, and avoids hitting rate limits.
  • Always include pagination.limit to avoid unexpectedly large responses.
  • Use params filters to narrow the dataset before paginating.
  • Use time filters to limit dataset size — request only the time range you need.
  • Request narrow time ranges when querying high-volume datasets such as the Orderbook.
  • Use smaller time ranges when querying high-volume markets to keep responses manageable.
Combining params filters with pagination is the most effective way to reduce response size and improve query speed.

​
Pagination

Paginating correctly ensures you retrieve complete datasets without missing records.
  • Always check has_more in the response to determine whether more pages are available.
  • Store the current offset value as you iterate so you can resume if your process is interrupted.
  • Use the formula offset = limit × (page - 1) to calculate the offset for any page.
Set limit to a consistent value across requests when iterating through large datasets. Changing the limit mid-iteration will produce incorrect offsets.

​
Market data

These tips apply when querying Markets, Candlesticks, and Orderbook endpoints.
  • Combine min_volume and closed filters to find liquid, active markets.
  • Use partial slugs for broad market searches — for example, "nba" returns all NBA markets.
  • Match the candlestick interval with an appropriate time range to avoid empty results. A 1-hour interval over a 5-minute window will return no data.
The Orderbook endpoint uses millisecond Unix timestamps instead of seconds. Confirm the expected timestamp unit for each endpoint before sending requests.

​
Trade analysis

These tips apply when querying Trades endpoints for Polymarket and Kalshi.
  • Use Unix timestamps as strings when filtering by time.
  • Combine market_slug with time filters to focus your analysis on a specific market and period.
  • Use transaction_hash to verify Polymarket trades on-chain.
  • Compare yes_price and no_price across Kalshi trades to observe probability shifts over time.

​
Trader analytics

These tips apply when querying Leaderboard, Wallet 360, and Lifetime Performance endpoints.
  • Combine Lifetime Performance data with Leaderboard results for comprehensive trader analysis.
  • Use min_total_trades_15d in Leaderboard queries to filter out low-activity wallets.
  • Use a smaller window_days value in Wallet 360 to analyze short-term behavior.
  • Check sybil_risk_flag and combined_risk_score to identify wallets with suspicious activity patterns.

​
Security

Protect your API tokens to prevent unauthorized access to your account.
  • Store API tokens in environment variables rather than hardcoding them in your source code.
  • Never commit tokens to version control.
  • Use separate tokens for development and production environments.
  • Rotate tokens periodically to limit exposure if a key is compromised.
Never expose your API token in client-side code or public repositories. Treat it like a password.