Core Concepts - Falcon

Understanding these core concepts will help you structure queries correctly and navigate datasets efficiently across all Falcon endpoints.

Agent IDs

Every Falcon dataset is queried using an agent_id. The agent_id you include in your request determines which dataset is returned. You use the same endpoint for all datasets — only the agent_id changes.

Agent ID	Dataset
`555`	Profit & Loss
`556`	Polymarket Trades
`565`	Kalshi Markets
`568`	Candlesticks
`572`	Orderbook
`573`	Kalshi Trades
`574`	Polymarket Markets
`575`	Market Insights
`581`	Wallet 360
`584`	Leaderboard / Top Traders
`585`	Social Pulse
`586`	Lifetime Performance

Pagination

Falcon supports pagination to efficiently navigate large datasets. Use the pagination object in your request to control how many records are returned and where the result set begins.

Parameter	Description
`limit`	Number of records returned per request. Range: `1–200`. Default: `10`.
`offset`	Number of records to skip before returning results.
`has_more`	Returned in the response. `true` when more records are available beyond the current page.

To calculate the offset for any page, use this formula:

offset = limit × (page - 1)

For example, to fetch page 3 with 25 results per page:

{
  "pagination": {
    "limit": 25,
    "offset": 50
  }
}

The offset is 25 × (3 - 1) = 50.

Time filters

Many Falcon datasets support filtering results by time range. You pass time filters inside the params object as Unix timestamps represented as strings.

{
  "params": {
    "start_time": "1703719954",
    "end_time": "1704067199"
  }
}

Most endpoints use Unix timestamps in seconds. The Orderbook endpoint uses milliseconds. Check the dataset-specific documentation to confirm the expected unit.

Converting to Unix timestamps

Use the examples below to generate the current Unix timestamp in your language:

// Current time in seconds
Math.floor(Date.now() / 1000).toString()

import time

# Current time in seconds
str(int(time.time()))

To query the last 24 hours, subtract 86400 seconds from the current timestamp:

start_time = current_time - 86400

​Agent IDs

​Pagination

​Time filters

​Converting to Unix timestamps

Agent IDs

Pagination

Time filters

Converting to Unix timestamps