> For the complete documentation index, see [llms.txt](https://falcon-bot.gitbook.io/falcon-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://falcon-bot.gitbook.io/falcon-api/market-intelligence/market-insights.md).
# Market Insights
### Request Body (JSON)
```json
{
"agent_id": 575,
"params": {
"condition_id": "ALL",
"min_volume_24h" : "0",
"min_liquidity_percentile" : "0",
"volume_trend" : "ALL",
"min_top1_wallet_pct" : "0",
"max_unique_traders_7d" : "0"
},
"formatter_config": {
"format_type": "raw"
}
}
```
***
### Available Filters
| Parameter | Type | Description | Example |
| -------------------------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `condition_id` | String | Polymarket condition ID for a specific market. If omitted, insights are returned for all markets. | `"0xb0fb3465776819e046065164c6fc558e9d3d7da36cd7a2ef7c7688791784e97d"` |
| `min_volume_24h` | String | Minimum trading volume in the last 24 hours. | `"50000"` |
| `min_liquidity_percentile` | String | Minimum liquidity percentile relative to all active markets (0–100). | `"70"` |
| `volume_trend` | String | Filter by activity trend. Options: `Spiking`, `Normal`, `Declining`, `Dying Interest`, `No Trades`, `ALL`. | `"Spiking"` |
| `min_top1_wallet_pct` | String | Minimum percentage of exposure controlled by the largest wallet. | `"60"` |
| `max_unique_traders_7d` | String | Maximum number of unique traders over the last 7 days. | `"10"` |
Example Request (cURL)
```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
"agent_id": 575,
"params": {
"condition_id": "ALL",
"min_volume_24h" : "0",
"min_liquidity_percentile" : "0",
"volume_trend" : "ALL",
"min_top1_wallet_pct" : "0",
"max_unique_traders_7d" : "0"
},
"formatter_config": {
"format_type": "raw"
}
}'
```
***
### Response Fields
| Field | Type | Description |
| -------------------------- | ----------------- | ------------------------------------------------------- |
| `snapshot_time` | String (ISO 8601) | Timestamp when the market snapshot was generated |
| `condition_id` | String | Unique Polymarket market identifier |
| `slug` | String | Market slug |
| `question` | String | Market question |
| `end_date` | String (ISO 8601) | Market resolution date |
| `market_active` | Boolean | Indicates whether the market is currently active |
| `market_closed` | Boolean | Indicates whether the market has closed |
| `current_volume_24h` | Decimal | Volume traded in the last 24 hours |
| `current_volume_7d` | Decimal | Volume traded in the last 7 days |
| `liquidity_percentile` | Decimal | Relative liquidity ranking across markets |
| `liquidity_tier` | String | Liquidity classification (`Low`, `Medium`, `High`) |
| `volume_trend` | String | Activity trend classification |
| `top1_wallet_pct` | Decimal | Percentage of exposure controlled by the largest wallet |
| `top3_wallet_pct` | Decimal | % exposure controlled by top wallet |
| `what_control_flag` | Boolean | TRUE if whale dominance detected |
| `unique_traders_7d` | Integer | Distinct traders over last 7 days |
| `trades_per_hour_avg` | Decimal | Average hourly trade count |
| `peak_hour_trades` | Integer | Maximum trades in a single hour |
| `trade_concentration_flag` | Bolean | TRUE if trading is highly concentrated |
| `create_at` | String (ISO 8601) | Record creation timestamp |
| `updated_at` | String (ISO 8601) | Last update timestamp |
Example Response
```bash
{
"timestamp": "",
"params": {
"condition_id": "ALL",
"max_unique_traders_7d": "0",
"min_liquidity_percentile": "0",
"min_top1_wallet_pct": "0",
"min_volume_24h": "0",
"volume_trend": "ALL"
},
"pagination": {
"limit": 200,
"offset": 0,
"has_more": true
},
"data": {
"results": [
{
"condition_id": "0x3488f31e6449f9803f99a8b5dd232c7ad883637f1c86e6953305a2ef19c77f20",
"created_at": "2026-02-09T16:53:53.025942Z",
"current_volume_24h": "33167793.852374",
"current_volume_7d": "232174556.966617",
"end_date": "2026-01-31T00:00:00Z",
"liquidity_percentile": "99.99",
"liquidity_tier": "Top 5%",
"market_active": true,
"market_closed": false,
"peak_hour_trades": 0,
"question": "US strikes Iran by February 28, 2026?",
"slug": "us-strikes-iran-by-february-28-2026-227-967-547-688-589-491-592-418-452-924-384-915-464-672-196-157-993-596-269-535-381-391-471-256-988-997-296-225-762-973-292-827-345-182-558-215-794-879-189-761",
"snapshot_time": "2026-03-15T18:00:00.009086Z",
"top1_wallet_pct": "0.00",
"top3_wallet_pct": "0.00",
"trade_concentration_flag": false,
"trades_per_hour_avg": "0.00",
"unique_traders_7d": 0,
"updated_at": "2026-03-15T18:00:00.009086Z",
"volume_trend": "No Trades",
"whale_control_flag": false
},
{
"condition_id": "0x25aa90b3cd98305e849189b4e8b770fc77fe89bccb7cf9656468414e01145d38",
"created_at": "2026-02-09T16:53:53.025942Z",
"current_volume_24h": "16256726.751000",
"current_volume_7d": "113011287.577520",
"end_date": "2026-03-18T00:00:00Z",
"liquidity_percentile": "100.00",
"liquidity_tier": "Top 5%",
"market_active": true,
"market_closed": false,
"peak_hour_trades": 234,
"question": "Will the Fed increase interest rates by 25+ bps after the March 2026 meeting?",
"slug": "will-the-fed-increase-interest-rates-by-25-bps-after-the-march-2026-meeting",
"snapshot_time": "2026-03-15T18:00:00.009086Z",
"top1_wallet_pct": "17.92",
"top3_wallet_pct": "43.57",
"trade_concentration_flag": false,
"trades_per_hour_avg": "74.75",
"unique_traders_7d": 3990,
"updated_at": "2026-03-15T18:00:00.009086Z",
"volume_trend": "Normal",
"whale_control_flag": false
},
{
"condition_id": "0x7a4e96623e5baf75e3a039b1fdae23b288f84333f8d3c1ae6dbfbf6075330325",
"created_at": "2026-02-28T18:00:00.023274Z",
"current_volume_24h": "13463478.939656",
"current_volume_7d": "36912985.480812",
"end_date": null,
"liquidity_percentile": "99.92",
"liquidity_tier": "Top 5%",
"market_active": true,
"market_closed": false,
"peak_hour_trades": 0,
"question": "Will Iran strike Israel on March 6?",
"slug": "will-iran-strike-israel-on-march-6",
"snapshot_time": "2026-03-15T18:00:00.009086Z",
"top1_wallet_pct": "13.15",
"top3_wallet_pct": "34.22",
"trade_concentration_flag": false,
"trades_per_hour_avg": "0.00",
"unique_traders_7d": 2333,
"updated_at": "2026-03-15T18:00:00.009086Z",
"volume_trend": "Spiking",
"whale_control_flag": false
},
{
"condition_id": "0xd4bbf7f6707c67beb736135ad32a41f6db41f8ae52d3ac4919650de9eeb94ed8",
"created_at": "2026-02-09T16:53:53.025942Z",
"current_volume_24h": "13076878.995525",
"current_volume_7d": "210780670.966638",
"end_date": "2026-02-28T00:00:00Z",
"liquidity_percentile": "100.00",
"liquidity_tier": "Top 5%",
"market_active": true,
"market_closed": false,
"peak_hour_trades": 431,
"question": "Khamenei out as Supreme Leader of Iran by February 28?",
"slug": "khamenei-out-as-supreme-leader-of-iran-by-february-28",
"snapshot_time": "2026-03-03T18:00:00.008741Z",
"top1_wallet_pct": "8.82",
"top3_wallet_pct": "24.16",
"trade_concentration_flag": false,
"trades_per_hour_avg": "191.08",
"unique_traders_7d": 17172,
"updated_at": "2026-03-03T18:00:00.008741Z",
"volume_trend": "Significant Decline",
"whale_control_flag": false
},
{
"condition_id": "0x7cb525e831729325d651017f81cbcb6f1adde5011c7b2283babea00b4ae93ae7",
"created_at": "2026-03-02T18:00:00.021712Z",
"current_volume_24h": "11983356.042356",
"current_volume_7d": "26564920.470856",
"end_date": "2026-12-31T00:00:00Z",
"liquidity_percentile": "99.87",
"liquidity_tier": "Top 5%",
"market_active": true,
"market_closed": false,
"peak_hour_trades": 2564,
"question": "Netanyahu out by March 31?",
"slug": "netanyahu-out-by-march-31-854",
"snapshot_time": "2026-03-15T18:00:00.009086Z",
"top1_wallet_pct": "6.12",
"top3_wallet_pct": "14.91",
"trade_concentration_flag": false,
"trades_per_hour_avg": "1097.21",
"unique_traders_7d": 4234,
"updated_at": "2026-03-15T18:00:00.009086Z",
"volume_trend": "Spiking",
"whale_control_flag": false
},
{
"condition_id": "0x09cbe3e796661a1d820580145488ad2ccb9ad1e720efcd64b448bb77b97007c1",
"created_at": "2026-02-17T16:08:30.954689Z",
"current_volume_24h": "11321214.533125",
"current_volume_7d": "79248501.731875",
"end_date": "2026-01-31T00:00:00Z",
"liquidity_percentile": "98.37",
"liquidity_tier": "Top 5%",
"market_active": true,
"market_closed": false,
"peak_hour_trades": 0,
"question": "US strikes Iran by February 27, 2026?",
"slug": "us-strikes-iran-by-february-27-2026",
"snapshot_time": "2026-03-15T18:00:00.009086Z",
"top1_wallet_pct": "0.00",
"top3_wallet_pct": "0.00",
"trade_concentration_flag": false,
"trades_per_hour_avg": "0.00",
"unique_traders_7d": 0,
"updated_at": "2026-03-15T18:00:00.009086Z",
"volume_trend": "No Trades",
"whale_control_flag": false
},
{
"condition_id": "0xda368e1f843931105e33e4d00c06e20f962ffc233389b8df15f53efc9d3d2984",
"created_at": "2026-02-09T16:53:53.025942Z",
"current_volume_24h": "11258479.740314",
"current_volume_7d": "78809358.182198",
"end_date": "2026-01-31T00:00:00Z",
"liquidity_percentile": "99.98",
"liquidity_tier": "Top 5%",
"market_active": true,
"market_closed": false,
"peak_hour_trades": 0,
"question": "US strikes Iran by February 9, 2026?",
"slug": "us-strikes-iran-by-february-9-2026-113-751",
"snapshot_time": "2026-03-15T18:00:00.009086Z",
"top1_wallet_pct": "0.00",
"top3_wallet_pct": "0.00",
"trade_concentration_flag": false,
"trades_per_hour_avg": "0.00",
"unique_traders_7d": 0,
"updated_at": "2026-03-15T18:00:00.009086Z",
"volume_trend": "No Trades",
"whale_control_flag": false
}
]
}
}
```
***
### Example Use Cases
#### 1. Whale-Dominated Markets
Identify markets where a large wallet controls significant exposure and trading activity is increasing.
```
min_volume_24h=50000
min_liquidity_percentile=70
volume_trend=Spiking
min_top1_wallet_pct=60
max_unique_traders_7d=20
```
#### 2. Healthy Crowd-Driven Markets
Find markets with strong participation and deep liquidity.
```
min_volume_24h=100000
min_liquidity_percentile=80
volume_trend=Normal
min_top1_wallet_pct=0
max_unique_traders_7d=0
```
#### 3. Fragile Market Structures
Detect markets where whale dominance and low participation may lead to fragile price discovery.
```
volume_trend=Spiking
min_top1_wallet_pct=70
max_unique_traders_7d=10
```
***
### Notes
* Use `min_volume_24h` together with `min_liquidity_percentile` to filter for **active markets with sufficient liquidity**, which improves execution quality and reduces slippage.
* Monitor `volume_trend` to identify **markets experiencing accelerating activity**, such as those with `"Spiking"` volume patterns.
* Use `top1_wallet_pct` and `top3_wallet_pct` to detect **whale-dominated markets**, where a small number of traders control a large portion of exposure.
* Check `unique_traders_7d` to evaluate **participation diversity**, which helps distinguish crowd-driven markets from low-participation ones.
* Use `trade_concentration_flag` and `whale_control_flag` to quickly identify markets with **potential structural risks or concentrated trading behavior**.
* Compare `current_volume_24h`, `current_volume_7d`, and `trades_per_hour_avg` to understand **how trading activity evolves over time**.
* Combine liquidity metrics with trader participation metrics to identify **healthy markets where price discovery is likely to be reliable**.