CortanaROI Brain

UW API Examples repo (catalog of 12 reference implementations)

6 min read

UW API Examples repo

Twelve official UW reference implementations covering REST polling, WebSocket streaming, Kafka consumption, and Jupyter-notebook analysis

  • visualization. Filed as reference code for the MK3 backend adapter (Codex handoff) AND for the eventual UI / analytics layer.

The websocket-specific architectural lessons are extracted into uw-websocket-client-patterns. This page is the catalog index.

1. Repo layout

api-examples/
├── README.md
└── examples/
    ├── earnings-with-known-institutional-holdings/    (notebook)
    ├── flow-alerts-multiple-tickers/                  (notebook)
    ├── interval-flow-example/                         (Python REST)
    ├── kafka-stream-flow-alerts/                      (Python Kafka)
    ├── market-tide/                                   (notebook)
    ├── net-prem-ticks-dashboard/                      (notebook)
    ├── replicate-top-net-impact-chart/                (notebook)
    ├── spot-greek-exposure-by-strike/                 (Python REST polling)
    ├── ws-multi-channel-multi-output/                 (Python WS)
    ├── ws-multi-channel-multi-output-nodejs/          (Node.js WS)
    ├── ws-stream-flow-alerts-to-sqlite/               (Python WS -> SQLite)
    └── ws-stream-spot-greeks-by-strike-by-expiry/     (Python WS -> DuckDB)

12 examples, four implementation classes (REST polling, WS streaming, Kafka consumption, notebook analytics).

2. The streaming examples (L1 substrate)

2.1 ws-multi-channel-multi-output (Python)

Foundational reference. Five channels (option_trades:TSLA, gex:SPY, gex:QQQ, gex:IWM, flow-alerts). Writes timestamped .txt files per channel. 1-second flush interval. 5-attempt reconnect with exponential backoff + jitter.

MK3 relevance: the protocol skeleton. See uw-websocket-client-patterns for the full architectural breakdown.

2.2 ws-multi-channel-multi-output-nodejs (Node.js)

Same functionality in JavaScript. Confirms the WS protocol is identical across languages. EventEmitter-based architecture. Useful if MK3 ever ships a JS front-end that needs direct WS access (it shouldn’t - the Python backend should mediate).

2.3 ws-stream-flow-alerts-to-sqlite (Python)

WS → SQLite. Demonstrates the persistence pattern for a single channel (flow-alerts). 1-second flush from buffer to DB. Sample DB shipped with the example - useful for understanding the flow-alert record shape end-to-end.

MK3 relevance: the simplest “WS to durable store” template. For MK3, replace SQLite with Postgres (already provisioned) + Parquet shards.

2.4 ws-stream-spot-greeks-by-strike-by-expiry (Python)

WS → DuckDB. Demonstrates the dual-trigger flush pattern with explicit BATCH_SIZE=500 and BATCH_TIMEOUT=10s constants. PyArrow intermediate (pa.Table.from_pylist(buffer)).

MK3 relevance: the load-bearing batching template. The DuckDB choice is interesting - good for embedded analytics but a Parquet target may be simpler at MK3 scale.

2.5 kafka-stream-flow-alerts (Python)

The most strategically important example. UW also publishes Kafka topics at stream.unusualwhales.com:9095 with protobuf payloads. Topics: option-states, all-trade-report, all-option-trades, flow-alerts.

Why Kafka may winDetail
BackpressureNative broker-side buffering vs WS drop-on-slow
ReplayTopic retention allows backfill from offset
Multi-workerConsumer groups for distributed processing
EncodingProtobuf compact + schema-evolution friendly
AuthSASL_SSL (Dan@UW provisions)

MK3 relevance: explore Kafka access during the WS adapter session. If UW grants creds, prefer Kafka over WS for the IMPULSE recorder. The WS adapter is still needed for low-volume channels (news, trading-halts) where Kafka may not be offered.

3. The REST polling examples (L1 fallback)

3.1 interval-flow-example (Python)

Codified from a UW YouTube walkthrough. Custom interval flow alerts. uv-based pyproject.

MK3 relevance: secondary - WS is the preferred path for live flow. Useful if the custom-alert WS channel doesn’t expose the same filter set.

3.2 spot-greek-exposure-by-strike (Python)

REST polling at 1-minute cadence. Multi-ticker (SPXW, SPY, AAPL, TSLA). Writes to SQLite. Demonstrates that the same data exists in both REST and WS surfaces - choice is cadence-based, not data-based.

In the example, 40 minutes of polling 4 tickers yielded 48792 records in SQLite. At-scale extrapolation: hundreds of MB/day per ticker if all strikes captured.

MK3 relevance: the REST polling fallback when WS isn’t available for a specific cut (or when polling intervals > 1m are acceptable).

4. The notebook examples (UI / analytics fodder)

These are the highest-value references for the future MK3 UI / dashboard layer.

4.1 market-tide (Jupyter)

Pulls market tide + OHLC. Plots both. Uses lets-plot for visualization (Kotlin’s plotting library Python bindings; ggplot-like grammar). Output: .png files in lets-plot-images/.

UI relevance: straight template for “market regime panel” in the MK3 dashboard. Market tide is user-flagged-important per cortana-north-star - a live version of this panel is a top-priority UI element.

4.2 net-prem-ticks-dashboard (Jupyter)

Multi-ticker dashboard construction. Pulls net premium ticks + OHLC for multiple tickers, composes a multi-panel dashboard with lets-plot. Loops through ticker lists.

UI relevance: the closest reference to “the SPY hunter intraday dashboard.” Per-ticker net premium tick stream overlaid on price candles = the canonical 0DTE trader’s view. For MK3 UI rebuild, this notebook is the architectural starting point.

4.3 replicate-top-net-impact-chart (Jupyter)

Uses the Stock Screener endpoint (uw-api-screener) to collect data and replicate UW’s own “top net impact” web chart. Top bullish

  • top bearish bar chart by net premium.

UI relevance: demonstrates how to recreate UW’s web dashboards in your own UI using only the API. If MK3 needs to replicate UW’s “market overview” page, this is the template.

4.4 flow-alerts-multiple-tickers (Jupyter)

Filters flow-alerts endpoint. Adds detail and removes less-interesting trades. Built live on YouTube (https://www.youtube.com/watch?v=pzLo5NqyEQo).

UI relevance: filtering / sorting / annotation of flow alerts in a tabular UI. Useful template for the “alerts feed” panel of the MK3 dashboard.

4.5 earnings-with-known-institutional-holdings (Jupyter)

Cross-references upcoming earnings with institutional holdings. L3 fodder per cortana-north-star (institutional data is quarterly). Filed for L3 future strategy work.

MK3 relevance: not in scope for L1 SPY hunter. Useful template when L3 is built.

5. Tech stack lessons (for MK3 UI / Codex handoff)

ConcernTech in examplesMK3 fit
WS client (Python)websockets libraryUse as-is
WS client (Node.js)ws librarySkip - backend mediates
Kafka clientconfluent_kafka (Confluent C bindings)Prefer if creds granted
Protobufgoogle.protobuf with generated *_pb2.pyRequired if Kafka
Local DBSQLite OR DuckDBPrefer Postgres (provisioned) + Parquet shards
Notebook plottinglets-plot (Kotlin/JVM Python bindings)Reasonable for MK3 dashboard prototype
Env mgmt.env + python-dotenvUse as-is
JSONstdlib json (examples use it; skills page recommends orjson)Use orjson per skills guidance
Async I/Oasyncio + aiofilesUse as-is
Logginglogging.handlers.RotatingFileHandlerUse as-is
Web charts(none in examples)TBD for MK3 web UI (Plotly? Streamlit? D3?)

lets-plot is an interesting choice - it’s the JVM/Kotlin ggplot2 port with Python bindings. Less common than Plotly / Matplotlib in Python ecosystems but produces publication-quality output. For MK3 dashboard prototyping this is a viable choice since UW’s own examples use it. For production web UI, evaluate alongside Plotly Dash or Streamlit.

6. Map: examples to MK3 work streams

MK3 workExamples to reference
WS / Kafka adapter (Codex session)ws-multi-channel-multi-output, ws-stream-flow-alerts-to-sqlite, ws-stream-spot-greeks-by-strike-by-expiry, kafka-stream-flow-alerts
IMPULSE Parquet recording pipelinews-stream-spot-greeks-by-strike-by-expiry (DuckDB swap to Parquet)
REST polling fallback for low-frequency cutsspot-greek-exposure-by-strike, interval-flow-example
Backtest / postmortem notebooksmarket-tide, flow-alerts-multiple-tickers, replicate-top-net-impact-chart
Live SPY hunter dashboard (future UI)net-prem-ticks-dashboard (closest single template), market-tide (regime panel)
L3 strategy researchearnings-with-known-institutional-holdings

7. Notable repo-wide patterns

  • All Python examples use .env + python-dotenv for token management. Never hardcoded. Production MK3 follows the same pattern (already in CLAUDE.md guidance).
  • All streaming examples use rotating log handlers with 5MB files, 5 backups. Reasonable default for MK3.
  • All persistence examples use embedded DB. SQLite + DuckDB. MK3 should use Postgres (already provisioned) + Parquet for the archive corpus.
  • No example uses Nautilus. UW examples are stand-alone. Integration into Nautilus’s LiveDataClient is on MK3 to design.
  • Two examples ship sample DBs (spot_greek_exposure_by_strike.db, flow_alerts.db). Useful for schema inspection without running the code: sqlite3 <file> then .schema.

8. Source

  • Repo: https://github.com/unusual-whales/api-examples
  • Cloned locally to /tmp/uw-api-examples for cross-reference during this filing pass.

cortana-north-star uw-api-websockets uw-websocket-client-patterns uw-api-option-trade uw-api-gex-greeks uw-api-tide uw-api-screener 2026-05-15-mk3-setup-hunter-architecture 2026-05-15-mk3-data-foundation-constraint nautilus-dev-adapters

Graph View

Backlinks