sharketo-sdk 0.1.14b3__tar.gz

sharketo_sdk-0.1.14b3/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "sharketo-python",
+  "version": "0.1.14b3",
+  "license": "MIT",
+  "description": "Python SDK integration, cache-only Dealer Exposures, bounded BTC/ETH current crypto exposure, prices, expiry flow, daily history, inventory rendering/exposure profiles and full-asset/compact Seasonality, curated Volatility/RRG and CTA Flow guidance; mock first, server-side credentials only."
+}

sharketo_sdk-0.1.14b3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sharketo Market Intelligence
+
+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.

sharketo_sdk-0.1.14b3/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: sharketo-sdk
+Version: 0.1.14b3
+Summary: Server-side Sharketo Python client for cache-only Dealer Exposures, BTC/ETH current crypto inventory, prices, Index Inventory, Seasonality, curated Volatility, RRG and CTA Flow
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: websockets<17,>=15
+Provides-Extra: dashboard
+Requires-Dist: altair<7,>=5.5; extra == 'dashboard'
+Requires-Dist: streamlit<2,>=1.49; extra == 'dashboard'
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: datamodel-code-generator==0.53.0; extra == 'dev'
+Requires-Dist: hatchling<2,>=1.27; extra == 'dev'
+Requires-Dist: jsonschema<5,>=4.23; extra == 'dev'
+Requires-Dist: mypy<2,>=1.15; extra == 'dev'
+Requires-Dist: packaging<27,>=26.1; extra == 'dev'
+Requires-Dist: pytest-asyncio<2,>=0.25; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: pyyaml<7,>=6; extra == 'dev'
+Requires-Dist: ruff==0.16.10; extra == 'dev'
+Requires-Dist: twine<8,>=7; extra == 'dev'
+Provides-Extra: notebook
+Requires-Dist: jupyterlab<5,>=4; extra == 'notebook'
+Description-Content-Type: text/markdown
+
+# Sharketo Python SDK
+
+Server-side Python 3.11+ client for Sharketo developer APIs. Supported products include
+Index Inventory, prices, daily inventory history, expiry flow, Seasonality, CTA Flow,
+RRG, crypto inventory, Dealer Exposures and curated Volatility.
+
+Version **0.1.14b3** matches the bundled coding-agent skill. SDK installation does not
+grant API access or establish live product availability. Obtain authorized credentials
+and approval for live use separately. All SDK Developer data access requires effective
+Apex access, including live prices and `get_access()` diagnostics. A usable API key or
+Pro portal/integration access alone does not grant Developer data access. The server
+evaluates effective access, including valid existing grants; other access requirements
+and service availability still apply.
+
+## Install and try it offline
+
+In your application's Python 3.11+ virtual environment, install the SDK from PyPI:
+
+```sh
+python -m pip install --index-url https://pypi.org/simple/ sharketo-sdk==0.1.14b3
+python -m sharketo.quickstart
+```
+
+Use an environment without configured extra package indexes. If the matching release is
+unavailable on PyPI, stop and report the unavailable version. Do not substitute another
+version, package index or source checkout.
+
+For a uv project, use `uv add --default-index https://pypi.org/simple/ sharketo-sdk==0.1.14b3`,
+then `uv run python -m sharketo.quickstart`.
+
+The quickstart uses invented data through an in-memory HTTP transport. It reads no
+credentials, opens no network sockets and does not validate API entitlements or service
+health.
+
+## Configure an authorized application
+
+Constructors take an explicit server-side key and do not read environment variables:
+
+```python
+from sharketo import SharketoClient
+
+
+def read_summary(api_key, ticker):
+    with SharketoClient(api_key) as client:
+        return client.index_inventory.get_summary(ticker)
+```
+
+Omitted/`None` `api_url` selects `https://api.sharketo.com`.
+`AsyncSharketoClient(api_key)` uses that API and `wss://socket.sharketo.com/v1/ws`;
+use `async with` and await HTTP methods. A custom API alone is HTTP-only: subscribing
+raises `ValueError` until an explicit `websocket_url` is supplied. A custom WebSocket URL
+with an omitted/`None` API URL raises `ValueError`. Explicit API/WS pairs are accepted
+without inferring hosts or ports.
+
+For environment-based switching, provision `SHARKETO_API_KEY` through server-side secret
+tooling, then use `SharketoClient.from_env()` or `AsyncSharketoClient.from_env()` in the
+corresponding context manager. Both read `SHARKETO_API_KEY`/`SHARKETO_API_URL` once at
+construction; only the async factory reads `SHARKETO_WEBSOCKET_URL`. Missing URL variables
+use defaults; a missing/invalid key or blank/invalid URL variable raises `ValueError`.
+The factories accept constructor limits/transport options, but no key/endpoint overrides;
+use constructors for explicit values.
+
+Leave both URL variables unset for production defaults. Use overrides only for a
+configuration supplied by Sharketo, with a key authorized for that service. Environment
+changes affect new clients only. The SDK does not scan dotenv files or fall back to
+production on failure. HTTPS/WSS retain verified TLS; plain HTTP/WS are loopback-only.
+
+## Optional coding-agent skill
+
+The package bundles version-matched SDK usage guidance and synthetic examples.
+Installation into an agent is explicit; pip does not change agent configuration. If a
+matching skill is already installed, use it without creating a duplicate.
+
+From your application directory, with the SDK's Python environment active:
+
+```sh
+python -m sharketo.skills install --agent claude-code --scope project
+```
+
+Use `--agent codex` instead for Codex. Run `python -m sharketo.skills --help` for installation
+and export options. Installing the skill does not install Python dependencies, configure
+credentials or grant API access. Keep credentials in server-side environment/secret
+storage, not source code or agent instructions.
+
+## Distribution and license
+
+Distributions contain the SDK source, bundled usage guides and synthetic fixtures,
+plugin resources, license and package/build metadata.
+
+SDK and bundled skill code are MIT-licensed. This license does not grant access to
+Sharketo services.

sharketo_sdk-0.1.14b3/PYPI_README.md

@@ -0,0 +1,91 @@
+# Sharketo Python SDK
+
+Server-side Python 3.11+ client for Sharketo developer APIs. Supported products include
+Index Inventory, prices, daily inventory history, expiry flow, Seasonality, CTA Flow,
+RRG, crypto inventory, Dealer Exposures and curated Volatility.
+
+Version **0.1.14b3** matches the bundled coding-agent skill. SDK installation does not
+grant API access or establish live product availability. Obtain authorized credentials
+and approval for live use separately. All SDK Developer data access requires effective
+Apex access, including live prices and `get_access()` diagnostics. A usable API key or
+Pro portal/integration access alone does not grant Developer data access. The server
+evaluates effective access, including valid existing grants; other access requirements
+and service availability still apply.
+
+## Install and try it offline
+
+In your application's Python 3.11+ virtual environment, install the SDK from PyPI:
+
+```sh
+python -m pip install --index-url https://pypi.org/simple/ sharketo-sdk==0.1.14b3
+python -m sharketo.quickstart
+```
+
+Use an environment without configured extra package indexes. If the matching release is
+unavailable on PyPI, stop and report the unavailable version. Do not substitute another
+version, package index or source checkout.
+
+For a uv project, use `uv add --default-index https://pypi.org/simple/ sharketo-sdk==0.1.14b3`,
+then `uv run python -m sharketo.quickstart`.
+
+The quickstart uses invented data through an in-memory HTTP transport. It reads no
+credentials, opens no network sockets and does not validate API entitlements or service
+health.
+
+## Configure an authorized application
+
+Constructors take an explicit server-side key and do not read environment variables:
+
+```python
+from sharketo import SharketoClient
+
+
+def read_summary(api_key, ticker):
+    with SharketoClient(api_key) as client:
+        return client.index_inventory.get_summary(ticker)
+```
+
+Omitted/`None` `api_url` selects `https://api.sharketo.com`.
+`AsyncSharketoClient(api_key)` uses that API and `wss://socket.sharketo.com/v1/ws`;
+use `async with` and await HTTP methods. A custom API alone is HTTP-only: subscribing
+raises `ValueError` until an explicit `websocket_url` is supplied. A custom WebSocket URL
+with an omitted/`None` API URL raises `ValueError`. Explicit API/WS pairs are accepted
+without inferring hosts or ports.
+
+For environment-based switching, provision `SHARKETO_API_KEY` through server-side secret
+tooling, then use `SharketoClient.from_env()` or `AsyncSharketoClient.from_env()` in the
+corresponding context manager. Both read `SHARKETO_API_KEY`/`SHARKETO_API_URL` once at
+construction; only the async factory reads `SHARKETO_WEBSOCKET_URL`. Missing URL variables
+use defaults; a missing/invalid key or blank/invalid URL variable raises `ValueError`.
+The factories accept constructor limits/transport options, but no key/endpoint overrides;
+use constructors for explicit values.
+
+Leave both URL variables unset for production defaults. Use overrides only for a
+configuration supplied by Sharketo, with a key authorized for that service. Environment
+changes affect new clients only. The SDK does not scan dotenv files or fall back to
+production on failure. HTTPS/WSS retain verified TLS; plain HTTP/WS are loopback-only.
+
+## Optional coding-agent skill
+
+The package bundles version-matched SDK usage guidance and synthetic examples.
+Installation into an agent is explicit; pip does not change agent configuration. If a
+matching skill is already installed, use it without creating a duplicate.
+
+From your application directory, with the SDK's Python environment active:
+
+```sh
+python -m sharketo.skills install --agent claude-code --scope project
+```
+
+Use `--agent codex` instead for Codex. Run `python -m sharketo.skills --help` for installation
+and export options. Installing the skill does not install Python dependencies, configure
+credentials or grant API access. Keep credentials in server-side environment/secret
+storage, not source code or agent instructions.
+
+## Distribution and license
+
+Distributions contain the SDK source, bundled usage guides and synthetic fixtures,
+plugin resources, license and package/build metadata.
+
+SDK and bundled skill code are MIT-licensed. This license does not grant access to
+Sharketo services.

sharketo_sdk-0.1.14b3/hatch_build.py

@@ -0,0 +1,15 @@
+"""Keep Hatchling from automatically appending VCS ignore files to source archives."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        forced = build_data["force_include"]
+        for source, target in tuple(forced.items()):
+            if target in {".gitignore", ".hgignore"}:
+                del forced[source]

sharketo_sdk-0.1.14b3/plugin.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "sharketo-python",
+  "version": "0.1.14b3",
+  "license": "MIT",
+  "description": "Python SDK integration, cache-only Dealer Exposures, bounded BTC/ETH current crypto exposure, prices, expiry flow, daily history, inventory rendering/exposure profiles and full-asset/compact Seasonality, curated Volatility/RRG and CTA Flow guidance; mock first, server-side credentials only."
+}

sharketo_sdk-0.1.14b3/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sharketo-sdk"
+version = "0.1.14b3"
+description = "Server-side Sharketo Python client for cache-only Dealer Exposures, BTC/ETH current crypto inventory, prices, Index Inventory, Seasonality, curated Volatility, RRG and CTA Flow"
+readme = "PYPI_README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.28,<1", "pydantic>=2.10,<3", "websockets>=15,<17"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<10", "pytest-asyncio>=0.25,<2", "ruff==0.16.10", "mypy>=1.15,<2", "datamodel-code-generator==0.53.0", "jsonschema>=4.23,<5", "build>=1.2,<2", "hatchling>=1.27,<2", "twine>=7,<8", "packaging>=26.1,<27", "PyYAML>=6,<7"]
+dashboard = ["streamlit>=1.49,<2", "altair>=5.5,<7"]
+notebook = ["jupyterlab>=4,<5"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sharketo"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/sharketo-python" = "sharketo/_skills/sharketo-python"
+"plugin.json" = "sharketo/_skills/openai-plugin.json"
+".claude-plugin/plugin.json" = "sharketo/_skills/claude-plugin.json"
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+  "src/sharketo",
+  "skills/sharketo-python",
+  "plugin.json",
+  ".claude-plugin/plugin.json",
+  "pyproject.toml",
+  "hatch_build.py",
+  "PYPI_README.md",
+  "LICENSE",
+]
+
+[tool.hatch.build.targets.sdist.hooks.custom]
+path = "hatch_build.py"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = ["live: opt-in read-only tests against an explicitly configured local dev stack"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC"]
+
+[tool.ruff.lint.per-file-ignores]
+"_generated.py" = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/sharketo"]

sharketo_sdk-0.1.14b3/skills/sharketo-python/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sharketo Market Intelligence
+
+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.

sharketo_sdk-0.1.14b3/skills/sharketo-python/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: sharketo-python
+description: Use when integrating the Sharketo Python SDK into an application, service, report, notebook or dashboard. Covers Index Inventory, prices, crypto inventory, Dealer Exposures, expiry flow, daily history, Seasonality, Volatility, RRG and CTA Flow APIs, async streams, data interpretation, installation, first-time API key setup and read-only access diagnostics.
+license: LICENSE
+metadata:
+  version: "0.1.14b3"
+---
+
+# Sharketo Python SDK
+
+## Developer API access
+
+All SDK data access requires effective Apex access, including live prices and
+`get_access()` diagnostics. A usable key or Pro portal/integration access is insufficient.
+The backend evaluates effective access, including valid existing grants; do not infer it
+from a billing label or add a client-side plan gate/preflight. For denied access, preserve
+sanitized capability/plan metadata and follow [terminal diagnostics](references/sdk.md#read-only-diagnostics-and-terminal-errors).
+
+## Personal-use scope
+
+Developer access covers private, noncommercial applications used only by the subscriber.
+Work for an employer or client is outside this scope. See
+[personal-use boundaries](references/integration.md#personal-use-boundaries) for hosting,
+sharing and code publication.
+
+## Start from the user's application
+
+1. If the SDK is missing or its version is uncertain, follow [installation](references/install.md) for the matching PyPI release and offline verification. Skill installation alone does not install the SDK.
+2. Select a family below and read its API and data semantics before coding. For client options, summary models, errors or stream limits, read the relevant section of the [SDK reference](references/sdk.md).
+3. Use [application integration](references/integration.md) for client reuse, stream lifecycle, status refresh and error handling.
+4. Check the changed behavior with the application's tests and the relevant guide's offline fixture. For agent-run live checks, follow the [validation workflow](references/workflow.md).
+
+## Select a capability
+
+| Requested data | Reference |
+| --- | --- |
+| SPX/NDX compact inventory summaries | [SDK clients and summary models](references/sdk.md#clients-and-subscriptions) |
+| SPX/NDX strike contributions, exposure/spot/IV history, session Bookmap | [Inventory rendering](references/inventory-rendering.md) |
+| Opt-in conditional-price exposure profiles | [Profiles](references/profiles.md) |
+| SPX/NDX replacement quotes | [Prices](references/prices.md) |
+| BTC/ETH current crypto exposure state | [Crypto inventory](references/crypto-inventory.md) |
+| SPX/NDX/SPY/QQQ cache-only dealer snapshots | [Dealer Exposures](references/dealer-exposures.md) |
+| SPX/NDX expiry-flow latest and selected hourly history | [Expiry flow](references/expiry-flow.md) |
+| Bounded daily reconstructed inventory history | [Daily history](references/daily-history.md) |
+| Full per-asset seasonal analysis and compact seasonal tables | [Seasonality](references/seasonality.md) |
+| Curated volatility catalog, asset and term-structure snapshots | [Volatility](references/volatility.md) |
+| Curated relative-rotation catalog, group and screener snapshots | [RRG](references/rrg.md) |
+| Modeled positioning and scenario-flow snapshot | [CTA Flow](references/cta-flow.md) |
+| SDK/skill installation, version matching, host discovery or export | [Installation](references/install.md) |
+| Portal API key creation or first-time server-side credential configuration | [First-time API key setup](references/setup.md) |
+| Access failures and sanitized diagnostics | [SDK error boundary](references/sdk.md#read-only-diagnostics-and-terminal-errors) |
+
+## Common boundaries
+
+- Consume complete replacement states instead of handling raw full, delta or tail messages.
+- Preserve supplied financial values, classifications, units, signs, provenance and null versus zero. Label application calculations separately.
+- Keep source time, publication time, receipt time and transport status separate. If source freshness is unknown, leave it unknown. For calendar-date fields, follow [date-only display](references/integration.md#calendar-date-display).
+- Keep API keys server-side and out of browser inputs, frontend bundles, notebook cells and outputs, URLs and logs.
+- For production defaults or custom environments, follow [endpoint configuration](references/integration.md#endpoints-and-environment-configuration).

sharketo_sdk-0.1.14b3/skills/sharketo-python/references/crypto-inventory.md

@@ -0,0 +1,140 @@
+# Crypto current inventory, SDK 0.1.14b3
+
+For stream lifecycle and status refresh, see [application integration](integration.md#streams).
+
+## Public usage
+
+`client.crypto_inventory.subscribe_inventory("BTC", time_window="24h")` is an async-only,
+nonawaitable lazy factory. Use `async with ... as sub` and `async for snapshot in sub`.
+Close the subscription and client on cancellation. A resolved `websocket_url` is required.
+Use the documented production default or an explicitly approved custom URL, as described in
+[configuration](integration.md#endpoints-and-environment-configuration).
+
+Only canonical BTC and ETH are supported. The windows are 1h, 4h, 8h, 24h (default), 7d,
+1m, 3m, 6m, 1y and max. Currency and window identify a subscription on `cryptoInventory.v1`.
+One async client shares its socket with SPX and NDX inventory and prices. This stream has
+no HTTP endpoint, polling API or optional section parameters. It needs no access or catalog preflight.
+Browser credentials are unsupported. `get_access()` remains index-specific.
+
+`CryptoInventorySubscription` exposes currency, time_window, status, latest and `aclose()`.
+Every `CryptoInventoryStreamSnapshot.inventory` is a complete `CryptoInventoryState`.
+It contains read-only entries with opaque keys, frozen leaves and a tracked_expirations tuple.
+Totals and market metadata replace the previous values. The SDK applies full resets, then
+removals, then whole-entry upserts before latest-only delivery. Applications consume the
+complete state rather than accumulate deltas. Reconnect requires a new baseline. There is
+no sequence, replay or every-provider-event guarantee. Never parse entry map keys.
+
+The window identifies the selector and its history metadata, not a rolling position interval.
+Every window exposes the current active flow-formed book. `window_duration_ms` is fixed
+selector metadata (max=None), not coverage. Preserve backend-computed financial values.
+Python formulas are not a substitute for missing SDK fields.
+
+## Display and units
+
+- Entry position and OI are underlying BTC or ETH coin quantities, not contracts multiplied
+  by 100 or dollar amounts. OI is nullable as a whole. Null means unknown, not zero.
+  Positions and exposures are signed, and zero is valid. Spot and strike are USD per
+  underlying coin.
+- Entry `iv.call/put`, `atm_iv` and IV buckets are annualized decimals (0.65 = 65%).
+  `dvol` is a percentage-index level (65 = 65%). Preserve explicit nulls in IV buckets.
+- The server computes `entry.exposures.call/put` and `exposure_totals.all/by_category`.
+  Preserve all supplied exposure fields and their backend dollar-scaled sensitivity
+  conventions. Do not re-dollarize them or infer shock normalization. Raw delta is a
+  signed delta measure. Raw theta is USD/year, not per day. Some higher-order measures
+  can be zero when not computed. Use the supplied server totals rather than summing
+  displayed rows.
+- The IV accessors are `.field_0_dte`, `.field_1_dte`, `.weekly`, `.monthly` and `.all`.
+  Category totals also have `.long`. Tracked expirations have `.expiration`,
+  `.expiration_timestamp` and nullable `.primary_bucket`. Crypto settlement is 08:00 UTC.
+- `reference_timestamp_ms` is server reference time and can advance without new market
+  observations. `emitted_at_ms` is publication time. Neither measures per-metric
+  provider freshness. `received_at_ms` and monotonic `receipt_age_seconds` measure local
+  receipt. `disconnected` means retained data is transport-stale. Old wrappers remain
+  disconnected after reconnect. Keep retained values marked disconnected until replacement.
+  Do not infer a TTL, stale property, source-age SLA, timestamp ordering, readiness or source
+  freshness. Empty startup zero market values are not live quotes.
+- The SDK rejects data that exceeds its bounds rather than cropping it. The limits are
+  10,000 accumulated entries, 10,000 removals per frame, 10,000 tracked expirations,
+  128-byte opaque keys, 32-byte expiration text and 8 MiB decoded envelopes.
+  The materialized payload reserves 1 KiB. Slow consumers may close.
+
+Access requires effective Apex access through `developer_api` and an API key with
+verified email, ApiKeys and InventoryCrypto. Existing
+quotas and policy apply. For agent-run live checks, follow the
+[validation workflow](workflow.md).
+
+## Offline validation fixture (installed package)
+
+```python
+from types import MappingProxyType
+from dataclasses import FrozenInstanceError
+from pydantic import ValidationError
+from sharketo import (
+    CryptoFullExposures,
+    CryptoInventoryEntry,
+    CryptoInventoryState,
+    CryptoExposureTotals,
+    CryptoAtmIvByBucket,
+)
+
+metrics = tuple(CryptoFullExposures.model_fields)
+zero = dict.fromkeys(metrics, 0.0)  # Invented values, not computed finance.
+entry = CryptoInventoryEntry.model_validate(
+    {
+        "strike": 60000.0,
+        "expiration": "2026-01-31",
+        "expirationTimestampMs": 1769846400000,
+        "position": {"call": -2.0, "put": 0.0},
+        "exposures": {"call": {**zero, "gex": -2500.0}, "put": zero},
+        "iv": {"call": 0.65, "put": 0.0},
+        "openInterest": None,
+    }
+)
+totals = CryptoExposureTotals.model_validate(
+    {
+        "all": {**zero, "gex": -2500.0},
+        "byCategory": {key: zero for key in ("0DTE", "1DTE", "WEEKLY", "MONTHLY", "LONG")},
+    }
+)
+iv = CryptoAtmIvByBucket.model_validate(
+    {
+        "0DTE": None,
+        "1DTE": 0.0,
+        "WEEKLY": None,
+        "MONTHLY": 0.65,
+        "ALL": 0.65,
+    }
+)
+state = CryptoInventoryState(
+    currency="BTC",
+    time_window="24h",
+    reference_timestamp_ms=1769760000000,
+    emitted_at_ms=1769760001000,
+    window_duration_ms=86400000,
+    entries=MappingProxyType({"opaque": entry}),
+    exposure_totals=totals,
+    spot_price=60000.0,
+    dvol=65.0,
+    atm_iv=0.65,
+    atm_iv_by_bucket=iv,
+    tracked_expirations=(),
+)
+assert state.entries["opaque"].position.call == -2.0
+assert state.entries["opaque"].position.put == 0.0
+assert state.entries["opaque"].open_interest is None
+assert state.atm_iv_by_bucket.field_0_dte is None
+assert state.atm_iv_by_bucket.field_1_dte == 0.0
+assert state.exposure_totals.all.gex == -2500.0
+for mutate, error in (
+    (lambda: state.entries.__setitem__("bad", entry), AttributeError),
+    (lambda: setattr(entry.position, "call", 99), ValidationError),
+    (lambda: setattr(state, "currency", "ETH"), FrozenInstanceError),
+):
+    try:
+        mutate()
+    except error:
+        pass
+    else:
+        raise AssertionError("Synthetic public state lost immutability")
+print("Synthetic BTC current book: signed/zero/null and frozen state preserved")
+```