tickerbot.io
Reference

SQL

A screen is one SQL WHERE clause. Scan takes it as q and a webhook as its trigger; events and news take the same grammar to filter their own records.

The grammar

One WHERE clause; its identifiers depend on where you send it.

  • On scan and webhooks: the q on Scan and its subscriptions. Identifiers are signals of any type: booleans you name directly, numerics, strings and dates you compare, object signals you test with @> (leadership @> '[{"name":"John Ternus"}]' matches the tickers whose leadership lists that person), plus the qualified context tickers below.
  • On events: Events and the event webhook's q. Five identifiers: id, ticker, ts, kind and payload, with jsonb operators on payload fields (payload->>'firm' = 'Goldman Sachs'); with one kind named, its payload fields by bare name (firm = 'Goldman Sachs'). With join=state ticker signals are legal too, as of each event's timestamp; an event webhook's q always takes them, at fire time.
  • On news: News. Article columns (time_published, source, sentiment) plus the per-mention fields (ticker, relevance, sentiment_score, sentiment), which give one row per article per mention for per-ticker rollups.

Where it goes

The same clause on every surface that takes one: in the JSON body on scan and webhooks, as a URL-encoded q on events and news.

Scan

curl -X POST "https://api.tickerbot.io/v2/scan" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "above_sma_200 AND market_cap > 1e10"
  }'

Add asof to run the same screen on any past date (As-of).

Webhook

curl -X POST "https://api.tickerbot.io/v2/scan/subscribe" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "gap_up AND market_cap > 1e9",
    "target_url": "https://example.com/hook"
  }'

The webhook fires when a ticker starts matching. Event webhooks take the events grammar in their q.

Events

curl -G "https://api.tickerbot.io/v2/events" \
  -H "Authorization: Bearer YOUR_KEY" \
  --data-urlencode "kind=analyst" \
  --data-urlencode "from=2026-10-06" \
  --data-urlencode "q=payload->>'action' = 'downgrades'"

News

curl "https://api.tickerbot.io/v2/news?ticker=NVDA&q=overall_sentiment_score%20%3C%20-0.2&limit=5" \
  -H "Authorization: Bearer YOUR_KEY"

Example screens has more, each combining two or three kinds of data.

Context tickers

Reference another symbol inside a screen.

Writing spy.price > spy.sma_50 pulls SPY's signals into the same screen: no second call, no client-side join, every clause evaluated at the same instant (under asof too).

What can be a qualifier

Any symbol the catalog returns, spelled as it appears there.

examplewhat it is
spyAn ETF (the S&P 500 proxy). Any ETF works the same way (qqq, iwm, xlk, ...).
nvdaAny equity in the catalog: a bellwether, a peer or a competitor.
r:sofrA rate (R: prefix): SOFR, fed funds, Treasury yields and spreads.
x:btcusdA crypto or FX pair (X: prefix).

Rules

  • A qualifier that is not in the catalog is a 400 unknown_context_ticker naming it, never a raw SQL error or a silent empty result.
  • Symbols with a dot or hyphen in them (BRK.B) cannot be qualifiers: the dot is the separator. Everything else in the catalog can, including prefixed ids (r:sofr, x:btcusd).
  • vix and dxy answer 400 context_ticker_unavailable.
  • There is no cap on refs per screen beyond the 4,000-character limit on q; each ref is one indexed lookup evaluated once per screen, whatever the symbol.
  • Refs inside a custom signal's expr are not rewritten. Keep custom signals single-ticker and put the context ref in q.

Macro-conditioned setup

curl -X POST "https://api.tickerbot.io/v2/scan" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "rsi_oversold AND spy.price > spy.sma_50"
  }'

RSI-oversold names, but only when the S&P 500 is holding above its 50-day average.

Sector-relative breakout

curl -X POST "https://api.tickerbot.io/v2/scan" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "at_20d_high AND sector = '"'"'Technology'"'"' AND change_1d_pct > xlk.change_1d_pct"
  }'

Tech breakouts that are also outpacing the tech sector ETF on the same day.

What's accepted

What works, what we reject and the reads that take something narrower than a WHERE clause.

  • Everything you'd expect works: LIKE/ILIKE, IN, BETWEEN, CASE, computed expressions (price / sma_50 > 1.05), casts to whitelisted types (::numeric, ::date, ::timestamptz, ...) and jsonb containment on an object signal, with the entries to match written as a JSON list (revenue_by_segment @> '[{"name":"Americas"}]'; a value that is not JSON is a 400).
  • No subqueries or joins. A clause filters one record at a time: a ticker's signals on /v2/scan, an event on /v2/events, an article on /v2/news. The one sanctioned join is join=state on /v2/events (a parameter, not SQL you write).
  • No statement composition. UNION / EXCEPT / INTERSECT, WITH, SELECT, any DDL/DML keyword, semicolons and SQL comments (--, /* */) are rejected.
  • Functions are whitelisted: aggregates (count, avg, sum, min, max, string_agg, ...) in select/having, plus scalar helpers (coalesce, round, abs, lower, upper, length, date_trunc, extract, now, cardinality for a string[] signal's length (etf_holders), jsonb_array_length for an object list (leadership), ...). Anything else (window functions included: OVER (...), row_number, rank, lag) is a 400 naming the function.
  • No double-quoted identifiers. Write columns bare (price, not "price"); single quotes are for string literals.
  • Custom-signal expr is stricter still: comparisons, AND/OR/NOT, IN, BETWEEN, IS [NOT] NULL and arithmetic; functions limited to abs/coalesce/round/least/greatest. No LIKE/ILIKE, no CASE, no :: casts. An expression that works in a scan q can still be rejected with compile_failed.

Three reads take other params instead of q: signal matches take condition, one comparator on the named signal (?condition=>70); History and Bars take structured params (select and grain on History, the bar width in the Bars path, from/to); ticker reads are keyed by symbol.