> ## Documentation Index
> Fetch the complete documentation index at: https://api.polymarketanalytics.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Tips for building reliable integrations with the Falcon API.

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.

> [!TIP]
>
> 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.

> [!TIP]
>
> 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.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> Never expose your API token in client-side code or public repositories. Treat it like a password.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.