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

# Python SDK

> Official Python SDK for the SportsX trading API.

<Note>
  **Pre-release — 0.1.x.** Sync HTTP, async HTTP, and WebSocket clients with typed Pydantic v2 response models are available today. API-key auth is in progress.
</Note>

`stx-python` is the official Python SDK for the SportsX trading API. It wraps the GraphQL HTTP API and Phoenix WebSocket channels behind a small, ergonomic surface:

* `STX` — synchronous GraphQL client
* `AsyncSTX` — asyncio-native GraphQL client (same surface as `STX`)
* `STXWebSocket` — Phoenix channels client with reconnect, heartbeat, and resubscribe baked in

One package, three clients, one set of credentials.

```bash theme={null}
pip install stx-python
```

```python theme={null}
from stx import STX, Selection

client = STX(region="ontario", env="production",
             email="you@example.com", password="...")
markets = client.markets(selections=Selection("market_id", "status"))
```

## Where to go next

<CardGroup cols={2}>
  <Card title="Quickstart" icon="bolt" href="/sdks/python/quickstart">
    Install, authenticate, and make your first call in under five minutes.
  </Card>

  <Card title="Installation" icon="download" href="/sdks/python/installation">
    Supported Python versions, optional extras, and platform notes.
  </Card>

  <Card title="Authentication" icon="key" href="/sdks/python/authentication">
    Email/password login, 2FA, env vars, and profile files.
  </Card>

  <Card title="Configuration" icon="sliders" href="/sdks/python/configuration">
    Regions, environments, `~/.stx/credentials` profiles, and schema pinning.
  </Card>

  <Card title="Market data" icon="chart-line" href="/sdks/python/markets">
    Query markets, orderbooks, and event metadata.
  </Card>

  <Card title="Trading" icon="arrows-rotate" href="/sdks/python/trading">
    Place, cancel, and inspect orders; fetch positions and fills.
  </Card>

  <Card title="WebSockets" icon="tower-broadcast" href="/sdks/python/websockets">
    Subscribe to Phoenix channels for real-time order and market updates.
  </Card>

  <Card title="Async" icon="wand-magic-sparkles" href="/sdks/python/async">
    The same API as `STX`, awaitable — for bots and high-fanout services.
  </Card>

  <Card title="Errors & retries" icon="triangle-exclamation" href="/sdks/python/errors-and-retries">
    Exception hierarchy, the built-in retry policy, and how to override it.
  </Card>

  <Card title="API Reference" icon="book" href="/sdks/python/reference/market-data">
    Per-category pages with parameter tables and examples for every supported op.
  </Card>
</CardGroup>

## Design goals

<Tip>
  **The SDK should feel like writing Python, not like calling a GraphQL API.** You should be able to get useful results without knowing what a `Selection` or a DSL field is.
</Tip>

1. **Zero-config defaults.** `client.markets()` returns every scalar field by default — REST-like. Narrow the payload with `Selection(...)` only when you care.
2. **Typed responses out of the box.** Every response is a Pydantic v2 model — `.market_id`, `.status`, full IDE autocomplete, and `.model_dump()` if you need a dict.
3. **Typed operations too.** Method names (`client.markets`, `client.place_order`) and `params=` keys autocomplete in VS Code / Pyright / mypy. Typos fail type-check before you run your code.
4. **One set of credentials, three clients.** The `User` singleton caches the JWT, so `STX`, `AsyncSTX`, and `STXWebSocket` share auth in a single process.
5. **Auto-refreshed tokens.** JWTs expire after 60 minutes; the SDK refreshes at 59 so you don't see `STXTokenExpiredException` in steady-state code.
6. **Typed exceptions.** `STXAuthException`, `STXRateLimitException`, `STXValidationException`, and friends — not a single catch-all `APIError`.
7. **Schema pinned to your SDK version.** The GraphQL schema ships with the package; upgrade the SDK to pick up new fields. Opt into always-latest mode when you need bleeding-edge fields.

## Compatibility

|               | Supported                                                        |
| ------------- | ---------------------------------------------------------------- |
| Python        | 3.11, 3.12, 3.13 (3.9, 3.10 best-effort)                         |
| OS            | Linux, macOS, Windows                                            |
| Async runtime | `asyncio` (native); `trio`/`anyio` via compat layer (not tested) |

## Example gallery

Working end-to-end examples live in [`stxapp/stx-python-demo`](https://github.com/stxapp/stx-python-demo):

* `quickstart.py` — minimum viable first call
* `list_markets.py` — comparison of narrow `Selection` vs. default-all-fields payload sizes
* `place_order.py` — order placement with dry-run mode
* `websocket_feed.py` — subscribe to live market updates over Phoenix

## Support

* **Bug reports / feature requests:** [github.com/stxapp/stx-python/issues](https://github.com/stxapp/stx-python/issues)
* **Questions:** post in the #developers channel on the SportsX Discord