Discover markets

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:

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 (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
`taker_fee`, `maker_fee`	Maximum fee rates in percent, e.g. `"1.0000"` = 1% (see Fees)
`size_decimals`, `price_decimals`, `min_base_amount`, `min_quote_amount`	Integer scaling and order minimums (see 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.

{
  "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) 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 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.

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 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 for live updates.