Walleye docs

A medallion pipeline over live option flow

Four tiers, declared once, driven by the node. Nothing here calls refresh.

bronze   a worker fetches the flow on a clock and writes what arrived
silver   a JavaScript worker turns those strings into numbers and writes
         one sentence describing each print
gold     every print is labelled: direction, conviction, urgency, and how
         sure the model is about each
desk     the few worth interrupting somebody for, posted to an endpoint

Running it

export UNUSUAL_WHALES_API_KEY=...     # the node holds this; no worker sees it
export TYPESAFE_API_KEY=...           # the labelling model
export WALLEYE_TOKEN=flow-demo-token-000
export WALLEYE_WORKER_FETCH_ALLOW=unusualwhales.com

walleye-node &                        # WALLEYE_ROOT_URI, WALLEYE_DIR as usual
./pipeline.sh

Nothing outside the node fetches anything. The script posts four view definitions and stops.

What each tier is

bronze is a worker with no source. A view with no source runs on a clock rather than on arriving rows, and this one goes and gets its own:

export default (rows, ctx) => {
  const answer = ctx.call({
    url: 'https://api.unusualwhales.com/api/option-trades/flow-alerts?limit=100',
    headers: { Authorization: 'Bearer {{env:UNUSUAL_WHALES_API_KEY}}',
               Accept: 'application/json' }
  });
  if (answer.status !== 200) throw new Error('unusual whales said ' + answer.status);
  return JSON.parse(answer.body).data.map((a) => ({ /* ...as it arrived... */ }));
}

Two things about that call. The host only permits a host named in WALLEYE_WORKER_FETCH_ALLOW, and the default is none, so reaching out is a decision somebody made rather than something a worker can assume. And {{env:...}} is filled in by the node at the moment of the call, so the key is not in the worker, not in the stored view definition, and not in anything a query can read.

Premium, strike and ratios stay as text because that is how the provider sends them. Bronze is supposed to be what actually arrived. It is keyed on the provider’s own alert id, so polling the same window twice writes nothing the second time.

silver is a worker. Converting a dozen string fields to numbers and composing a sentence is the kind of work that is tedious in SQL and ordinary in JavaScript:

export default (rows) => rows.map((r) => {
  const premium = Number(r.premium);
  const side = Number(r.ask_side_premium) > Number(r.bid_side_premium) ? 'ask' : 'bid';
  return {
    ticker: r.ticker, kind: r.kind, strike: r.strike, premium, side,
    summary: `${r.ticker} ${r.kind} $${r.strike} expiring ${r.expiry}: ` +
             `$${Math.round(premium).toLocaleString('en-US')} of premium, ` +
             `filled on the ${side} side, ...`
  };
});

gold labels each print with one call. The service answers every question about a row in parallel, so asking three things costs about what asking one costs. Asking them as three separate function calls would cost three times as much, which is why this uses decide:

SELECT ticker, premium, summary,
       d['stance']['label']      AS stance,
       d['stance']['confidence'] AS stance_sure,
       d['conviction']['label']  AS conviction,
       d['urgent']['value']      AS urgency
  FROM (SELECT ticker, premium, summary, decide(summary, '<question set>') AS d
          FROM silver_flow)

desk writes nothing. It filters on confidence and posts what is left:

{"source": "gold_labelled",
 "sql": "SELECT ... FROM gold_labelled WHERE stance_sure >= 0.7 AND urgency >= 0.5 AND premium >= 500000",
 "alert": {"url": "https://example.test/desk"}}

What came out

From one hundred live prints:

stanceconvictionprints
bullishnotable29
bearishaggressive22
bearishnotable22
neutralnotable14
bullishaggressive12
bullishroutine1

Three cleared the desk threshold and were delivered:

{"ticker":"SPX","stance":"bullish","conviction":"notable","premium":525600,
 "summary":"SPX put $7450 expiring 2026-09-18: $525,600 of premium, filled on the bid side, ..."}
{"ticker":"SPY","stance":"bearish","conviction":"aggressive","premium":604420,
 "summary":"SPY put $716 expiring 2026-10-16: $604,420 of premium, filled on the ask side, volume is 6.81 of open interest, ..."}
{"ticker":"IWM","stance":"bearish","conviction":"notable","premium":882504,
 "summary":"IWM put $275 expiring 2026-09-30: $882,504 of premium, filled on the ask side, ..."}

A put sold on the bid came back bullish and a put bought on the ask came back bearish, which is the right way round. Index spreads came back neutral with low confidence, which is also right: they are genuinely ambiguous, and the confidence says so rather than guessing.

Things worth knowing

Each tier keeps a cursor, so a second run only processes what arrived since. Delivery happens before the cursor moves, so an endpoint that was down is offered the same rows again rather than never.

Labelling costs one call per row. That is why it happens here, once, where the row is written, and not in the query somebody runs later.