SDKs

Python SDK

The ITMatrixHQ SDK for Python 3.10+ — a blocking client, an async client, typed models, protobuf on request and async streams.

Source on GitHub · Python on PyPI · TypeScript on npm.

Install

pip install itmatrix
# WebSocket streams:
pip install "itmatrix[stream]"

The distribution and import name are both itmatrix. Python 3.10 or newer.

Quickstart

python

import os
import itmatrix as itm

with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
    result = client.get_gex("SPY", top=10)
    print(result.data.spot, result.data.net_gex)
    for row in result.data.strikes:
        print(row.strike, row.gex, row.expiry)

row.strike is a convenient dollar value; row.strike_thousandths keeps the exact integer.

The main methods

Method	`result.data`
`get_gex(symbol, at=..., top=..., by_expiry=...)`	`GexGrid` with `GexStrike` rows
`get_gex_history(symbol, date=..., from_=..., to=..., top=...)`	Every capture of one session
`get_gex_reference(symbol, date=..., basis="open")`	The exact persisted reference book, or explicit unavailable values
`get_option_chain(symbol, expiry=..., strike_gte=...)`	`OptionChain` with contract and quote models
`list_expirations(symbol)`	ISO expiry dates
`list_symbols(symbol_class="equity")`	`Symbol` values from the registry
`lookup_symbol("spy")`	`SymbolIdentity`
`get_bars(symbol, from_=..., to=..., timeframe="1m")`	`Bars` with `bars`, `cursor` and completeness
`get_gex_analysis(symbol)`	Server net GEX and zero gamma plus ranked visible levels
`get_bars_for_period(symbol, "today")`	New York calendar-day bars; longer periods default to daily bars

get_gex_analysis and get_bars_for_period are local compositions over the reads above; they add no API route. Levels are ranked among the rows returned — a top limit can hide stronger strikes — so do not call them full-chain walls.

Grouped resources cover the rest: client.flow, client.offexchange, client.vol, client.market, client.reference, client.screener, client.economy, client.fundamentals, client.journal, client.watchlists, client.account, client.protocols and client.info.

python

with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
    large = client.flow.large_trades(symbol="SPY", limit=25)
    eod = client.flow.eod(session="2026-09-25", symbol="SPY")
    rates = client.economy.treasury_yields()
    ref = client.get_gex_reference("SPY", date="2026-09-25", basis="prev_close")

Async

python

import asyncio
import os
import itmatrix as itm

async def main():
    async with itm.AsyncITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
        spy, qqq = await asyncio.gather(client.get_gex("SPY"), client.get_gex("QQQ"))
        print(spy.data.net_gex, qqq.data.net_gex)

asyncio.run(main())

The blocking ITMClient owns one background event loop and HTTP pool and serializes its calls; use AsyncITMClient for concurrent work. Close either with with / async with or close().

Protobuf

python

client = itm.ITMClient(api_key=os.environ["ITM_API_KEY"], transport="protobuf")

The bulk market-data and off-exchange reads then negotiate protobuf and return the same models. See Protobuf.

Streams

Streams live on AsyncITMClient.stream and need the stream extra. Subscriptions are bounded async iterators of public protobuf frames:

python

async with itm.AsyncITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
    async with client.stream.spot("SPY") as prices:
        async for frame in prices:
            print(frame.spot.price_scaled / 10_000)

Falling behind the queue limit raises an error rather than dropping updates. See Streaming.

Errors, retries and configuration

python

try:
    with itm.ITMClient(api_key=os.environ["ITM_API_KEY"], timeout=15, retries=2) as client:
        grid = client.get_gex("SPY")
except itm.ITMError as error:
    print(error.code, error.status, error.request_id)

timeout is per operation, not an end-to-end deadline including retries.
Only GET on 429/502/503/504 is retried, each wait capped at 30 seconds.
Redirects are disabled; credentials are never sent to arbitrary absolute URLs.
base_url defaults to https://api.itmatrixhq.com. No credential is read from the environment implicitly — pass api_key (a string or a refresh callback).