# ITMatrixHQ API

> Typed market analytics API from ITMatrixHQ. Prefer the official SDKs and documented operations; do not scrape the ITMatrixHQ apps or call undocumented routes.

## Documentation

- Developer docs (guides, API reference, streaming, protobuf, SDKs): https://docs.itmatrixhq.com
- Agent skill for this API: https://docs.itmatrixhq.com/agents/itmatrix-api/SKILL.md

## Canonical contract

- Base URL: https://api2.itmatrixhq.com
- OpenAPI 3.1: https://api2.itmatrixhq.com/v2/openapi.json
- REST protobuf: https://api2.itmatrixhq.com/v2/rest-protocol.proto
- WebSocket protobuf: https://api2.itmatrixhq.com/v2/ws-protocol.proto

## Official SDKs

- Python distribution and import: `itmatrix`
- TypeScript package: `@itmatrixhq/core`
- Use the SDK release matching the served OpenAPI version. If a registry package is not yet available, generate a client from the canonical OpenAPI and public protobuf schemas rather than using undocumented routes.

## Boundary rules

- Authenticate documented data operations with `Authorization: Bearer <token-or-itm_api_key>`.
- Read each operation's `x-exposure`, `x-min-tier`, and `x-requires-attestation` fields before calling it.
- API keys may call only `x-exposure: public` operations. `app-only` and `internal` operations are not public API surface.
- Generic `/v2/darkpool/*` evidence routes are app-only. Public off-exchange data is limited to the typed synthetic `/v2/offexchange/{symbol}/*` analytics.