View as markdown
Endpoints · Tickers

Subscribe to a ticker

POSThttps://api.tickerbot.io/v2/tickers/{ticker}/subscribe

Push one ticker: we POST your endpoint whenever it matches the condition you give.

Body parameters

stringrequired

Case-insensitive. Equities are bare symbols (AAPL); every other class carries a prefix — rates (R:SOFR), crypto (X:BTCUSD), fx (X:EURUSD). Bare BTC/ETH are US-listed ETFs, not spot crypto. See Asset symbols.

stringrequired

WHERE-clause fragment using signal/column names from the schema — the same grammar as /v2/scan. (condition accepted as an alias.) See the schema for columns + flags you can compose.

string

Original name for q — accepted as well. The same WHERE-clause fragment; send either spelling.

string

https:// URL to POST when the condition fires. Omit for in-app delivery (visible in the dashboard).

enum

Delivery channel. webhook (POST to target_url), discord (post an embed to discord_url), in_app (dashboard only), or mobile_push (notify a phone signed in to the Tickerbot mobile app; requires a device_id from POST /v2/devices/register). Inferred when omitted: webhook if target_url is set, discord if discord_url is set, else in_app. slack is reserved and returns 501. See the Delivery channels guide.

webhookPOST the payload to an HTTPS endpoint you own, signed with X-Tickerbot-Signature.
discordPost to a Discord channel via its webhook URL. Delivered as a Discord embed, never HMAC-signed — the URL is itself the credential.
in_appDeliver to the in-app feed. No external receiver, so nothing to validate and no test_url.
mobile_pushPush to a registered device. Requires a device_id from Register a device.
string

Discord incoming-webhook URL (https://discord.com/api/webhooks/…). Required when channel is discord. Stored as a posting credential: the create response echoes it back under channel_config, but every later read (list, get, deliveries) strips it and sets channel_config_present: true instead.

string

Device to notify, from POST /v2/devices/register. Required when channel is mobile_push; unknown ids are a 404 device_not_found.

enum

How often to evaluate. realtime (the default) is evaluated on every data refresh (~1×/min); hourly and nyse_open throttle to a batch schedule. 1m is a deprecated alias for realtime.

realtimeEvaluate on every refresh — the canonical value. (1m is a deprecated alias that collapses to this.)
hourlyBatch schedule: evaluate once an hour.
nyse_openBatch schedule: evaluate once per session, at the NYSE open.
string

Human-readable label (up to 80 chars). Defaults to <TICKER>: <query>.

string[]

Comma-separated extra columns to include in each fired payload match row, beyond the standard set (ticker, name, asset_type, price, day_change_pct, market_cap). Each must be a real column; an unknown column is rejected at creation. fields accepted as an alias — and note the RESPONSE reports them under fields, as an array.

stringdefault market_cap

Column the fired payload's match lists are sorted by before the 100-row cap is applied, so a truncated list is the deterministic top 100 rather than an arbitrary sample. Must be a real column (validated at creation).

enumdefault desc

Sort direction for order.

ascAscending — smallest or earliest first.
descdefaultDescending — largest or most recent first.

Headers

string

Optional unique string (≤255 chars). A retry carrying the same key within 24h replays the original response (Idempotency-Replayed: true header) instead of creating a duplicate; a concurrent duplicate gets 409 idempotency_in_flight; reusing a key for a *different* request (another method or path) gets 422 idempotency_key_reused. 5xx responses are not stored — those retries re-execute.

Status codes

201
Webhook subscription created — the same shape as GET /v2/webhooks/{id}, plus test_url and, uniquely on create, signing_secret (shown once, for HMAC verification) and the raw channel_config you supplied. Later reads strip both.
400
bad_request — missing q, invalid ticker, or malformed target_url.
403
webhook_tier_required or webhook_limit_reached.
404
not_found — ticker is not tracked; device_not_found — unknown device_id.
409
idempotency_in_flight — a concurrent request carried the same Idempotency-Key.
422
idempotency_key_reused — the Idempotency-Key was already used for a different request.
501
channel_not_implemented — channel: "slack" is reserved.

Notes

  • Shorthand for POST /v2/webhooks with a { type: "ticker" } trigger — one of the four doors to the same webhook object, listed, updated, and deleted at /v2/webhooks. It counts against your account-wide webhook cap.
  • The predicate is scoped to the path ticker automatically, so do not add ticker = '…' yourself. (condition, the original name, is still accepted.)
  • Returns the same shape as GET /v2/webhooks/{id}, plus a test_url for wire-delivered channels (webhook, discord). Subscribing does NOT auto-fire anything at your endpoint — hit the test URL to send a real-shape webhook.fired and validate your receiver. In-app subscriptions have no external receiver and carry no test_url.
  • Custom signals referenced in the predicate are expanded and frozen into the webhook at creation. Editing the signal later does not change this subscription — re-subscribe to apply.

More examples

Deliver to Discord instead of an HTTPS endpoint
curl -X POST "https://api.tickerbot.io/v2/tickers/NVDA/subscribe" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"rsi_oversold AND high_volume_alert","channel":"discord","discord_url":"https://discord.com/api/webhooks/123456789012345678/aBcDeF…","cadence":"realtime"}'
Response
{
  "as_of": "2026-07-27T16:41:00.000Z",
  "id": "wh_dC9rTq-k77p",
  "name": "NVDA: rsi_oversold AND high_volume_alert",
  "q": "ticker = 'NVDA' AND (rsi_oversold AND high_volume_alert)",
  "cadence": "realtime",
  "target_url": null,
  "channel": "discord",
  "delivery": "discord",
  "channel_config": {
    "url": "https://discord.com/api/webhooks/123456789012345678/aBcDeF…"
  },
  "signing_secret": "whsec_…",
  "status": "active",
  "subscription_origin": {
    "type": "ticker",
    "ref": "NVDA",
    "condition": "rsi_oversold AND high_volume_alert"
  },
  "test_url": "/v2/webhooks/wh_dC9rTq-k77p/test",
  "created_at": 1785170460
}