itmatrix 1.0.0__tar.gz

itmatrix-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+node_modules/
+dist/
+.venv/
+__pycache__/
+*.pyc
+*.egg-info/
+.idea/
+.vscode/
+.DS_Store
+
+target/
+.pytest_cache/
+.ruff_cache/
+.wheel-smoke/
+*.tgz

itmatrix-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ITMatrixHQ contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

itmatrix-1.0.0/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.5
+Name: itmatrix
+Version: 1.0.0
+Summary: Human-friendly sync and async clients for the ITMatrixHQ API
+Project-URL: Homepage, https://itmatrixhq.com
+Project-URL: Source, https://github.com/ITMatrixHQ/itmatrix-sdks
+Project-URL: Issues, https://github.com/ITMatrixHQ/itmatrix-sdks/issues
+Project-URL: Changelog, https://github.com/ITMatrixHQ/itmatrix-sdks/blob/master/CHANGELOG.md
+Author: ITMatrixHQ
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api client,gamma exposure,gex,itmatrix,itmatrixhq,market data,options
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio<5,>=4
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: protobuf<8,>=7.35.1
+Requires-Dist: typing-extensions>=4.7
+Requires-Dist: tzdata>=2024.1
+Provides-Extra: stream
+Requires-Dist: websockets<16,>=14; extra == 'stream'
+Description-Content-Type: text/markdown
+
+# ITMatrixHQ Python SDK
+
+```sh
+pip install itmatrix
+# For WebSocket streams:
+pip install "itmatrix[stream]"
+```
+
+```python
+import os
+import itmatrix as itm
+
+client = itm.ITMClient(api_key=os.environ["ITM_API_KEY"])
+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)
+```
+
+No `with` block is needed. The same client works as a context manager, which
+closes it when the block ends:
+
+```python
+with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
+    print(client.get_gex("SPY").data.net_gex)
+```
+
+`itmatrix` is the distribution and import name. Python 3.10+ is supported. To build
+from source instead, run `pip install ./python` from the repository root.
+
+## A small vocabulary
+
+| Method | `result.data` |
+| --- | --- |
+| `get_gex(symbol, at=..., top=..., by_expiry=...)` | `GexGrid` and `GexStrike` values |
+| `get_gex_reference(symbol, date=..., basis="open")` | Exact persisted reference book, or explicit unavailable values |
+| `get_option_chain(symbol, expiry=..., strike_gte=...)` | `OptionChain` with contract/quote models |
+| `list_expirations(symbol)` | ISO expiry date strings |
+| `list_symbols(symbol_class="equity")` | `Symbol` values from the registry |
+| `lookup_symbol("spy")` | `SymbolIdentity` with broad class and conservative instrument classification |
+| `get_bars(symbol, from_=..., to=..., timeframe="1m")` | `Bars` with `bars`, `cursor`, and completeness |
+| `get_replay(symbol, date="2026-09-04")` | `Replay` with `Tick` or `Bar` events |
+| `get_gex_analysis(symbol)` | Server net GEX and zero gamma plus ranked **visible** positive/negative strike levels |
+| `get_bars_for_period(symbol, "today")` | New York calendar-day intraday bars; longer named periods default to daily bars |
+
+The convenience methods are local compositions; they add no API route.
+`get_bars_for_period(symbol, "calendar_month", month="2024-02")` requests the
+whole named month with daily bars; inspect the returned cursor for another page.
+`resolve_bar_window` can be used without a
+client. See [convenience semantics](../docs/convenience.md) before treating
+visible GEX levels as full-chain levels or a month as a completed session set.
+
+`Result` retains `meta`, HTTP `status`, `request_id`, and `etag`. Unknown metadata
+is preserved. Nullable measurements stay `None`; zero is a real value. Timestamps
+are epoch milliseconds, dates are ISO strings, bar/quote prices are dollars, and
+strike filters use integer thousandths of dollars. `row.strike` is a convenient
+dollar value; `row.strike_thousandths` preserves the exact integer. GEX values
+(`gex`, `net_gex`, `max_abs_gex`, `delta_adj`, `gex_0dte`) are dollars of dealer
+hedging per $1 move. Each has a served `*_shares` sibling (`gex_shares`,
+`net_gex_shares`, `max_abs_gex_shares`, `delta_adj_shares`, `gex_0dte_shares`) in
+shares of the underlying per $1 move, on the grid, history and reference book;
+`None` means the server does not know it.
+
+The public protobuf representation omits an option contract's OSI root. Its
+`underlying` is therefore `None` on that transport, rather than a guessed value.
+The normalized model otherwise uses the same field names and units for JSON and
+public protobuf. Set `transport="protobuf"` to negotiate public protobuf on the
+bulk market-data and off-exchange endpoints. Streaming always uses the public protobuf protocol.
+
+Account, journal, watchlists, economy, offexchange, market, reference, screener, flow,
+fundamentals, vol, protocol and service-info operations are grouped on both
+clients. Together with the client's own methods they model **every non-internal
+`/v2` operation the contract declares**; the pre-`/v2` aliases are deliberately
+not modelled.
+
+`client.offexchange` is the typed synthetic surface: `activity`, `concentration`,
+`profile`, and `composition`. `client.darkpool` is a compatibility alias to the
+same safe resource. There is no generic dataset method or raw-evidence route.
+
+```python
+with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
+    rates = client.economy.treasury_yields()
+    trades = client.journal.list_trades()
+    news = client.fundamentals.digest(kind="brief", scope="market")
+
+    # A whole session's GEX captures. `to` is exclusive, so 16:00 drops the close.
+    day = client.get_gex_history("SPY", date="2026-09-04", from_="09:25", to="16:05", top=120)
+
+    # Exact immutable book; captured_at=None means unavailable, not zero.
+    reference = client.get_gex_reference("SPY", date="2026-09-25", basis="prev_close")
+
+    # First-party app session only: Pro + CBOE attestation, explicitly partial.
+    premium = client.flow.premium("SPY", sessions=2, dte="zero", min_premium_usd=100_000)
+
+    # Our own implied vol, out of the greeks engine.
+    term = client.vol.term("SPY")
+
+    # Is the API up, and what does this deployment serve? No credential needed.
+    ready = client.info.ready()
+    spec = client.info.openapi()
+```
+
+`info.health()` and `info.ready()` are the only calls that leave `/v2/`: the
+client keeps a two-entry allowlist for them and rejects every other path, so
+`request()` cannot wander off the documented surface. `ready()` is the deploy
+contract rather than a synonym for `health()` — it is non-2xx while the process
+is still warming up.
+
+Grouped resources and `request("/v2/...")` expose raw JSON data for less common
+operations. Endpoint availability still depends on server entitlements; installing
+an SDK does not grant app-only products such as bars or chain data.
+
+## Async and streaming
+
+```python
+import asyncio
+
+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())
+```
+
+Subscriptions live on `AsyncITMClient.stream`; they are bounded async iterators of
+public protobuf frames. See the repository streaming documentation and the
+`stream.gex(symbol)` / `stream.spot(symbol)` helpers. Close subscriptions with
+`async with` or `aclose()`, and close the client with `async with` or `aclose()`. Falling behind the configured
+queue limit raises an error rather than silently discarding market updates.
+
+## Client lifecycle
+
+The blocking `ITMClient` owns one persistent background event loop and HTTP pool;
+it never reuses async connections across short-lived loops. Create it once and
+reuse it. `close()` is optional:
+
+- Call `close()` (or use `with`) when you want the loop thread and connections
+  released at a known point, such as a long-running process that makes a client
+  per task. It is safe to call more than once; a request after it raises
+  `RuntimeError`, and `client.closed` reports it.
+- A client you never close is closed when it is garbage-collected or when the
+  interpreter exits. Its loop runs on a daemon thread, so it never keeps a script
+  from exiting.
+
+Blocking requests are serialized. Use `AsyncITMClient` for concurrent work; an async
+client belongs to the loop where it is used. Without `async with`, call
+`await client.aclose()` when you are done: async cleanup cannot run from a
+finalizer, so an async client that owns its pool and is collected unclosed only
+emits `ResourceWarning`. Injected async HTTP clients remain owned by the caller.
+
+## Errors, retries, and configuration
+
+```python
+client = itm.ITMClient(api_key=os.environ["ITM_API_KEY"], timeout=15, retries=2)
+try:
+    grid = client.get_gex("SPY")
+except itm.ITMError as error:
+    print(error.code, error.status, error.request_id)
+```
+
+Only GET responses with status 429, 502, 503, or 504 are retried; mutations and
+transport exceptions are not replayed. Retry waits are bounded at 30 seconds,
+with exponential fallback. `timeout` is HTTPX's per-operation timeout, not an
+end-to-end deadline including retries. HTTPX transport exceptions propagate.
+Redirects are disabled even for injected clients. The `request` escape hatch
+accepts only `/v2/` paths; query parameters go in `query={...}`. Credentials are
+resolved for each attempt and never attached to arbitrary absolute URLs.
+
+`base_url` must be an HTTP(S) origin and defaults to `itm.DEFAULT_BASE_URL`, the
+one place the package defines it. `api_key` and `token` are mutually exclusive;
+each accepts a string or refresh callback (sync or async). No credentials are
+inferred from environment variables. Tests can inject `http_transport`.
+
+## Studies and indicators
+
+There is no native evaluator in Python. The ITMScript runtime is TypeScript, unpublished,
+and has no Python port planned; this package hands you normalized bars and stops there.
+A study over `get_bars(...).data` is either computed in your own code or run through the
+TypeScript runtime out of process. The rules a host has to resolve either way — a 304 is
+revalidation and not an empty history, pagination is the caller's loop, entitlement
+belongs to the credential — are in [docs/itmscript.md](https://github.com/ITMatrixHQ/itmatrix-sdks/blob/master/docs/itmscript.md).
+
+## Contributing
+
+From `python/`, install with `pip install -e .`, run
+`python -m unittest discover -s tests`, and build with `python -m build`.
+The repository contract-coverage test also requires the sibling `spec/` directory.
+Only the protobuf serializers in `itmatrix/_core/_wire` are generated. Public clients,
+models, options, resources, and tests are hand maintained. Wheels and source
+archives contain the single `itmatrix` import package and its `py.typed` marker.

itmatrix-1.0.0/README.md

@@ -0,0 +1,192 @@
+# ITMatrixHQ Python SDK
+
+```sh
+pip install itmatrix
+# For WebSocket streams:
+pip install "itmatrix[stream]"
+```
+
+```python
+import os
+import itmatrix as itm
+
+client = itm.ITMClient(api_key=os.environ["ITM_API_KEY"])
+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)
+```
+
+No `with` block is needed. The same client works as a context manager, which
+closes it when the block ends:
+
+```python
+with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
+    print(client.get_gex("SPY").data.net_gex)
+```
+
+`itmatrix` is the distribution and import name. Python 3.10+ is supported. To build
+from source instead, run `pip install ./python` from the repository root.
+
+## A small vocabulary
+
+| Method | `result.data` |
+| --- | --- |
+| `get_gex(symbol, at=..., top=..., by_expiry=...)` | `GexGrid` and `GexStrike` values |
+| `get_gex_reference(symbol, date=..., basis="open")` | Exact persisted reference book, or explicit unavailable values |
+| `get_option_chain(symbol, expiry=..., strike_gte=...)` | `OptionChain` with contract/quote models |
+| `list_expirations(symbol)` | ISO expiry date strings |
+| `list_symbols(symbol_class="equity")` | `Symbol` values from the registry |
+| `lookup_symbol("spy")` | `SymbolIdentity` with broad class and conservative instrument classification |
+| `get_bars(symbol, from_=..., to=..., timeframe="1m")` | `Bars` with `bars`, `cursor`, and completeness |
+| `get_replay(symbol, date="2026-09-04")` | `Replay` with `Tick` or `Bar` events |
+| `get_gex_analysis(symbol)` | Server net GEX and zero gamma plus ranked **visible** positive/negative strike levels |
+| `get_bars_for_period(symbol, "today")` | New York calendar-day intraday bars; longer named periods default to daily bars |
+
+The convenience methods are local compositions; they add no API route.
+`get_bars_for_period(symbol, "calendar_month", month="2024-02")` requests the
+whole named month with daily bars; inspect the returned cursor for another page.
+`resolve_bar_window` can be used without a
+client. See [convenience semantics](../docs/convenience.md) before treating
+visible GEX levels as full-chain levels or a month as a completed session set.
+
+`Result` retains `meta`, HTTP `status`, `request_id`, and `etag`. Unknown metadata
+is preserved. Nullable measurements stay `None`; zero is a real value. Timestamps
+are epoch milliseconds, dates are ISO strings, bar/quote prices are dollars, and
+strike filters use integer thousandths of dollars. `row.strike` is a convenient
+dollar value; `row.strike_thousandths` preserves the exact integer. GEX values
+(`gex`, `net_gex`, `max_abs_gex`, `delta_adj`, `gex_0dte`) are dollars of dealer
+hedging per $1 move. Each has a served `*_shares` sibling (`gex_shares`,
+`net_gex_shares`, `max_abs_gex_shares`, `delta_adj_shares`, `gex_0dte_shares`) in
+shares of the underlying per $1 move, on the grid, history and reference book;
+`None` means the server does not know it.
+
+The public protobuf representation omits an option contract's OSI root. Its
+`underlying` is therefore `None` on that transport, rather than a guessed value.
+The normalized model otherwise uses the same field names and units for JSON and
+public protobuf. Set `transport="protobuf"` to negotiate public protobuf on the
+bulk market-data and off-exchange endpoints. Streaming always uses the public protobuf protocol.
+
+Account, journal, watchlists, economy, offexchange, market, reference, screener, flow,
+fundamentals, vol, protocol and service-info operations are grouped on both
+clients. Together with the client's own methods they model **every non-internal
+`/v2` operation the contract declares**; the pre-`/v2` aliases are deliberately
+not modelled.
+
+`client.offexchange` is the typed synthetic surface: `activity`, `concentration`,
+`profile`, and `composition`. `client.darkpool` is a compatibility alias to the
+same safe resource. There is no generic dataset method or raw-evidence route.
+
+```python
+with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
+    rates = client.economy.treasury_yields()
+    trades = client.journal.list_trades()
+    news = client.fundamentals.digest(kind="brief", scope="market")
+
+    # A whole session's GEX captures. `to` is exclusive, so 16:00 drops the close.
+    day = client.get_gex_history("SPY", date="2026-09-04", from_="09:25", to="16:05", top=120)
+
+    # Exact immutable book; captured_at=None means unavailable, not zero.
+    reference = client.get_gex_reference("SPY", date="2026-09-25", basis="prev_close")
+
+    # First-party app session only: Pro + CBOE attestation, explicitly partial.
+    premium = client.flow.premium("SPY", sessions=2, dte="zero", min_premium_usd=100_000)
+
+    # Our own implied vol, out of the greeks engine.
+    term = client.vol.term("SPY")
+
+    # Is the API up, and what does this deployment serve? No credential needed.
+    ready = client.info.ready()
+    spec = client.info.openapi()
+```
+
+`info.health()` and `info.ready()` are the only calls that leave `/v2/`: the
+client keeps a two-entry allowlist for them and rejects every other path, so
+`request()` cannot wander off the documented surface. `ready()` is the deploy
+contract rather than a synonym for `health()` — it is non-2xx while the process
+is still warming up.
+
+Grouped resources and `request("/v2/...")` expose raw JSON data for less common
+operations. Endpoint availability still depends on server entitlements; installing
+an SDK does not grant app-only products such as bars or chain data.
+
+## Async and streaming
+
+```python
+import asyncio
+
+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())
+```
+
+Subscriptions live on `AsyncITMClient.stream`; they are bounded async iterators of
+public protobuf frames. See the repository streaming documentation and the
+`stream.gex(symbol)` / `stream.spot(symbol)` helpers. Close subscriptions with
+`async with` or `aclose()`, and close the client with `async with` or `aclose()`. Falling behind the configured
+queue limit raises an error rather than silently discarding market updates.
+
+## Client lifecycle
+
+The blocking `ITMClient` owns one persistent background event loop and HTTP pool;
+it never reuses async connections across short-lived loops. Create it once and
+reuse it. `close()` is optional:
+
+- Call `close()` (or use `with`) when you want the loop thread and connections
+  released at a known point, such as a long-running process that makes a client
+  per task. It is safe to call more than once; a request after it raises
+  `RuntimeError`, and `client.closed` reports it.
+- A client you never close is closed when it is garbage-collected or when the
+  interpreter exits. Its loop runs on a daemon thread, so it never keeps a script
+  from exiting.
+
+Blocking requests are serialized. Use `AsyncITMClient` for concurrent work; an async
+client belongs to the loop where it is used. Without `async with`, call
+`await client.aclose()` when you are done: async cleanup cannot run from a
+finalizer, so an async client that owns its pool and is collected unclosed only
+emits `ResourceWarning`. Injected async HTTP clients remain owned by the caller.
+
+## Errors, retries, and configuration
+
+```python
+client = itm.ITMClient(api_key=os.environ["ITM_API_KEY"], timeout=15, retries=2)
+try:
+    grid = client.get_gex("SPY")
+except itm.ITMError as error:
+    print(error.code, error.status, error.request_id)
+```
+
+Only GET responses with status 429, 502, 503, or 504 are retried; mutations and
+transport exceptions are not replayed. Retry waits are bounded at 30 seconds,
+with exponential fallback. `timeout` is HTTPX's per-operation timeout, not an
+end-to-end deadline including retries. HTTPX transport exceptions propagate.
+Redirects are disabled even for injected clients. The `request` escape hatch
+accepts only `/v2/` paths; query parameters go in `query={...}`. Credentials are
+resolved for each attempt and never attached to arbitrary absolute URLs.
+
+`base_url` must be an HTTP(S) origin and defaults to `itm.DEFAULT_BASE_URL`, the
+one place the package defines it. `api_key` and `token` are mutually exclusive;
+each accepts a string or refresh callback (sync or async). No credentials are
+inferred from environment variables. Tests can inject `http_transport`.
+
+## Studies and indicators
+
+There is no native evaluator in Python. The ITMScript runtime is TypeScript, unpublished,
+and has no Python port planned; this package hands you normalized bars and stops there.
+A study over `get_bars(...).data` is either computed in your own code or run through the
+TypeScript runtime out of process. The rules a host has to resolve either way — a 304 is
+revalidation and not an empty history, pagination is the caller's loop, entitlement
+belongs to the credential — are in [docs/itmscript.md](https://github.com/ITMatrixHQ/itmatrix-sdks/blob/master/docs/itmscript.md).
+
+## Contributing
+
+From `python/`, install with `pip install -e .`, run
+`python -m unittest discover -s tests`, and build with `python -m build`.
+The repository contract-coverage test also requires the sibling `spec/` directory.
+Only the protobuf serializers in `itmatrix/_core/_wire` are generated. Public clients,
+models, options, resources, and tests are hand maintained. Wheels and source
+archives contain the single `itmatrix` import package and its `py.typed` marker.

itmatrix-1.0.0/pyproject.toml

@@ -0,0 +1,62 @@
+[project]
+name = "itmatrix"
+version = "1.0.0"
+description = "Human-friendly sync and async clients for the ITMatrixHQ API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "ITMatrixHQ" }]
+keywords = ["itmatrixhq", "itmatrix", "options", "gamma exposure", "gex", "market data", "api client"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Office/Business :: Financial :: Investment",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "anyio>=4,<5",
+  "protobuf>=7.35.1,<8",
+  "typing-extensions>=4.7",
+  "tzdata>=2024.1",
+]
+
+[project.optional-dependencies]
+stream = ["websockets>=14,<16"]
+
+[project.urls]
+Homepage = "https://itmatrixhq.com"
+Source = "https://github.com/ITMatrixHQ/itmatrix-sdks"
+Issues = "https://github.com/ITMatrixHQ/itmatrix-sdks/issues"
+Changelog = "https://github.com/ITMatrixHQ/itmatrix-sdks/blob/master/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/itmatrix"]
+
+[tool.hatch.build]
+include = [
+  "src/itmatrix/**/*.py",
+  "src/itmatrix/py.typed",
+  "README.md",
+  "LICENSE",
+  "pyproject.toml",
+  "tests/**/*.py",
+]
+
+[tool.ruff.lint]
+ignore = ["E501"]

itmatrix-1.0.0/src/itmatrix/__init__.py

@@ -0,0 +1,53 @@
+"""The ITMatrixHQ API, for people and agents."""
+
+from ._core.config import DEFAULT_BASE_URL
+from ._core.errors import ITMError
+from ._core.models import Transport
+from ._core.stream import Stream, Subscription
+from .analytics import GexAnalysis, GexLevel, analyze_gex
+from .client import AsyncClient, AsyncITMClient, Client, ITMClient
+from .models import (
+    Bar,
+    Bars,
+    GexGrid,
+    GexStrike,
+    OptionChain,
+    OptionContract,
+    OptionQuote,
+    Replay,
+    Result,
+    Symbol,
+    SymbolIdentity,
+    Tick,
+)
+from .periods import BarPeriod, BarWindow, resolve_bar_window
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AsyncClient",
+    "AsyncITMClient",
+    "Bar",
+    "BarPeriod",
+    "BarWindow",
+    "Bars",
+    "Client",
+    "GexAnalysis",
+    "GexGrid",
+    "GexLevel",
+    "GexStrike",
+    "ITMClient",
+    "ITMError",
+    "OptionChain",
+    "OptionContract",
+    "OptionQuote",
+    "Replay",
+    "Result",
+    "Stream",
+    "Subscription",
+    "Symbol",
+    "SymbolIdentity",
+    "Tick",
+    "Transport",
+    "analyze_gex",
+    "resolve_bar_window",
+]

itmatrix-1.0.0/src/itmatrix/_core/__init__.py

@@ -0,0 +1,9 @@
+"""Thin client for the ITMatrixHQ /v2 API."""
+
+from .client import ITMClient
+from .config import DEFAULT_BASE_URL
+from .errors import ITMError
+from .models import Result, Transport
+from .stream import Stream, Subscription
+
+__all__ = ["DEFAULT_BASE_URL", "ITMClient", "ITMError", "Result", "Stream", "Subscription", "Transport"]

itmatrix-1.0.0/src/itmatrix/_core/_wire/__init__.py

@@ -0,0 +1 @@
+"""Generated public protobuf bindings. Prefer the high-level client."""

itmatrix-1.0.0/src/itmatrix/_core/_wire/rest_pb2.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: itmatrixhq/rest/v1/wire.proto
+# Protobuf Python Version: 7.35.1
+"""Generated protocol buffer code."""
+
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC, 7, 35, 1, "", "itmatrixhq/rest/v1/wire.proto"
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
+    b'\n\x1ditmatrixhq/rest/v1/wire.proto\x12\x12itmatrixhq.rest.v1"\xcc\x01\n\x0c\x42\x61rsResponse\x12\x13\n\x0bprice_scale\x18\x01 \x01(\r\x12 \n\x13\x63omplete_through_ms\x18\x02 \x01(\x04H\x00\x88\x01\x01\x12\x1f\n\x12prior_close_scaled\x18\x03 \x01(\x11H\x01\x88\x01\x01\x12%\n\x04\x62\x61rs\x18\x04 \x03(\x0b\x32\x17.itmatrixhq.rest.v1.Bar\x12\x0e\n\x06\x63ursor\x18\x05 \x01(\tB\x16\n\x14_complete_through_msB\x15\n\x13_prior_close_scaled"\x88\x01\n\x03\x42\x61r\x12\r\n\x05ts_ms\x18\x01 \x01(\x04\x12\t\n\x01o\x18\x02 \x01(\x11\x12\t\n\x01h\x18\x03 \x01(\x11\x12\t\n\x01l\x18\x04 \x01(\x11\x12\t\n\x01\x63\x18\x05 \x01(\x11\x12\x0e\n\x01v\x18\x06 \x01(\rH\x00\x88\x01\x01\x12\x11\n\x04vwap\x18\x07 \x01(\x11H\x01\x88\x01\x01\x12\x0e\n\x01n\x18\x08 \x01(\rH\x02\x88\x01\x01\x42\x04\n\x02_vB\x07\n\x05_vwapB\x04\n\x02_n"\xaa\x01\n\x0eReplayResponse\x12\x13\n\x0bprice_scale\x18\x01 \x01(\r\x12\x10\n\x08\x66idelity\x18\x02 \x01(\r\x12\x10\n\x08\x63omplete\x18\x03 \x01(\x08\x12\x0f\n\x07sources\x18\x04 \x03(\t\x12\'\n\x05ticks\x18\x05 \x03(\x0b\x32\x18.itmatrixhq.rest.v1.Tick\x12%\n\x04\x62\x61rs\x18\x06 \x03(\x0b\x32\x17.itmatrixhq.rest.v1.Bar"K\n\x04Tick\x12\r\n\x05ts_ms\x18\x01 \x01(\x04\x12\x14\n\x0cprice_scaled\x18\x02 \x01(\x11\x12\x11\n\tsource_id\x18\x03 \x01(\r\x12\x0b\n\x03seq\x18\x04 \x01(\x04"\x84\x03\n\x0fGexGridResponse\x12\x1b\n\x0e\x63\x61ptured_at_ms\x18\x01 \x01(\x04H\x00\x88\x01\x01\x12\x11\n\x04spot\x18\x02 \x01(\x01H\x01\x88\x01\x01\x12\x1d\n\x10prior_close_spot\x18\x03 \x01(\x01H\x02\x88\x01\x01\x12\x0f\n\x07net_gex\x18\x04 \x01(\x01\x12\x1b\n\x0enet_gex_shares\x18\t \x01(\x01H\x03\x88\x01\x01\x12\x17\n\nflip_point\x18\x05 \x01(\x01H\x04\x88\x01\x01\x12\x13\n\x0bmax_abs_gex\x18\x06 \x01(\x01\x12\x1f\n\x12max_abs_gex_shares\x18\n \x01(\x01H\x05\x88\x01\x01\x12\r\n\x05\x61\x64hoc\x18\x07 \x01(\x08\x12,\n\x04rows\x18\x08 \x03(\x0b\x32\x1e.itmatrixhq.rest.v1.GexGridRowB\x11\n\x0f_captured_at_msB\x07\n\x05_spotB\x13\n\x11_prior_close_spotB\x11\n\x0f_net_gex_sharesB\r\n\x0b_flip_pointB\x15\n\x13_max_abs_gex_shares"\x83\x03\n\nGexGridRow\x12\x1a\n\x12strike_thousandths\x18\x01 \x01(\x03\x12\x0b\n\x03gex\x18\x02 \x01(\x01\x12\x17\n\ngex_shares\x18\x08 \x01(\x01H\x00\x88\x01\x01\x12\x15\n\x08gex_0dte\x18\x03 \x01(\x01H\x01\x88\x01\x01\x12\x1c\n\x0fgex_0dte_shares\x18\t \x01(\x01H\x02\x88\x01\x01\x12\x14\n\x07\x63\x61ll_oi\x18\x04 \x01(\x05H\x03\x88\x01\x01\x12\x13\n\x06put_oi\x18\x05 \x01(\x05H\x04\x88\x01\x01\x12\x16\n\tdelta_adj\x18\x06 \x01(\x01H\x05\x88\x01\x01\x12\x1d\n\x10\x64\x65lta_adj_shares\x18\n \x01(\x01H\x06\x88\x01\x01\x12\x1d\n\x10\x65xpiry_epoch_day\x18\x07 \x01(\x05H\x07\x88\x01\x01\x42\r\n\x0b_gex_sharesB\x0b\n\t_gex_0dteB\x12\n\x10_gex_0dte_sharesB\n\n\x08_call_oiB\t\n\x07_put_oiB\x0c\n\n_delta_adjB\x13\n\x11_delta_adj_sharesB\x13\n\x11_expiry_epoch_day"\x98\x01\n\rChainResponse\x12\x1b\n\x0e\x63\x61ptured_at_ms\x18\x01 \x01(\x04H\x00\x88\x01\x01\x12\x11\n\x04spot\x18\x02 \x01(\x01H\x01\x88\x01\x01\x12\x0f\n\x07partial\x18\x03 \x01(\x08\x12*\n\x04rows\x18\x04 \x03(\x0b\x32\x1c.itmatrixhq.rest.v1.ChainRowB\x11\n\x0f_captured_at_msB\x07\n\x05_spot"\x9c\x03\n\x08\x43hainRow\x12\x18\n\x10\x65xpiry_epoch_day\x18\x01 \x01(\x05\x12\r\n\x05right\x18\x02 \x01(\r\x12\x1a\n\x12strike_thousandths\x18\x03 \x01(\x03\x12\x0f\n\x02oi\x18\x04 \x01(\x03H\x00\x88\x01\x01\x12\x13\n\x06volume\x18\x05 \x01(\x03H\x01\x88\x01\x01\x12\x10\n\x03\x62id\x18\x06 \x01(\x01H\x02\x88\x01\x01\x12\x10\n\x03\x61sk\x18\x07 \x01(\x01H\x03\x88\x01\x01\x12\x11\n\x04last\x18\x08 \x01(\x01H\x04\x88\x01\x01\x12\x10\n\x03\x66mv\x18\t \x01(\x01H\x05\x88\x01\x01\x12\x0f\n\x02iv\x18\n \x01(\x01H\x06\x88\x01\x01\x12\x12\n\x05\x64\x65lta\x18\x0b \x01(\x01H\x07\x88\x01\x01\x12\x12\n\x05gamma\x18\x0c \x01(\x01H\x08\x88\x01\x01\x12\x12\n\x05theta\x18\r \x01(\x01H\t\x88\x01\x01\x12\x11\n\x04vega\x18\x0e \x01(\x01H\n\x88\x01\x01\x12\x1b\n\x13shares_per_contract\x18\x0f \x01(\rB\x05\n\x03_oiB\t\n\x07_volumeB\x06\n\x04_bidB\x06\n\x04_askB\x07\n\x05_lastB\x06\n\x04_fmvB\x05\n\x03_ivB\x08\n\x06_deltaB\x08\n\x06_gammaB\x08\n\x06_thetaB\x07\n\x05_vega"W\n\x1bOffExchangeActivityResponse\x12\x38\n\x04rows\x18\x01 \x03(\x0b\x32*.itmatrixhq.rest.v1.OffExchangeActivityRow"\xbe\x02\n\x16OffExchangeActivityRow\x12\x0c\n\x04\x64\x61te\x18\x01 \x01(\t\x12\x1b\n\x13off_exchange_volume\x18\x02 \x01(\x01\x12\x10\n\x08notional\x18\x03 \x01(\x01\x12\x13\n\x0btrade_count\x18\x04 \x01(\x04\x12\x14\n\x0c\x61verage_size\x18\x05 \x01(\x01\x12\x0c\n\x04vwap\x18\x06 \x01(\x01\x12\x1f\n\x12off_exchange_share\x18\x07 \x01(\x01H\x00\x88\x01\x01\x12 \n\x13\x63onsolidated_volume\x18\x08 \x01(\x01H\x01\x88\x01\x01\x12"\n\x15\x63onsolidated_notional\x18\t \x01(\x01H\x02\x88\x01\x01\x42\x15\n\x13_off_exchange_shareB\x16\n\x14_consolidated_volumeB\x18\n\x16_consolidated_notional"a\n OffExchangeConcentrationResponse\x12=\n\x04rows\x18\x01 \x03(\x0b\x32/.itmatrixhq.rest.v1.OffExchangeConcentrationRow"\xab\x02\n\x1bOffExchangeConcentrationRow\x12\x0c\n\x04\x64\x61te\x18\x01 \x01(\t\x12\x17\n\x0f\x62ucket_midpoint\x18\x02 \x01(\x01\x12\x14\n\x0c\x62ucket_width\x18\x03 \x01(\x01\x12\x0e\n\x06volume\x18\x04 \x01(\x01\x12\x10\n\x08notional\x18\x05 \x01(\x01\x12\x13\n\x0btrade_count\x18\x06 \x01(\x04\x12\x19\n\x11\x64istinct_sessions\x18\x07 \x01(\r\x12\x12\n\nrank_score\x18\x08 \x01(\x01\x12\x0c\n\x04rank\x18\t \x01(\r\x12\x14\n\x0c\x62ucket_count\x18\n \x01(\r\x12\x19\n\x0c\x64istance_bps\x18\x0b \x01(\x01H\x00\x88\x01\x01\x12\x19\n\x11lookback_sessions\x18\x0c \x01(\rB\x0f\n\r_distance_bps"U\n\x1aOffExchangeProfileResponse\x12\x37\n\x04rows\x18\x01 \x03(\x0b\x32).itmatrixhq.rest.v1.OffExchangeProfileRow"w\n\x15OffExchangeProfileRow\x12\x0c\n\x04\x64\x61te\x18\x01 \x01(\t\x12\x19\n\x11price_thousandths\x18\x02 \x01(\x03\x12\x0e\n\x06volume\x18\x03 \x01(\x01\x12\x10\n\x08notional\x18\x04 \x01(\x01\x12\x13\n\x0btrade_count\x18\x05 \x01(\x04"]\n\x1eOffExchangeCompositionResponse\x12;\n\x04rows\x18\x01 \x03(\x0b\x32-.itmatrixhq.rest.v1.OffExchangeCompositionRow"\x9a\x01\n\x19OffExchangeCompositionRow\x12\x0c\n\x04\x64\x61te\x18\x01 \x01(\t\x12\x10\n\x08\x63\x61tegory\x18\x02 \x01(\t\x12\x0e\n\x06volume\x18\x03 \x01(\x01\x12\x10\n\x08notional\x18\x04 \x01(\x01\x12\x13\n\x0btrade_count\x18\x05 \x01(\x04\x12&\n\x1eshare_of_off_exchange_notional\x18\x06 \x01(\x01\x62\x06proto3'
+)
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(
+    DESCRIPTOR, "itmatrixhq.rest.v1.wire_pb2", _globals
+)
+if not _descriptor._USE_C_DESCRIPTORS:
+    DESCRIPTOR._loaded_options = None
+    _globals["_BARSRESPONSE"]._serialized_start = 54
+    _globals["_BARSRESPONSE"]._serialized_end = 258
+    _globals["_BAR"]._serialized_start = 261
+    _globals["_BAR"]._serialized_end = 397
+    _globals["_REPLAYRESPONSE"]._serialized_start = 400
+    _globals["_REPLAYRESPONSE"]._serialized_end = 570
+    _globals["_TICK"]._serialized_start = 572
+    _globals["_TICK"]._serialized_end = 647
+    _globals["_GEXGRIDRESPONSE"]._serialized_start = 650
+    _globals["_GEXGRIDRESPONSE"]._serialized_end = 1038
+    _globals["_GEXGRIDROW"]._serialized_start = 1041
+    _globals["_GEXGRIDROW"]._serialized_end = 1428
+    _globals["_CHAINRESPONSE"]._serialized_start = 1431
+    _globals["_CHAINRESPONSE"]._serialized_end = 1583
+    _globals["_CHAINROW"]._serialized_start = 1586
+    _globals["_CHAINROW"]._serialized_end = 1998
+    _globals["_OFFEXCHANGEACTIVITYRESPONSE"]._serialized_start = 2000
+    _globals["_OFFEXCHANGEACTIVITYRESPONSE"]._serialized_end = 2087
+    _globals["_OFFEXCHANGEACTIVITYROW"]._serialized_start = 2090
+    _globals["_OFFEXCHANGEACTIVITYROW"]._serialized_end = 2408
+    _globals["_OFFEXCHANGECONCENTRATIONRESPONSE"]._serialized_start = 2410
+    _globals["_OFFEXCHANGECONCENTRATIONRESPONSE"]._serialized_end = 2507
+    _globals["_OFFEXCHANGECONCENTRATIONROW"]._serialized_start = 2510
+    _globals["_OFFEXCHANGECONCENTRATIONROW"]._serialized_end = 2809
+    _globals["_OFFEXCHANGEPROFILERESPONSE"]._serialized_start = 2811
+    _globals["_OFFEXCHANGEPROFILERESPONSE"]._serialized_end = 2896
+    _globals["_OFFEXCHANGEPROFILEROW"]._serialized_start = 2898
+    _globals["_OFFEXCHANGEPROFILEROW"]._serialized_end = 3017
+    _globals["_OFFEXCHANGECOMPOSITIONRESPONSE"]._serialized_start = 3019
+    _globals["_OFFEXCHANGECOMPOSITIONRESPONSE"]._serialized_end = 3112
+    _globals["_OFFEXCHANGECOMPOSITIONROW"]._serialized_start = 3115
+    _globals["_OFFEXCHANGECOMPOSITIONROW"]._serialized_end = 3269
+# @@protoc_insertion_point(module_scope)