# Markets

> Markets and events: filters, sorting, pagination, and the market object.

Source: https://docs.stxapp.io/sdks/python/markets/

What a market is and how it moves through its statuses is covered in [Concepts](/concepts/); every field is in the [API reference](/api/rest/). This page shows the SDK calls.

## Listing markets

`markets()` calls `GET /api/v1/markets` and returns one `Page` of `stx.models.Market`:

```python
from stx import STX

with STX() as client:
    page = client.markets(status=["pre_open", "open"], trading=True, limit=10)
    for m in page:
        print(m.market_id, m.status, m.symbol, m.last_traded_price)
    print(len(page), "markets; more:", page.has_more)
```

| Argument | Meaning |
|---|---|
| `market_ids`, `event_ids` | One id or a list |
| `status` | One status or a list: `scheduled`, `pre_open`, `open`, `closed`, `resulted`, `cancelled`, `voided` |
| `trading` | `True` for markets accepting orders now |
| `sports`, `competitions` | Exact names as the market carries them, e.g. `"Baseball"`, `"MLB"` |
| `sort_by`, `sort_direction` | `"event_start"`, and `"asc"` or `"desc"` |
| `limit` | Page size, default 100, maximum 200 |
| `cursor` | The `cursor` of the previous page |

Filters combine with AND; a list matches any of its values.

## Pagination

Every list endpoint pages by cursor. `page.cursor` is `None` on the last page. Pass it back for the next one, or let an `iter_` method follow it for you:

```python
from itertools import islice

from stx import STX

with STX() as client:
    first = client.markets(status="open", limit=2)
    if first.cursor:
        second = client.markets(status="open", limit=2, cursor=first.cursor)
        print([m.symbol for m in second])

    walked = list(islice(client.iter_markets(status="open", limit=50), 120))
    print("walked", len(walked), "markets across pages")
```

`iter_markets`, `iter_events`, `iter_orders`, `iter_fills`, `iter_settlements`, `iter_deposits`, `iter_withdrawals`, `iter_adjustments`, `iter_fees`, `iter_loyalty` and `iter_account_market_stats` all work the same way. On `AsyncSTX` they are async iterators (`async for`).

## One market

There is no single-market route; `market(market_id)` asks `markets()` for that id and raises `STXNotFoundException` when there is none:

```python
from stx import STX

with STX() as client:
    some_id = client.markets(limit=1)[0].market_id
    market = client.market(some_id)
    print(market.title)
    print("rules", market.rules, "max", market.max_price, "delay", market.in_play_delay_sec)
```

## The market object

Selected fields of `stx.models.Market`; every field is on the [API reference](/api/rest/).

| Field | Type | Notes |
|---|---|---|
| `market_id`, `event_id` | `str` | UUIDs |
| `symbol`, `title`, `short_title`, `question` | `str` | |
| `status` | `str` | See [market status](/concepts/market-status/) |
| `trading` | `bool` | Accepting orders now |
| `max_price` | `str` | What a winning contract pays, e.g. `"1.0000"`. Read it per market; orders price strictly below it |
| `price`, `last_traded_price` | `str` or `None` | Dollars |
| `bids`, `offers` | `List[BookLevel]` | Best first; each level has `price` and `quantity` strings |
| `recent_trades` | `List[RecentTrade]` | `price`, `quantity`, `timestamp`, `liquidity_taker` |
| `volume24h`, `total_volume`, `open_interest` | `str` or `None` | Contracts |
| `event_start` | `str` | ISO 8601 |
| `in_play_delay_sec` | `int` | Queue delay while the event is in progress |

Fields the server adds before the SDK knows them are kept: read them as attributes or from `model_dump()`.

## Events

```python
from stx import STX

with STX() as client:
    for event in client.events(status="scheduled", sort_by="start_time", limit=5):
        print(event.start_time_iso, event.sport, event.title)
```

`events()` takes `event_ids`, `sports`, `competitions`, `event_types`, `title`, `status` (`scheduled`, `in_progress`, `completed`, `cancelled`), `promoted`, `sort_by="start_time"`, `sort_direction`, `limit` and `cursor`.

## Live prices

`markets()` returns the book as it stood when you asked. To follow a book, subscribe to the `orderbook` channel; for price changes across many markets, `ticker`. See [WebSockets](/sdks/python/websockets/).