Agent skill

itmatrix API clients

Use the installed itmatrix Python package or @itmatrixhq/core TypeScript package. Check the installed version's package README or types for signatures before coding; this skill may outlive a package release. Take credentials from the application's configured environment and keep them out of logs and generated output. An SDK method does not grant an API key access to an app-only route.

Choose the smallest useful method

• Start with named methods and grouped resources. Use get_gex / getGex, get_option_chain / getOptionChain, and get_bars / getBars for direct reads. The Python sync client is itmatrix.ITMClient, the async client is itmatrix.AsyncITMClient, and the TypeScript client is ITMClient from @itmatrixhq/core.
• For a New York calendar period, use get_bars_for_period(symbol, "today") or getBarsForPeriod(symbol, "today"). Other supported periods are week_to_date, month_to_date, year_to_date, and calendar_month with a YYYY-MM month. Today defaults to 1-minute bars; longer periods default to daily bars. These return one page, not a complete observed month. Inspect meta.cursor and fetch additional pages when completeness matters.
• For GEX levels, use get_gex_analysis / getGexAnalysis to fetch and analyze once. analyze_gex / analyzeGex works on a grid already in hand. Server net_gex and nullable flip_point supply net exposure and zero gamma. Positive/negative level rankings cover only returned strike rows; top or tier limits can hide stronger levels. Do not call them full-chain walls or infer market direction from exposure sign.
• Use flow for bounded public options-flow views and offexchange for synthetic activity, concentration, profile, and composition. Do not construct raw dark-pool/evidence URLs. Live large trades require a symbol or premium floor; EOD flow requires a session and one of those constraints. Server attestation and entitlements still apply.

Preserve what the response says

Keep data with its metadata, HTTP status, request ID, and ETag where the caller needs provenance or cache behavior. Check freshness, coverage, session/capture, caps, and any partial or delayed signal before presenting a result as current or complete. Preserve nulls: unavailable zero gamma or missing prices are not zero. Timestamps ending _ms are epoch milliseconds; strike filters use integer thousandths of dollars where specified.

JSON is the default. Public protobuf is an optional transport for supported market-data operations and produces the same domain models. Use only JSON or public protobuf; do not request other media types. A 304 supplies no replacement data; use retained cached data only if the application actually has it. On entitlement errors, surface the code and request ID. Let the SDK perform its bounded safe-read retries; do not add blind retries for mutations.

For lists or bars, follow only the cursor the response provides. Bound page and row counts, and stop on a missing or repeated cursor. Do not silently turn the first page into a monthly aggregate or full-history study.

Streams

Python streams use AsyncITMClient; TypeScript streams use the client stream API. Keep one shared connection, bounded subscriptions, and close them through their lifecycle methods. A ticket authorizes a connection handshake; mint a new ticket for a real reconnect, not because a healthy connection's ticket expired. Treat backpressure errors as data loss requiring an explicit recovery decision.

Minimal examples

import os
import itmatrix as itm

with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
    result = client.get_gex_analysis("SPY", levels=3)
    print(result.data.net_gex, result.data.zero_gamma)
    print(result.data.levels_scope)  # returned_rows
    month = client.get_bars_for_period("SPY", "calendar_month", month="2026-09")
    print(month.meta.get("cursor"))  # continue if complete history is required

import { ITMClient } from "@itmatrixhq/core";

const client = new ITMClient({ apiKey: process.env.ITM_API_KEY });
const analysis = await client.getGexAnalysis("SPY", { levels: 3 });
console.log(analysis.data.netGex, analysis.data.zeroGamma);
const month = await client.getBarsForPeriod("SPY", "calendar_month", { month: "2026-09" });
console.log(month.meta.cursor); // continue if complete history is required