siftingio 0.1.0__tar.gz

siftingio-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

siftingio-0.1.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `siftingio` are documented here. Format follows
+[Keep a Changelog](https://keepachangelog.com); the project adheres to SemVer.
+
+## [0.1.0] — Unreleased
+
+Initial release.
+
+### Added
+- `SiftingClient` (sync) and `AsyncSiftingClient` (async) covering the full data
+  plane: `last`, `stocks`, `filers`, `markets`, `forex`, `crypto`, `dex`,
+  `economic_calendar`.
+- Live WebSocket clients: `AsyncSiftingSocket` (asyncio) and a thread-backed
+  sync `SiftingSocket`, both with auto-reconnect and subscription replay.
+- Cursor auto-pagination: `auto_paginate` / `collect_all` and async
+  `aauto_paginate` / `acollect_all`.
+- Automatic retries (429/5xx with `Retry-After`), gzip negotiation, per-request
+  timeouts, and typed errors (`SiftingAPIError`, `SiftingConnectionError`).
+- Full type hints (`py.typed`); responses typed via `TypedDict`.
+- Python 3.9+; depends only on `httpx` and `websockets`.

siftingio-0.1.0/CLAUDE.md

@@ -0,0 +1,89 @@
+# CLAUDE.md — `siftingio` (Python)
+
+Guidance for maintaining and extending the SiftingIO Python SDK. It wraps the
+**data plane only** — the API-key-authenticated `/v1/*` endpoints from
+`SiftingIO_API_V1/router/router.go`. It does **not** wrap the `/ops/v1/*`
+control plane (auth, billing, account); that is the SPA's surface.
+
+The package mirrors the TypeScript SDK (`../typescript`) endpoint-for-endpoint,
+so keep the two in sync when the API changes.
+
+## Layout
+
+```
+src/siftingio/
+  __init__.py        — public surface + __version__ (hatch reads this)
+  client.py          — SiftingClient (sync) + AsyncSiftingClient (async)
+  _transport.py      — _SyncTransport / _AsyncTransport: auth, gzip, retries, errors
+  errors.py          — SiftingError / SiftingAPIError / SiftingConnectionError
+  types.py           — TypedDict response shapes + Literal unions
+  pagination.py      — auto_paginate / collect_all (+ async aauto_paginate / acollect_all)
+  resources/
+    _base.py         — Req namedtuple, seg(), _SyncResource / _AsyncResource bases
+    *.py             — one module per namespace; see "sync/async pattern" below
+  ws/
+    client.py        — AsyncSiftingSocket + thread-backed sync SiftingSocket
+    types.py         — WebSocket protocol TypedDicts
+tests/               — pytest (httpx.MockTransport for REST, a local ws server for WS)
+examples/            — runnable rest.py / websocket.py
+```
+
+## The sync/async pattern (important)
+
+Each resource module has **one request-builder per endpoint** (`_profile`,
+`_filings`, …) that returns a `Req(path, params)` — this is the single source of
+truth for routing. Then two thin classes, `XResource` (sync) and
+`AsyncXResource` (async), each expose one-line methods that call `self._get` /
+`self._aget`. When you add an endpoint you write: one builder + two one-liners +
+a `TypedDict`. The actual logic lives only in the builder.
+
+Python keyword collisions (`from`) use a trailing-underscore kwarg (`from_`) on
+the public method; the builder maps it to the real query key (`"from"`).
+
+## Commands
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest -q          # tests (REST + WebSocket)
+.venv/bin/mypy src/siftingio # strict type check
+.venv/bin/ruff check src     # lint
+.venv/bin/python -m build --wheel   # build distribution
+```
+
+## Adding or changing an endpoint
+
+The Go API is the source of truth — read `router.go` for the route and
+`model/fundamentals.go` (or the relevant `service/*`) for the response struct.
+
+1. Add a `_req` builder in the matching `resources/*.py`, encoding every dynamic
+   segment with `seg(...)` and listing query params in the params dict.
+2. Add a `TypedDict` in `types.py` mirroring the Go struct field-for-field
+   (JSON casing, `total=False`).
+3. Add the sync method to `XResource` and the async method to `AsyncXResource`.
+4. Re-export new public types from `__init__.py` if user-facing.
+5. Add a test in `tests/` using `httpx.MockTransport`.
+6. Run `pytest`, `mypy`, `ruff`. Mirror the change in the TypeScript SDK.
+
+### Gzip-required endpoints
+
+`stocks.screener`, `stocks.financials`, `stocks.financial_concept`,
+`stocks.bars`, `forex.bars`, `crypto.bars` return 406 without
+`Accept-Encoding: gzip`. The transport sends it on every request and httpx
+decompresses transparently, so no per-method handling is needed.
+
+## Conventions
+
+- Runtime deps are only `httpx` + `websockets`. Don't add more without cause.
+- `from __future__ import annotations` at the top of every module — this is what
+  lets us use `list[...]` / `X | None` while still supporting Python 3.9.
+- Responses are returned as raw dicts (typed via `TypedDict`); we don't validate
+  or construct models at runtime. `mypy` runs with `warn_return_any = false`
+  because of this.
+- Resources never import httpx — only the transport does.
+- Semver, mirrored with the TS package. Keep `CHANGELOG.md` and `__version__`
+  in step.
+
+## Releasing
+
+`pytest && mypy src/siftingio && ruff check src` → bump `__version__` →
+update `CHANGELOG.md` → `python -m build` → `twine upload dist/*`.

siftingio-0.1.0/LICENSE

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

siftingio-0.1.0/Makefile

@@ -0,0 +1,72 @@
+# Makefile for the siftingio Python SDK.
+#
+# Publishing reads the PyPI token from the environment — never hardcode it here.
+# Set it for the session (don't commit it anywhere):
+#
+#     export TWINE_PASSWORD='pypi-...'      # the token value
+#     make publish-test                     # upload to TestPyPI first
+#     make publish                          # upload to real PyPI
+#
+# TWINE_USERNAME defaults to __token__ (correct for API-token auth).
+
+PY        := .venv/bin/python
+PIP       := .venv/bin/pip
+VENV      := .venv
+
+export TWINE_USERNAME ?= __token__
+
+.PHONY: help venv install test lint typecheck check build dist-check \
+        publish-test publish clean
+
+help:
+	@echo "Targets:"
+	@echo "  venv         Create the virtualenv (.venv)"
+	@echo "  install      Install the package + dev tools (editable)"
+	@echo "  test         Run the test suite"
+	@echo "  lint         Run ruff"
+	@echo "  typecheck    Run mypy (strict)"
+	@echo "  check        lint + typecheck + test"
+	@echo "  build        Build sdist + wheel into dist/"
+	@echo "  dist-check   Validate built artifacts with twine check"
+	@echo "  publish-test Upload to TestPyPI  (needs TWINE_PASSWORD)"
+	@echo "  publish      Upload to PyPI      (needs TWINE_PASSWORD)"
+	@echo "  clean        Remove build artifacts and caches"
+
+$(VENV):
+	python3 -m venv $(VENV)
+
+venv: $(VENV)
+
+install: venv
+	$(PIP) install -e ".[dev]"
+
+test:
+	$(PY) -m pytest -q
+
+lint:
+	$(PY) -m ruff check src
+
+typecheck:
+	$(PY) -m mypy src/siftingio
+
+check: lint typecheck test
+
+build: clean
+	$(PY) -m build
+
+dist-check:
+	$(PY) -m twine check dist/*
+
+# Gated on a green build + metadata check so a bad artifact never ships.
+publish-test: check build dist-check
+	@test -n "$$TWINE_PASSWORD" || { echo "ERROR: set TWINE_PASSWORD to your TestPyPI token"; exit 1; }
+	$(PY) -m twine upload --repository testpypi dist/*
+
+publish: check build dist-check
+	@test -n "$$TWINE_PASSWORD" || { echo "ERROR: set TWINE_PASSWORD to your PyPI token"; exit 1; }
+	$(PY) -m twine upload dist/*
+
+clean:
+	rm -rf dist build *.egg-info src/*.egg-info
+	rm -rf .pytest_cache .mypy_cache .ruff_cache
+	find . -type d -name __pycache__ -prune -exec rm -rf {} +

siftingio-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: siftingio
+Version: 0.1.0
+Summary: Official Python SDK for the SiftingIO market data API (sync + async REST, plus WebSocket).
+Project-URL: Homepage, https://sifting.io
+Project-URL: Documentation, https://sifting.io/docs
+Project-URL: Source, https://github.com/siftingio/sdk-python
+Author: SiftingIO
+License: MIT
+License-File: LICENSE
+Keywords: api,crypto,edgar,forex,fundamentals,market-data,sdk,sec,sifting,siftingio,stocks,websocket,xbrl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=12
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# siftingio
+
+Official Python SDK for the [SiftingIO](https://sifting.io) market data API — **sync and async** REST clients plus a live WebSocket, fully type-hinted.
+
+- **Sync *and* async.** `SiftingClient` for scripts, notebooks, and pandas; `AsyncSiftingClient` for asyncio services. Same method names, same shapes.
+- **Typed.** Every endpoint, parameter, and response is annotated (`py.typed`); responses are plain dicts with `TypedDict` shapes for editor autocomplete.
+- **Resource-mapped.** Methods mirror the [API docs](https://sifting.io/docs) 1:1.
+- **Batteries included.** Auto-retry on 429/5xx, gzip negotiation, cursor auto-pagination, and an auto-reconnecting WebSocket client.
+
+## Install
+
+```bash
+pip install siftingio
+```
+
+Requires Python 3.9+. Depends only on `httpx` and `websockets`.
+
+## Quick start (sync)
+
+```python
+from siftingio import SiftingClient
+
+client = SiftingClient(api_key="sft_...")  # or env-driven; see below
+
+# Live price
+trade = client.last.trade("crypto", "BTCUSDT")
+print(trade["p"], trade["t"])
+
+# Company fundamentals
+profile = client.stocks.profile("AAPL")
+ratios = client.stocks.ratios("AAPL")
+
+# Historical bars (gzip handled for you)
+bars = client.crypto.bars("BTCUSD", start="2024-01-01", interval="1h")
+print(len(bars["data"]), "bars")
+
+client.close()  # or use `with SiftingClient(...) as client:`
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from siftingio import AsyncSiftingClient
+
+async def main():
+    async with AsyncSiftingClient(api_key="sft_...") as client:
+        quote = await client.last.quote("crypto", "ETHUSDT")
+        print(quote["b"], quote["a"])
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Get an API key from your [SiftingIO dashboard](https://sifting.io). It's sent as the `X-API-Key` header. You can also supply it dynamically (e.g. from a secrets manager or a rotating token):
+
+```python
+client = SiftingClient(get_api_key=lambda: read_secret("SIFTING_API_KEY"))
+
+# Async: the hook may be sync or async
+async_client = AsyncSiftingClient(get_api_key=fetch_token_async)
+```
+
+## Configuration
+
+```python
+SiftingClient(
+    api_key="sft_...",       # X-API-Key header
+    get_api_key=callable,    # dynamic alternative to api_key
+    base_url="https://api.sifting.io",      # override for proxies/staging
+    ws_url="wss://stream.sifting.io/ws/v1", # WebSocket endpoint
+    timeout=30.0,            # per-request timeout (seconds)
+    max_retries=2,           # automatic retries for 429 / 5xx
+    headers={"X-Trace": "…"},# extra headers on every request
+    http_client=httpx.Client(...),  # bring your own httpx client
+)
+```
+
+`AsyncSiftingClient` takes the same arguments (with `httpx.AsyncClient`).
+
+## Resources
+
+| Namespace | Endpoints | Highlights |
+|---|---|---|
+| `client.last` | `/v1/last/*` | `trade`, `quote`, `tvl` — live snapshots |
+| `client.stocks` | `/v1/fnd/stocks/*`, `/v1/hist/stocks/*` | `search`, `profile`, `filings`, `financials`, `ratios`, `insiders`, `events`, `screener`, `bars`, … |
+| `client.filers` | `/v1/fnd/filers/*` | `holdings` — 13F positions |
+| `client.markets` | `/v1/fnd/markets/*` | `list`, `status`, `hours`, `calendar` |
+| `client.forex` | `/v1/hist/forex/*` | `bars` |
+| `client.crypto` | `/v1/hist/crypto/*` | `bars` |
+| `client.dex` | `/v1/fnd/dex/*` | `wallet` portfolios |
+| `client.economic_calendar` | `/v1/fnd/economic-calendar` | `list` |
+
+> Python keyword params that collide with reserved words use a trailing underscore: pass `from_=...` (sent to the API as `from`).
+
+## Pagination
+
+List endpoints return `{"data": [...], "meta": {...}}` with an opaque `meta["next_cursor"]`. Stream every page with `auto_paginate` (sync) or `aauto_paginate` (async):
+
+```python
+from siftingio import auto_paginate, collect_all
+
+for filing in auto_paginate(lambda cursor: client.stocks.filings("AAPL", cursor=cursor, form="10-K")):
+    print(filing["accession"], filing["filed_at"])
+
+insiders = collect_all(lambda cursor: client.stocks.insiders("TSLA", cursor=cursor), max_items=100)
+```
+
+```python
+from siftingio import aauto_paginate
+
+async for filing in aauto_paginate(lambda cursor: client.stocks.filings("AAPL", cursor=cursor)):
+    ...
+```
+
+## Live WebSocket
+
+**Async:**
+
+```python
+async with client.ws() as socket:   # client = AsyncSiftingClient(...)
+    socket.on("tick", lambda t: print(t["s"], t.get("p")))
+    socket.on("error", lambda e: print("server error:", e["code"], e["message"]))
+    await socket.subscribe("cex", ["BTCUSDT", "ETHUSDT"])  # products: cex|dex|fx|us|tvl
+    async for frame in socket:       # or rely purely on handlers
+        ...
+```
+
+**Sync:**
+
+```python
+socket = client.ws()                 # client = SiftingClient(...)
+socket.on("tick", lambda t: print(t["s"], t.get("p")))
+socket.connect()
+socket.subscribe("cex", ["BTCUSDT"])
+for frame in socket.stream():
+    ...
+socket.close()
+```
+
+Subscriptions are tracked and **replayed automatically on reconnect**, so you subscribe once and keep receiving data across drops. In the sync client, handlers run on a background thread.
+
+## Error handling
+
+```python
+from siftingio import SiftingAPIError, SiftingConnectionError
+
+try:
+    client.stocks.profile("NOPE")
+except SiftingAPIError as err:
+    err.status       # 404
+    err.code         # "unknown_ticker"
+    err.retry_after  # seconds, on 429
+    err.request_id   # X-Request-Id — quote this in support tickets
+    err.body         # full parsed error body
+except SiftingConnectionError as err:
+    err.timeout      # True if it was a client-side timeout
+```
+
+The client automatically retries `429` and `5xx` up to `max_retries`, honoring `Retry-After`.
+
+## License
+
+MIT

siftingio-0.1.0/README.md

@@ -0,0 +1,165 @@
+# siftingio
+
+Official Python SDK for the [SiftingIO](https://sifting.io) market data API — **sync and async** REST clients plus a live WebSocket, fully type-hinted.
+
+- **Sync *and* async.** `SiftingClient` for scripts, notebooks, and pandas; `AsyncSiftingClient` for asyncio services. Same method names, same shapes.
+- **Typed.** Every endpoint, parameter, and response is annotated (`py.typed`); responses are plain dicts with `TypedDict` shapes for editor autocomplete.
+- **Resource-mapped.** Methods mirror the [API docs](https://sifting.io/docs) 1:1.
+- **Batteries included.** Auto-retry on 429/5xx, gzip negotiation, cursor auto-pagination, and an auto-reconnecting WebSocket client.
+
+## Install
+
+```bash
+pip install siftingio
+```
+
+Requires Python 3.9+. Depends only on `httpx` and `websockets`.
+
+## Quick start (sync)
+
+```python
+from siftingio import SiftingClient
+
+client = SiftingClient(api_key="sft_...")  # or env-driven; see below
+
+# Live price
+trade = client.last.trade("crypto", "BTCUSDT")
+print(trade["p"], trade["t"])
+
+# Company fundamentals
+profile = client.stocks.profile("AAPL")
+ratios = client.stocks.ratios("AAPL")
+
+# Historical bars (gzip handled for you)
+bars = client.crypto.bars("BTCUSD", start="2024-01-01", interval="1h")
+print(len(bars["data"]), "bars")
+
+client.close()  # or use `with SiftingClient(...) as client:`
+```
+
+## Quick start (async)
+
+```python
+import asyncio
+from siftingio import AsyncSiftingClient
+
+async def main():
+    async with AsyncSiftingClient(api_key="sft_...") as client:
+        quote = await client.last.quote("crypto", "ETHUSDT")
+        print(quote["b"], quote["a"])
+
+asyncio.run(main())
+```
+
+## Authentication
+
+Get an API key from your [SiftingIO dashboard](https://sifting.io). It's sent as the `X-API-Key` header. You can also supply it dynamically (e.g. from a secrets manager or a rotating token):
+
+```python
+client = SiftingClient(get_api_key=lambda: read_secret("SIFTING_API_KEY"))
+
+# Async: the hook may be sync or async
+async_client = AsyncSiftingClient(get_api_key=fetch_token_async)
+```
+
+## Configuration
+
+```python
+SiftingClient(
+    api_key="sft_...",       # X-API-Key header
+    get_api_key=callable,    # dynamic alternative to api_key
+    base_url="https://api.sifting.io",      # override for proxies/staging
+    ws_url="wss://stream.sifting.io/ws/v1", # WebSocket endpoint
+    timeout=30.0,            # per-request timeout (seconds)
+    max_retries=2,           # automatic retries for 429 / 5xx
+    headers={"X-Trace": "…"},# extra headers on every request
+    http_client=httpx.Client(...),  # bring your own httpx client
+)
+```
+
+`AsyncSiftingClient` takes the same arguments (with `httpx.AsyncClient`).
+
+## Resources
+
+| Namespace | Endpoints | Highlights |
+|---|---|---|
+| `client.last` | `/v1/last/*` | `trade`, `quote`, `tvl` — live snapshots |
+| `client.stocks` | `/v1/fnd/stocks/*`, `/v1/hist/stocks/*` | `search`, `profile`, `filings`, `financials`, `ratios`, `insiders`, `events`, `screener`, `bars`, … |
+| `client.filers` | `/v1/fnd/filers/*` | `holdings` — 13F positions |
+| `client.markets` | `/v1/fnd/markets/*` | `list`, `status`, `hours`, `calendar` |
+| `client.forex` | `/v1/hist/forex/*` | `bars` |
+| `client.crypto` | `/v1/hist/crypto/*` | `bars` |
+| `client.dex` | `/v1/fnd/dex/*` | `wallet` portfolios |
+| `client.economic_calendar` | `/v1/fnd/economic-calendar` | `list` |
+
+> Python keyword params that collide with reserved words use a trailing underscore: pass `from_=...` (sent to the API as `from`).
+
+## Pagination
+
+List endpoints return `{"data": [...], "meta": {...}}` with an opaque `meta["next_cursor"]`. Stream every page with `auto_paginate` (sync) or `aauto_paginate` (async):
+
+```python
+from siftingio import auto_paginate, collect_all
+
+for filing in auto_paginate(lambda cursor: client.stocks.filings("AAPL", cursor=cursor, form="10-K")):
+    print(filing["accession"], filing["filed_at"])
+
+insiders = collect_all(lambda cursor: client.stocks.insiders("TSLA", cursor=cursor), max_items=100)
+```
+
+```python
+from siftingio import aauto_paginate
+
+async for filing in aauto_paginate(lambda cursor: client.stocks.filings("AAPL", cursor=cursor)):
+    ...
+```
+
+## Live WebSocket
+
+**Async:**
+
+```python
+async with client.ws() as socket:   # client = AsyncSiftingClient(...)
+    socket.on("tick", lambda t: print(t["s"], t.get("p")))
+    socket.on("error", lambda e: print("server error:", e["code"], e["message"]))
+    await socket.subscribe("cex", ["BTCUSDT", "ETHUSDT"])  # products: cex|dex|fx|us|tvl
+    async for frame in socket:       # or rely purely on handlers
+        ...
+```
+
+**Sync:**
+
+```python
+socket = client.ws()                 # client = SiftingClient(...)
+socket.on("tick", lambda t: print(t["s"], t.get("p")))
+socket.connect()
+socket.subscribe("cex", ["BTCUSDT"])
+for frame in socket.stream():
+    ...
+socket.close()
+```
+
+Subscriptions are tracked and **replayed automatically on reconnect**, so you subscribe once and keep receiving data across drops. In the sync client, handlers run on a background thread.
+
+## Error handling
+
+```python
+from siftingio import SiftingAPIError, SiftingConnectionError
+
+try:
+    client.stocks.profile("NOPE")
+except SiftingAPIError as err:
+    err.status       # 404
+    err.code         # "unknown_ticker"
+    err.retry_after  # seconds, on 429
+    err.request_id   # X-Request-Id — quote this in support tickets
+    err.body         # full parsed error body
+except SiftingConnectionError as err:
+    err.timeout      # True if it was a client-side timeout
+```
+
+The client automatically retries `429` and `5xx` up to `max_retries`, honoring `Retry-After`.
+
+## License
+
+MIT

siftingio-0.1.0/examples/rest.py

@@ -0,0 +1,48 @@
+"""REST quick tour (sync). Run with:  SIFTING_API_KEY=sft_… python examples/rest.py"""
+
+import os
+
+from siftingio import SiftingAPIError, SiftingClient, auto_paginate
+
+
+def main() -> None:
+    with SiftingClient(api_key=os.environ.get("SIFTING_API_KEY")) as client:
+        # 1. Live snapshot
+        trade = client.last.trade("crypto", "BTCUSDT")
+        print("BTC last trade:", trade["p"], "@", trade["t"])
+
+        # 2. Fundamentals
+        profile = client.stocks.profile("AAPL")
+        print(f"{profile['name']} ({profile['ticker']}) — {profile.get('sic_description')}")
+
+        ratios = client.stocks.ratios("AAPL")
+        latest = ratios.get("latest") or {}
+        print("Latest net margin:", latest.get("net_margin"))
+
+        # 3. Historical bars (gzip negotiated automatically)
+        bars = client.crypto.bars("ETHUSD", start="2024-01-01", end="2024-01-02", interval="1h")
+        print(f"Got {len(bars['data'])} ETH bars")
+
+        # 4. Auto-paginated 10-K filings
+        count = 0
+        for filing in auto_paginate(
+            lambda cursor: client.stocks.filings("AAPL", cursor=cursor, form="10-K")
+        ):
+            count += 1
+            if count <= 3:
+                print("10-K:", filing["filed_at"], filing["accession"])
+        print(f"Total 10-Ks: {count}")
+
+        # 5. Markets + economic calendar
+        status = client.markets.status("us_equities")
+        print("US equities open?", status["data"].get("is_open"))
+
+        cal = client.economic_calendar.list(impact="high", limit=5)
+        print(f"{cal['count']} high-impact events upcoming")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SiftingAPIError as err:
+        raise SystemExit(f"API error {err.status} ({err.code}): {err.message}") from err

siftingio-0.1.0/examples/websocket.py

@@ -0,0 +1,47 @@
+"""Live WebSocket tour. Run with:  SIFTING_API_KEY=sft_… python examples/websocket.py
+
+Shows both the async-native client and (commented) the blocking client.
+"""
+
+import asyncio
+import os
+
+from siftingio import AsyncSiftingClient
+
+
+async def main() -> None:
+    client = AsyncSiftingClient(api_key=os.environ.get("SIFTING_API_KEY"))
+    socket = client.ws()
+
+    socket.on("open", lambda _: print("connected"))
+    socket.on("reconnect", lambda info: print("reconnecting, attempt", info["attempt"]))
+    socket.on("error", lambda e: print("server error:", e.get("code"), e.get("message")))
+    socket.on("tick", lambda t: print(f"[{t.get('class', 'tick')}] {t['s']} {t.get('p') or t.get('b')}"))
+    socket.on("tvl", lambda v: print(f"[tvl] {v['s']} ${v['usd']}"))
+
+    await socket.connect()
+    await socket.subscribe("cex", ["BTCUSDT", "ETHUSDT"])
+    await socket.subscribe("tvl", ["eth:WETH-USDC"])
+
+    # Stream for 30 seconds, then close.
+    await asyncio.sleep(30)
+    await socket.close()
+    await client.aclose()
+    print("done")
+
+
+# Blocking equivalent:
+#
+#     from siftingio import SiftingClient
+#     client = SiftingClient(api_key=os.environ["SIFTING_API_KEY"])
+#     socket = client.ws()
+#     socket.on("tick", lambda t: print(t["s"], t.get("p")))
+#     socket.connect()
+#     socket.subscribe("cex", ["BTCUSDT"])
+#     for frame in socket.stream():
+#         ...
+#     socket.close()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())