← tickerbot.io
View as markdown
Endpoints › Websockets

Stream

WSSwss://api.tickerbot.io/v2/stream

Hold a socket open and receive each subscribed ticker's freshly-computed row the moment the minute refresh turns it over.

Server messages

authed
Key accepted. Carries your resolved plan. **Wait for this ack before sending subscribe** — a frame that arrives while auth is still resolving is rejected with auth_required, so sending auth and subscribe back-to-back in onopen races.
subscribed
Acks a subscribe. Returns count (distinct tickers on the account), plus rejected (over cap), invalid (malformed symbols) and dropped_fields when present.
update
One ticker's new row: { ticker, as_of, data }. One per subscribed ticker per minute turnover.
unsubscribed
Acks an unsubscribe frame.
pong
Reply to a ping frame.

Error frames

auth_required
First message was not a valid auth frame and no Bearer header was sent. The socket closes.
auth_timeout
No credential arrived within 10 seconds of connecting. The socket closes (1008).
unauthenticated
Malformed, unknown, or revoked API key.
bad_json
A frame was not valid JSON.
unknown_type
A frame's type is not one of auth/subscribe/unsubscribe/ping.
bad_request
tickers missing or empty, or more than 200 symbols in one subscribe frame.
subscription_limit
You are subscribed to N of M tickers on your plan. Unsubscribe some or upgrade to add more. Over-cap tickers come back in the subscribed ack's rejected list (the error frame arrives before the ack). On Free the cap is 0, and the frame carries plan and upgrade_url.
too_many_connections
Max 5 concurrent stream connections per account, pooled across every API key on the account. An abuse guard, not a plan limit.
connection_closed
The connection was closed server-side while a frame was in flight.
internal
Unexpected server error; the socket closes with 1011.

Notes

  • An update frame carries the same record as GET /v2/tickers/{ticker}. Per-minute during US market hours (4 AM–8 PM ET), equities and ETFs; the feed is quiet when the market is closed.
  • Caps are per ACCOUNT, not per API key. Concurrent distinct tickers are pooled across every live connection your account holds, so issuing additional keys grants no additional capacity, and two connections subscribed to the same symbol cost one slot. Unsubscribing or disconnecting frees slots immediately — it is a live gauge, not a consumption meter. Check current consumption with GET /v2/stream/usage.
  • Authenticate with Authorization: Bearer at the handshake, or send an auth frame as the first message — {type:"auth", api_key}, or {type:"auth", id_token} from a signed-in browser session. Authenticate within 10 seconds or the socket closes with 1008.
  • Client frames: {type:"auth", …}, {type:"subscribe", tickers, fields?}, {type:"unsubscribe", tickers}, {type:"ping"}. A partially-rejected subscribe emits its error frame *before* the subscribed ack it refers to.
  • Subscribe validates symbol *shape* only: an unknown but well-formed symbol acks cleanly, consumes a cap slot, and simply never emits an update. Malformed symbols come back in the ack's invalid list.
  • Keepalive and backpressure: the server pings every 30 seconds and terminates unresponsive peers. A slow consumer with over 4 MB buffered silently loses the rest of that tick's updates; past 16 MB the socket closes with 1013.
  • Close codes: 1008 policy/auth (bad key, auth timeout, connection cap), 1011 internal error, 1013 slow consumer.