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

# Forecastex

> IBKR event contract data with open interest (read-only)

<Card title="Join the Graylayer Discord" icon="discord" href="https://discord.gg/UxGa5C4C2A" horizontal>
  Request an API key in **#api-key-request** under the Community tab.
</Card>

**Platform key:** `forecastex` · Path-based routing to forecastex.com and IBKR Client Portal Gateway.

Forecastex provides Interactive Brokers event contract data. The integration is read-only—no trading endpoints.

## forecastex.com paths

**Upstream:** `https://forecastex.com/api`

| Method | Path         | Description          |
| ------ | ------------ | -------------------- |
| GET    | `/contracts` | List event contracts |

### Query parameters for `/contracts`

| Parameter   | Type    | Description                                       |
| ----------- | ------- | ------------------------------------------------- |
| `page`      | integer | Page number (1-indexed)                           |
| `pageSize`  | integer | Results per page                                  |
| `sortBy`    | string  | Field to sort by (e.g. `open_interest`, `volume`) |
| `sortOrder` | string  | `asc` or `desc`                                   |

<CodeGroup>
  ```bash Top by open interest theme={null}
  curl -H "X-API-Key: your_key" \
    "http://gateway.graylayer.tech/api/v1/forecastex/contracts?page=1&pageSize=100&sortBy=open_interest&sortOrder=desc"
  ```

  ```bash Top by volume theme={null}
  curl -H "X-API-Key: your_key" \
    "http://gateway.graylayer.tech/api/v1/forecastex/contracts?page=1&pageSize=50&sortBy=volume&sortOrder=desc"
  ```
</CodeGroup>

## IBKR Gateway paths

**Upstream:** `https://localhost:5000/v1/api` or `https://api.ibkr.com/v1/api`

Requires [IBKR Client Portal Gateway](https://www.interactivebrokers.com/campus/ibkr-api-page/cpapi-v1/) running locally. Set `FORECASTEX_IBKR_BASE_URL` in `.env`. Tickle runs every 60s to keep the session alive.

| Method | Path                           | Description                                     |
| ------ | ------------------------------ | ----------------------------------------------- |
| GET    | `/trsrv/event/category-tree`   | Event contract category tree                    |
| GET    | `/tickle`                      | Keep session alive                              |
| GET    | `/iserver/secdef/search`       | Search underlying index (query: `symbol`)       |
| GET    | `/iserver/secdef/strikes`      | Strike values                                   |
| GET    | `/iserver/secdef/info`         | Contract info                                   |
| GET    | `/forecast/category/tree`      | Category tree                                   |
| GET    | `/forecast/contract/details`   | Contract details (query: `conid`)               |
| GET    | `/forecast/contract/market`    | Contracts for market (query: `underlyingConid`) |
| GET    | `/forecast/contract/rules`     | Contract rules (query: `conid`)                 |
| GET    | `/forecast/contract/schedules` | Trading schedules (query: `conid`)              |

<CodeGroup>
  ```bash Category tree theme={null}
  curl -H "X-API-Key: your_key" \
    "http://gateway.graylayer.tech/api/v1/forecastex/trsrv/event/category-tree"
  ```

  ```bash Tickle (keep session alive) theme={null}
  curl -H "X-API-Key: your_key" \
    "http://gateway.graylayer.tech/api/v1/forecastex/tickle"
  ```

  ```bash Contract details theme={null}
  curl -H "X-API-Key: your_key" \
    "http://gateway.graylayer.tech/api/v1/forecastex/forecast/contract/details?conid=12345"
  ```
</CodeGroup>