Falcon API

https://falcon-bot.gitbook.io/falcon-api
Admin
Unified API for prediction market data providing real-time market data, trade history, and analytics...
Tokens:30,189
Snippets:169
Trust Score:9.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Construct a Full Response Example

Source: https://falcon-bot.gitbook.io/falcon-api/reference/api-structure.md

A complete example of a standard Falcon API response.

```json
{
  "timestamp": "2025-01-09T19:12:50Z",
  "params": {},
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": []
  }
}
```

--------------------------------

### GET /getting-started/quickstart.md

Source: https://falcon-bot.gitbook.io/falcon-api/llms.txt

Perform an HTTP GET request on the documentation index to ask a question and receive a direct answer with relevant excerpts.

```APIDOC
## GET /getting-started/quickstart.md

### Description
Perform an HTTP GET request on the documentation index with the `ask` parameter, and the optional `goal` parameter to retrieve a direct answer and relevant excerpts from the documentation.

### Method
GET

### Endpoint
https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md

### Parameters
#### Query Parameters
- **ask** (string) - Required - The immediate question to ask, written in natural language.
- **goal** (string) - Optional - Describes the broader end goal to tailor the answer.
```

--------------------------------

### cURL Request Example

Source: https://falcon-bot.gitbook.io/falcon-api/traders/top-traders.md

Example of how to call the top traders endpoint using 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": 579,
    "params": {
        "wallet_address": "ALL",
        "leaderboard_period": "1d"
    },
    "pagination": {
        "limit": 50,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

--------------------------------

### Query documentation via HTTP GET

Source: https://falcon-bot.gitbook.io/falcon-api/llms.txt

Perform a GET request to the documentation index using the ask and goal parameters to receive tailored answers.

```http
GET https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md?ask=<question>&goal=<end_goal>
```

--------------------------------

### Construct a Full Request Example

Source: https://falcon-bot.gitbook.io/falcon-api/reference/api-structure.md

A complete example of a valid Falcon API request body.

```json
{
  "agent_id": 555,
  "params": {
    "closed": "false",
    "market_slug": "bitcoin"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}
```

--------------------------------

### Polymarket Trade Response Example

Source: https://falcon-bot.gitbook.io/falcon-api/trade-data/trades/polymarket-trades.md

Example JSON response structure for a trade query.

```bash
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "1767973860",
    "market_slug": "bitcoin-up-or-down-january-9-10am-et",
    "proxy_wallet": "ALL",
    "side": "BUY",
    "start_time": "1767973812",
    "wallet_proxy": "ALL"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0x1e30835026c910cd5f676a504ce8c39666917f402dfe93bb46c19adf6b152c13",
        "outcome": "Down",
        "price": 0.001,
        "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
        "side": "BUY",
        "size": 225.23,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:51:00Z",
        "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0xb07225fa95a2b5dd0f15b3f41f07657d9eb9e928268d4e5ae9fdf7e178049ac7",
        "outcome": "Down",
        "price": 0.001,
        "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
        "side": "BUY",
        "size": 14.99,
```

--------------------------------

### Example Request (Curl)

Source: https://falcon-bot.gitbook.io/falcon-api/trade-data/trades/kalshi-trades.md

A cURL command to retrieve trade data from the specified endpoint.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 573,
    "params": {
        "ticker": "KXSOL15M-26MAR180730-30",
        "start_time": "1773589812",
        "end_time": "1774021812"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

--------------------------------

### Example Response

Source: https://falcon-bot.gitbook.io/falcon-api/trade-data/trades/kalshi-trades.md

A sample JSON response returned by the trade retrieval endpoint.

```json
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "1767973860",
    "market_slug": "bitcoin-up-or-down-january-9-10am-et",
    "proxy_wallet": "ALL",
    "side": "BUY",
    "start_time": "1767973812",
    "wallet_proxy": "ALL"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0x1e30835026c910cd5f676a504ce8c39666917f402dfe93bb46c19adf6b152c13",
        "outcome": "Down",
        "price": 0.001,
        "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
        "side": "BUY",
        "size": 225.23,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:51:00Z",
        "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0xb07225fa95a2b5dd0f15b3f41f07657d9eb9e928268d4e5ae9fdf7e178049ac7",
        "outcome": "Down",
        "price": 0.001,
        "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
        "side": "BUY",
        "size": 14.99,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:51:00Z",
        "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee"
```

--------------------------------

### Retrieve Data via Python

Source: https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md

Example using the requests library to perform a POST request.

```python
import requests

url = "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized"

headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
}

payload = {
    "agent_id": 555,
    "params": {"closed": "False"},
    "pagination": {"limit": 10, "offset": 0},
    "formatter_config": {"format_type": "raw"}
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

--------------------------------

### API Response Example

Source: https://falcon-bot.gitbook.io/falcon-api/traders/top-traders.md

Sample JSON response structure returned by the API.

```json
{
  "timestamp": "",
  "params": {
    "leaderboard_period": "1d",
    "max_sharpe_ratio": "-1.0",
    "max_total_pnl": "-1.0",
    "max_win_rate": "-1.0",
    "min_sharpe_ratio": "-1.0",
    "min_total_pnl": "-1.0",
    "min_win_rate": "-1.0",
    "wallet_address": "ALL"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "address": "0x0720803c7cb0d0c5a928787b3b7ea148c6831cdb",
        "markets_traded": 1,
        "rank": 1,
        "roi": "0.414952",
        "sharpe_ratio": null,
        "total_pnl": "1494121.7168",
        "total_trades": 69,
        "total_volume": "3600711.99",
        "win_rate": "1.0000"
      },
      {
        "address": "0xe90bec87d9ef430f27f9dcfe72c34b76967d5da2",
        "markets_traded": 50,
        "rank": 2,
        "roi": "0.355880",
        "sharpe_ratio": "0.2847",
        "total_pnl": "1092294.3287",
```

--------------------------------

### API Use Case Examples

Source: https://falcon-bot.gitbook.io/falcon-api/traders/top-traders.md

Common request patterns for retrieving leaderboard data.

```json
{
  "agent_id": 579,
  "params": {
    "wallet_address": "ALL",
    "leaderboard_period": "7d"
  }
}
```

```json
{
  "agent_id": 579,
  "params": {
    "wallet_address": "ALL",
    "leaderboard_period": "30d",
    "min_total_pnl": "1000",
    "min_win_rate": "0.5",
    "min_sharpe_ratio": "1.5"
  }
}
```

```json
{
  "agent_id": 579,
  "params": {
    "wallet_address": "0x123...",
    "leaderboard_period": "1d"
  }
}
```

--------------------------------

### Retrieve Data via cURL

Source: https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md

Example using the command line to perform a POST request.

```bash
curl -X POST https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 555,
    "params": {"closed": "False"},
    "pagination": {"limit": 10, "offset": 0},
    "formatter_config": {"format_type": "raw"}
  }'
```

--------------------------------

### Define Request Fields

Source: https://falcon-bot.gitbook.io/falcon-api/reference/api-structure.md

Individual field examples for request body configuration.

```json
"agent_id": 555
```

```json
"params": {
  "closed": "false",
  "market_slug": "bitcoin"
}
```

```json
"pagination": {
  "limit": 10,
  "offset": 0
}
```

```json
"formatter_config": {
  "format_type": "raw"
}
```

--------------------------------

### Define Response Fields

Source: https://falcon-bot.gitbook.io/falcon-api/reference/api-structure.md

Individual field examples for response data.

```json
"timestamp": "2025-01-09T19:12:50Z"
```

--------------------------------

### Retrieve Data via JavaScript

Source: https://falcon-bot.gitbook.io/falcon-api/getting-started/quickstart.md

Example using the fetch API to perform a POST request.

```javascript
const response = await fetch(
  "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_TOKEN",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      agent_id: 555,
      params: { closed: "False" },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" }
    })
  }
);

const data = await response.json();
console.log(data);
```

--------------------------------

### Example API Response for Wallet 360

Source: https://falcon-bot.gitbook.io/falcon-api/market-intelligence/falcon-wallet-360.md

A sample JSON response showing the structure of wallet performance data, including metrics such as annualized return, risk scores, and trade statistics.

```bash
{
  "timestamp": "",
  "params": {
    "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
    "window_days": "3"
  },
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "annualized_return": 4.7138,
        "avg_position_size": 2379.96,
        "best_trade": 75126.54,
        "calculation_window_days": 3,
        "calmar_ratio": null,
        "category_diversity_score": 1.6501,
        "coefficient_of_variation": 3.9035,
        "combined_risk_score": 10,
        "curve_smoothness": 0.0292,
        "date": "2026-03-15T00:00:00Z",
        "date_range_end": "2026-03-15T00:00:00Z",
        "date_range_start": "2026-03-13T00:00:00Z",
        "days_active": 3,
        "dominant_market_id": "0x42a016b0a4bdf4de840334551b04bda95fcf02e4626c60bb49e3b1f1530067a3",
        "dominant_market_pnl": -68490.68,
        "drawdown_frequency": 0,
        "edge_decay": null,
        "equity_curve_pattern": "volatile",
        "flagged_metrics": "{position_size_volatility}",
        "gain_to_pain_ratio": 100,
        "last_active": "2026-03-15T23:59:59.999999Z",
        "losing_trades": 2086,
        "market_concentration_ratio": 0.029,
        "markets_traded": 3146,
        "max_drawdown": 0,
        "max_position_pct": 0.3048,
        "num_markets_traded": 3146,
        "perfect_entry_count": 1204,
        "perfect_exit_count": 0,
        "perfect_timing_flag": false,
        "perfect_timing_score": 0.2258,
        "performance_by_category": "W3sicG5sIjogMTYxNzE3LjY4LCAidHJhZGVzIjogNjQwMCwgImNhdGVnb3J5IjogIk90aGVyIn0sIHsicG5sIjogNTgzMDguNTgsICJ0cmFkZXMiOiAyODUsICJjYXRlZ29yeSI6ICJXb3JsZCBFdmVudHMifSwgeyJwbmwiOiA0NzI1OS45OSwgInRyYWRlcyI6IDkzNSwgImNhdGVnb3J5IjogIlNwb3J0cyJ9LCB7InBubCI6IDIyNzk5LjEyLCAidHJhZGVzIjogODIsICJjYXRlZ29yeSI6ICJTY2llbmNlICYgVGVjaCJ9XQ==",
        "performance_trend": "improving",
        "position_size_consistency": 0,
        "position_size_volatility_flag": true,
        "profit_factor": 1.0972,
        "proxy_wallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
        "recovery_time_avg": 0,
        "risk_level": "LOW",
        "roi": 3.8743,
        "sharpe_ratio": 50,
        "similar_wallets_count": 0,
        "single_market_dependence_flag": false,
        "sortino_ratio": null,
        "statistical_confidence": 0.9966,
        "stddev_position_size": 4645.09,
        "suspicious_timing_trades": 0,
        "suspicious_win_rate_flag": false,
        "sybil_risk_flag": false,
        "sybil_risk_score": 0,
        "timing_anomaly_flag": false,
        "timing_hit_rate": 0,
        "timing_z_score": 0.61,
        "total_closed_positions": 2666,
        "total_invested": 7487360.92,
        "total_pnl": 290085.37,
        "total_timed_trades": 85719,
        "total_trades": 85719,
        "trade_size_stdev": 418.9442,
        "trade_timing_correlation_max": 0,
        "ulcer_index": 0,
        "win_rate": 0.522,
        "win_rate_last_30d": 0.5133,
        "win_rate_z_score": -5.37,
        "winning_trades": 2278,
        "worst_trade": -83113.9
      },
      {
        "annualized_return": -8.6915,
        "avg_position_size": 2045.27,
        "best_trade": 51771.41,
        "calculation_window_days": 3,
        "calmar_ratio": -86.6618,
        "category_diversity_score": 0.6255,
        "coefficient_of_variation": 4.0603,
        "combined_risk_score": 10,
        "curve_smoothness": 0.1176,
        "date": "2026-03-14T00:00:00Z",
        "date_range_end": "2026-03-14T00:00:00Z",
        "date_range_start": "2026-03-12T00:00:00Z",
        "days_active": 3,
        "dominant_market_id": "0x09eb95f347c8ca17d639371297175ed15f397c531e8ef13286382cda2a2595d1",
        "dominant_market_pnl": -178633.03,
        "drawdown_frequency": 0.3333,
        "edge_decay": null,
        "equity_curve_pattern": "volatile",
        "flagged_metrics": "{position_size_volatility}",
        "gain_to_pain_ratio": -0.776,
        "last_active": "2026-03-14T23:59:59.999999Z",
        "losing_trades": 1452,
        "market_concentration_ratio": 0.0507,
        "markets_traded": 2704,
        "max_drawdown": 0.1003,
        "max_position_pct": 0.4194,
        "num_markets_traded": 2704,
        "perfect_entry_count": 772,
        "perfect_exit_count": 0,
        "perfect_timing_flag": false,
        "perfect_timing_score": 0.172,

```

--------------------------------

### Orderbook Request via cURL

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/orderbook.md

Example of how to perform the orderbook request using the curl command-line tool.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 572,
    "params": {
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
        "start_time": "1769902905868",
        "end_time": "1770034843377"
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

--------------------------------

### Configure Pagination

Source: https://falcon-bot.gitbook.io/falcon-api/reference/core-concepts.md

Control the result set size and starting position using limit and offset parameters.

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

```json
offset = limit × (page - 1)
offset = 25 × (3 - 1)
offset = 50
```

--------------------------------

### Polymarket Trade cURL Request

Source: https://falcon-bot.gitbook.io/falcon-api/trade-data/trades/polymarket-trades.md

Example cURL command to retrieve trade data from the API.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 556,
    "params": {
        "proxy_wallet": "ALL",
        "condition_id": "ALL",
        "market_slug": "bitcoin-up-or-down-january-9-10am-et",
        "side": "BUY",
        "start_time": "1767973812",
        "end_time": "1767973860"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

--------------------------------

### Market Insights API Example Response

Source: https://falcon-bot.gitbook.io/falcon-api/market-intelligence/market-insights.md

A sample JSON response showing the structure of market data, including pagination, request parameters, and a list of market results.

```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
```

--------------------------------

### Example Polymarket Market Response

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/markets/polymarket-markets.md

A sample JSON response showing the structure of market data, including pagination metadata and a list of market results.

```json
{
  "timestamp": "",
  "params": {
    "closed": "True",
    "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
    "end_date_max": "1769213303",
    "end_date_min": "1768467703",
    "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
    "market_slug": "bitcoin-up-or-down-january-17-3pm-et",
    "min_volume": "100"
  },
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "closed": true,
        "closed_date": "2026-01-17T22:07:24Z",
        "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
        "end_date": "2026-01-17T21:00:00Z",
        "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "question": "Bitcoin Up or Down - January 17, 3PM ET",
        "side_a_outcome": "Up",
        "side_a_token_id": "54962395221233298907357564706944806093710338832907683007646483576474886134345",
        "side_b_outcome": "Down",
        "side_b_token_id": "99436386356623686771311452414494038846982778884699006473918967429453507432222",
        "slug": "bitcoin-up-or-down-january-17-3pm-et",
        "start_date": "2026-01-15T20:01:06.506385Z",
        "volume_total": 104456.760687,
        "winning_outcome": "Up"
      }
    ]
  }
}
```

--------------------------------

### cURL Request for Lifetime Performance

Source: https://falcon-bot.gitbook.io/falcon-api/traders/lifetime-performance.md

Example cURL command to retrieve lifetime performance data for a specific wallet address.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 586,
    "params": {
        "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
    },
    "pagination": {
        "limit": 50,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

--------------------------------

### Orderbook API Response

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/orderbook.md

Example response structure containing orderbook snapshots.

```json
{
  "timestamp": "",
  "params": {
    "end_time": "1770034843377",
    "start_time": "1769902905868",
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "asks": "[{\"size\": \"60\", \"price\": \"0.99\"}, {\"size\": \"723.17\", \"price\": \"0.93\"}, {\"size\": \"12\", \"price\": \"0.91\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"25\", \"price\": \"0.02\"}, {\"size\": \"5.63\", \"price\": \"0.03\"}, {\"size\": \"12\", \"price\": \"0.09\"}, {\"size\": \"12\", \"price\": \"0.19\"}, {\"size\": \"200\", \"price\": \"0.28\"}, {\"size\": \"29.48\", \"price\": \"0.29\"}]",
        "timestamp": "2026-02-02T12:01:20.885Z",
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
      },
      {
        "asks": "[{\"size\": \"60\", \"price\": \"0.99\"}, {\"size\": \"5\", \"price\": \"0.98\"}, {\"size\": \"723.17\", \"price\": \"0.93\"}, {\"size\": \"12\", \"price\": \"0.91\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"30\", \"price\": \"0.02\"}, {\"size\": \"5.63\", \"price\": \"0.03\"}, {\"size\": \"12\", \"price\": \"0.09\"}, {\"size\": \"12\", \"price\": \"0.19\"}, {\"size\": \"200\", \"price\": \"0.28\"}, {\"size\": \"29.48\", \"price\": \"0.29\"}]",
        "timestamp": "2026-02-02T10:29:08.324Z",
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
      },
      {
        "asks": "[{\"size\": \"60\", \"price\": \"0.99\"}, {\"size\": \"5\", \"price\": \"0.98\"}, {\"size\": \"714.29\", \"price\": \"0.93\"}, {\"size\": \"23.1\", \"price\": \"0.91\"}]",
        "bids": "[{\"size\": \"60\", \"price\": \"0.01\"}, {\"size\": \"30\", \"price\": \"0.02\"}, {\"size\": \"5.63\", \"price\": \"0.03\"}, {\"size\": \"12\", \"price\": \"0.09\"}, {\"size\": \"12\", \"price\": \"0.19\"}, {\"size\": \"200\", \"price\": \"0.28\"}, {\"size\": \"29.48\", \"price\": \"0.29\"}]",
        "timestamp": "2026-02-02T09:53:57.168Z",
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235"
      },
      {
        "asks": "[{\"size\": \"60\", \"price\": \"0.99\"}, {\"size\": \"5\", \"price\": \"0.98\"}, {\"size\": \"714.29\", \"price\": \"0.93\"}, {\"size\": \"357\", \"price\": \"0.92\"}, {\"size\": \"23.1\", \"price\": \"0.91\"}]",
```

--------------------------------

### API Response Structure

Source: https://falcon-bot.gitbook.io/falcon-api/traders/lifetime-performance.md

Example JSON response containing historical trading metrics for the requested wallet.

```json
{
  "timestamp": "",
  "params": {
    "wallet_address": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "avg_pnl_per_trade": "2.26",
        "avg_trade_size": "122.24",
        "last_updated": "2026-03-14T00:00:00Z",
        "proxy_wallet": "0x6ac5bb06a9eb05641fd5e82640268b92f3ab4b6e",
        "roi_pct": "1.85",
        "total_invested": "22785473.35",
        "total_pnl": "420395.44",
        "total_trades": 186403
      }
    ]
  }
}
```

--------------------------------

### Example Candlestick Response

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/candlesticks.md

A sample JSON response showing the structure of candlestick data, including pagination and an array of market results.

```bash
{
  "timestamp": "",
  "params": {
    "end_time": "1770083100",
    "interval": "4h",
    "start_time": "1769910300",
    "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622"
  },
  "pagination": {
    "limit": 200,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "ask_close": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": null,
        "bid_close": null,
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": null,
        "candle_time": "2026-02-01T00:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5033",
        "open": "0.5000",
        "outcome": "No",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 6,
        "volume": "135.97"
      },
      {
        "ask_close": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": "0.9900",
        "bid_close": null,
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": "0.0100",
        "candle_time": "2026-02-01T04:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5038",
        "open": "0.5000",
        "outcome": "No",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 15,
        "volume": "1020.08"
      },
      {
        "ask_close": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": null,
        "bid_close": null,
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": null,
        "candle_time": "2026-02-01T08:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5095",
        "open": "0.5100",
        "outcome": "No",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 62,
        "volume": "1137.14"
      },
      {
        "ask_close": null,
        "ask_high": "0.9900",
        "ask_low": "0.5100",
        "ask_open": null,
        "bid_close": null,
        "bid_high": "0.5000",
        "bid_low": "0.0100",
        "bid_open": null,
        "candle_time": "2026-02-01T12:00:00Z",
        "close": "0.5100",
        "condition_id": "0x18b1c135d0a40c5894da9412e77311827d9caf16cf4cd6591b247a34730af919",
        "high": "0.5100",
        "low": "0.5000",
        "mean": "0.5046",
        "open": "0.5100",
        "outcome": "No",
        "token_id": "78633590736077251574794513664747155551297291244492840448622550955320930591622",
        "trade_count": 137,
        "volume": "2748.29"
      }
    ]
  }
}
```

--------------------------------

### Polymarket Data Request via cURL

Source: https://falcon-bot.gitbook.io/falcon-api/market-data/markets/polymarket-markets.md

Example cURL command to fetch Polymarket data using a Bearer token for authentication.

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 574,
    "params": {
        "min_volume": "100",
        "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
        "market_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "end_date_min": "1768467703",
        "end_date_max": "1769213303",
        "closed": "True"
    },
    "pagination": {
        "limit": 100,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

--------------------------------

### GET /traders/profit-and-loss

Source: https://falcon-bot.gitbook.io/falcon-api/traders/profit-and-loss.md

Retrieves aggregated profit and loss metrics for a specified wallet over a defined time range.

```APIDOC
## GET /traders/profit-and-loss

### Description
Retrieves aggregated profit and loss metrics for a specified wallet over a defined time range. The data can be filtered by market condition and aggregated by different time granularities.

### Query Parameters
- **wallet** (String) - Required - The wallet address for which performance is calculated.
- **start_time** (String) - Required - Start date for the metrics (ISO 8601).
- **end_time** (String) - Required - End date for the metrics (ISO 8601).
- **granularity** (String) - Required - Time interval for aggregation (e.g., 1d, 1w, 1m).
- **condition_id** (String) - Optional - Market condition ID to isolate performance. Defaults to "ALL".
- **limit** (Integer) - Optional - Maximum number of results to return.
- **offset** (Integer) - Optional - Number of results to skip.

### Response
#### Success Response (200)
- **date** (String) - Date for which the metrics are aggregated
- **proxy_wallet** (String) - Wallet address for which performance is calculated
- **invested** (String) - Total amount invested during the period
- **pnl** (String) - Net realized profit and loss for the period
- **trades** (Integer) - Total number of trades executed during the period
- **wins** (Integer) - Number of profitable trades
- **losses** (Integer) - Number of losing trades
- **win_rate** (String) - Win rate for the period

#### Response Example
{
  "data": {
    "results": [
      {
        "date": "2026-02-19T00:00:00Z",
        "invested": "830494.18",
        "losses": 0,
        "pnl": "0.00",
        "proxy_wallet": "0x8e433d051bfb5cc6a1f7e5a0452029b7ffb4a3cd",
        "trades": 3342,
        "win_rate": "0.00",
        "wins": 0
      }
    ]
  }
}
```
Tokens:
Raw