> For the complete documentation index, see [llms.txt](https://docs.lighter.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lighter.xyz/developers/binary-options/discover-markets.md).

# Discover markets

Find events and market IDs, follow the market lifecycle, and query the underlying price.

Markets are grouped into **events**. An event describes the question (title, description, observation window) and links to the market that trades it. For Up/Down series each window is one event with one market, and all windows of a series share a `tag`.

## Query events

Start without a `tag` filter to discover currently tradable events:

```shell
curl "https://mainnet.zklighter.elliot.ai/api/v1/events?active=true&sort=start_at&order=asc&limit=10"
```

To follow a particular series, use its returned `tag` in subsequent requests. Read its underlying asset and observation duration from the event metadata. The examples below use `eth` and `15m` to illustrate the response and request formats.

[events](https://docs.lighter.xyz/api/binary-options) (`GET /api/v1/events`) is public and accepts:

| Parameter                    | Notes                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `tag`                        | Optional series filter. Use a tag returned by `events`; `eth-updown-15m` is an example of the format    |
| `active`                     | `true`: at least one outcome still tradeable · `false`: scheduled and closed events only                |
| `event_ids`, `market_ids`    | Up to 50 comma-separated IDs; mutually exclusive. `market_ids` returns the event each market belongs to |
| `creator_account_index`      | Optional additional filter                                                                              |
| `event_kind`                 | `one_off` or `recurrent`                                                                                |
| `start_from`, `start_before` | Filter on `start_at` (inclusive / exclusive), Unix ms                                                   |
| `sort`, `order`              | `id` (default) or `start_at`; `desc` (default) or `asc`                                                 |
| `cursor`, `limit`            | Pagination; pass `next_cursor` as `cursor`. `limit` 1–100                                               |

### Event fields

| Field                                            | Meaning                                                                                                        |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `event_id`, `title`, `description`               | Event identity and question                                                                                    |
| `tag`, `event_kind`, `recurrence_period_seconds` | Series, event type and recurrence interval                                                                     |
| `start_at`, `end_at`                             | Observation window, in Unix milliseconds. Trading can open before observation starts                           |
| `metadata`                                       | Series metadata, including `symbol`, `duration`, `provider`, `feed_id`, `market_id` and `underlying_market_id` |
| `order_books[]`                                  | Market definitions and their live `stats`                                                                      |
| `lifetime_quote_token_volume`                    | Total lifetime quote-token volume for the event                                                                |

### Market fields

Each entry in `order_books[]` includes:

| Field                                                                    | Meaning                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `market_id`, `symbol`, `market_type`                                     | Use `market_id` everywhere else, like any other market                                                                                                                                                                                                                                |
| `status`                                                                 | See [Market lifecycle](#market-lifecycle)                                                                                                                                                                                                                                             |
| `taker_fee`, `maker_fee`                                                 | Maximum fee rates in percent, e.g. `"1.0000"` = 1% (see [Fees](/developers/binary-options/trading-and-fees.md#fees))                                                                                                                                                                  |
| `size_decimals`, `price_decimals`, `min_base_amount`, `min_quote_amount` | Integer scaling and order minimums (see [Integer prices and sizes](/developers/getting-started/core-concepts.md#integer-prices-and-sizes))                                                                                                                                            |
| `start_timestamp`, `end_timestamp`                                       | Trading window in Unix ms, separate from the observation window. In the mainnet example below, trading opens two hours before `start_at`. Read each market's actual timestamps; create and modify requests are rejected outside this window. A `0` start means tradeable from listing |
| `is_frozen`                                                              | Whether the operator has frozen the order book; create and modify requests are rejected while frozen                                                                                                                                                                                  |
| `base_asset_id`, `quote_asset_id`                                        | Asset IDs; both are `3` (USDC) for Up/Down markets                                                                                                                                                                                                                                    |
| `order_quote_limit`                                                      | Maximum quote value of an order                                                                                                                                                                                                                                                       |
| `settlement_type`                                                        | `0`: discrete; `1`: continuous. Up/Down markets use discrete settlement                                                                                                                                                                                                               |
| `settlement_cap`                                                         | Full payout per share in price ticks (`100` = `1.00` USDC). Order prices must be below it                                                                                                                                                                                             |
| `default_price`                                                          | Price the market settles at if no outcome can be determined (`50` = `0.50` USDC per share to both sides)                                                                                                                                                                              |
| `settlement_price`, `outcome`                                            | Settlement price in price ticks and outcome, set at settlement. `outcome`: `0` none, `1` No/Down, `2` Yes/Up                                                                                                                                                                          |
| `operator_account_index`                                                 | Account that creates and settles the market                                                                                                                                                                                                                                           |
| `market_deployer`                                                        | Deployer label, currently `"lighter"` for Lighter-operated markets; external deployers may have a different label                                                                                                                                                                     |
| `stats`                                                                  | `best_bid_price`, `best_ask_price`, `mid_price`, `last_trade_price`, `daily_*` volume and price stats, `lifetime_quote_token_volume`, `open_interest`, `status`, `outcome`                                                                                                            |

### Example response

This mainnet response was captured on October 19, 2026. It shows a 15-minute ETH Up/Down market whose trading window opens two hours before the observation window (`start_timestamp = start_at − 7,200,000` milliseconds). The ID and status are a snapshot: query `events` for current markets and read their configuration before trading.

```json
{
  "code": 200,
  "events": [
    {
      "event_id": 107,
      "title": "ETH Up or Down",
      "description": "Up if the chainlink ETH price at the end of the 15m window is at least the one at its start.",
      "creator_account_index": 761897,
      "created_at": 1792409448058,
      "tag": "eth-updown-15m",
      "event_kind": "recurrent",
      "recurrence_period_seconds": 900,
      "start_at": 1792436400000,
      "end_at": 1792437300000,
      "metadata": {
        "duration": "15m",
        "feed_id": "0x0002fbf9f58ef89c93385770d289d7c10c01c250641daa811063e303ee095593",
        "market_id": 4206,
        "provider": "chainlink",
        "symbol": "eth",
        "type": "updown",
        "underlying_market_id": 0
      },
      "order_books": [
        {
          "symbol": "ETH-UPDOWN-15M-1792436400",
          "market_id": 4206,
          "market_type": "binary_options",
          "base_asset_id": 3,
          "quote_asset_id": 3,
          "status": "active",
          "taker_fee": "1.0000",
          "is_taker_fee_enabled": true,
          "maker_fee": "0.0000",
          "is_maker_fee_enabled": false,
          "liquidation_fee": "0.0000",
          "min_base_amount": "5.0000",
          "min_quote_amount": "0.000001",
          "order_quote_limit": "281474976.710655",
          "supported_size_decimals": 4,
          "supported_price_decimals": 2,
          "supported_quote_decimals": 6,
          "created_at": "1792409447862",
          "multiplier": "1.000000000000000000",
          "start_timestamp": 1792429200000,
          "end_timestamp": 1792437300000,
          "open_interest": "0.0000",
          "outcome": 0,
          "operator_account_index": 761897,
          "settlement_cap": 100,
          "settlement_type": 0,
          "settlement_price": 0,
          "default_price": 50,
          "is_frozen": false,
          "market_deployer": "lighter",
          "size_decimals": 4,
          "price_decimals": 2,
          "stats": {
            "symbol": "ETH-UPDOWN-15M-1792436400",
            "market_id": 4206,
            "mid_price": "",
            "best_ask_price": "",
            "best_bid_price": "",
            "last_trade_price": "0.00",
            "daily_base_token_volume": 0,
            "daily_quote_token_volume": 0,
            "daily_price_low": 0,
            "daily_price_high": 0,
            "daily_price_change": 0,
            "lifetime_quote_token_volume": 0,
            "lifetime_base_token_volume": 0,
            "open_interest": "0.0000",
            "status": "active",
            "outcome": 0
          }
        }
      ],
      "lifetime_quote_token_volume": 0
    }
  ]
}
```

Poll `events` (or subscribe to `bo_market_stats/all`, see [WebSocket](/developers/binary-options/websocket.md)) to roll from one window to the next. Markets of a series are listed a limited time ahead; do not hard-code market IDs.

## Market lifecycle

| `status`                 | Meaning                                                                                 | Orders                 |
| ------------------------ | --------------------------------------------------------------------------------------- | ---------------------- |
| `inactive`               | Listed, trading window not open yet                                                     | No orders              |
| `active`                 | Trading window open                                                                     | Create, modify, cancel |
| `waiting-for-settlement` | Window ended, outcome pending; existing GTT orders may still rest                       | Cancel only            |
| `in-settlement`          | Operator initiated settlement; remaining orders are cancelled before positions are paid | Cancel only            |
| `settled`                | Book drained and every position paid. `outcome` and `settlement_price` are final        | –                      |

The API reports the effective lifecycle status above. After settlement, a book stored internally as `inactive` is exposed as `settled`. Window expiry does not immediately cancel resting GTT orders: cancel them yourself to release reserved funds before settlement cleanup.

## Underlying price

The price the outcome is measured on is published per series as candles of the underlying Chainlink feed (this is **not** the binary options order book; [candles](https://docs.lighter.xyz/api/candlesticks) on a binary options market is empty).

Set `symbol` and `duration` from the selected event’s metadata. This example uses `eth` and `15m`; replace them and the timestamps with the series and time range you want to query.

```shell
curl "https://mainnet.zklighter.elliot.ai/api/v1/upDownCandles?symbol=eth&duration=15m&resolution=30s&start_timestamp=1792429350&end_timestamp=1792429950"
```

| Parameter                          | Notes                                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------- |
| `symbol`, `duration`               | Series underlying and window, e.g. `eth` + `15m`                              |
| `resolution`                       | `1s` (the raw price observations, default) or `30s`                           |
| `start_timestamp`, `end_timestamp` | Unix **seconds**, inclusive, at most 24h apart                                |
| `limit`                            | 1–3600, default 1000. Pass `next_cursor` as `start_timestamp` to page forward |

See [upDownCandles](https://docs.lighter.xyz/api/binary-options) for the full API reference. Candles arrive oldest first. Each candle contains `symbol`, `duration`, `resolution`, `timestamp`, `open`, `high`, `low`, `close`, `provider` and `feed_id`; prices are decimal strings. Subscribe to [up\_down\_candle](/developers/binary-options/websocket.md#up-down-candlesticks) for live updates.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.lighter.xyz/developers/binary-options/discover-markets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.