Stream

Connecting, subscribing, resuming and keeping up on the traktor.v1 trade stream.

wss://api.traktor.fun/v1/stream delivers origin: "live" trades as Traktor stores them, chosen by a flow filter.

Lifecycle

1. Connect with the subprotocol traktor.v1, and put nothing in the URL: a query parameter named like a credential closes the socket 4015. hello arrives at once, before you authenticate, with the protocol version, the heartbeat and the frame sizes; hello.auth says how many frames you may send before you authenticate, how many bytes each may hold, and how many milliseconds you have.

2. Send auth as your first frame, with your key in key. Authentication must finish within hello.auth.deadlineMs of connecting, the server's check of the key included, or the socket closes 4001; a server full of connections still authenticating can close the oldest from the network holding the most with 4001 sooner, to make room. The ack holds your plan's limits, the chains and apps tracked, and head, the stream's position; read the limits there rather than copying the plans table. A refused key closes the socket instead: 4002, or 4003 for a suspended account. Frames you send after auth and before its ack wait for the key check, and past ten of them each is refused rate_limited, so send your subscriptions once the ack arrives.

3. Send subscribe with a flow filter in filter; left out, the filter's defaults apply. Its other keys are optional: sub, your name for the subscription, which the server picks when you leave it out; delivery, with maxBatch, the most events one frame carries, and maxDelayMs, the longest the server holds an event to fill a frame; and from, to resume. The ack's result.seq is the stream's position when the subscription opened.

4. Trades arrive in events frames. d holds a batch, each element a trade row without tx and leg, which id holds. seq is the position of the batch's last trade, an opaque string: keep the latest for each subscription.

The stream carries only origin: "live" rows: a row Traktor recovers later, with origin sweep or backfill, never reaches it. The same trade can arrive twice, under two seqs, so deduplicate on id. The Quickstart has a client in TypeScript and Python.

Every frame is one JSON object with op and id. Each frame you send gets one answer, which carries the frame's id as re: an ack, an error, or a pong for a ping. Answers come in the order you sent the frames, with one exception: while a replay is being sent or auth's key is being checked, the frames you send wait for it, and one sent while twice your plan's per-second inbound rate of them already wait (during the key check, ten sent after auth) is refused rate_limited at once, ahead of the frames before it. An error for a frame with no readable id has no re, and a fault that closes the socket answers with a bye instead. Ignore a server op you do not know. A field the server does not know is refused, so a typo never widens a filter.

One channel is served, flows; a subscribe that names another answers channel_denied. A chains or platforms name outside the vocabulary answers filter_invalid, with detail.pointer at the key you sent: /filter/chains, or /filter/chain if you spelled it so. Both spellings of one key answer filter_invalid at the plural's pointer, /filter/chains. Either way no subscription opens.

Frames

You send

The server sends

Notice kinds

Ack warnings

A heartbeat arrives every 15 seconds; the socket closes after 45 seconds without a frame from you.

The ack's warnings qualify a subscription as a whole; each event's flags qualify its own row (Flags).

Resume

After a disconnect, subscribe again with from set to the last seq you processed. If the stream has not been rebuilt since, and that seq is younger than the plan's replay window, the span after it replays in order with no gap, each event judged by the filter as it was live, and the ack says resumed: true. Otherwise the ack says resumed: false, and gap.reason says why:

• trimmed: the span is older than the plan's replay window, or than the stream retains.

• epoch_stale: the stream was rebuilt after that seq.

• replay_unavailable: the server could not read the span.

The subscription still opens, and carries on from the ack's seq: the trades in the gap are not sent. A from past the stream's newest event opens nothing: it is refused bad_frame at /from, so subscribe again without it. A plan with no replay window cannot resume: its from answers trimmed, or epoch_stale once the stream has been rebuilt. Each plan's window is in Plans and limits.

A span cut short after the ack arrives as a replay_incomplete notice, with detail.reason and detail.oldestAvailable. The subscription carries on from the ack's seq, and the rest of the span is not sent.

Flow control

Each subscription queues up to 4,096 matching events. When events match faster than your plan's event rate delivers them, or faster than your socket reads, the queue fills and stays full: the oldest are dropped and counted, and each event you do receive has waited about 4,096 ÷ the matches a second, minutes on a wide filter and longer still on one that matches only a little faster than the plan delivers. To stay current, narrow the filter until a heartbeat's queued stays low.

A dropped notice arrives within about a second of a drop, with detail { count, since, reason: "backpressure", policy: "drop_oldest", queued }, and every heartbeat carries each subscription's running total. Dropped events are never billed.

Shedding never closes the socket. 4008 closes one that stops reading: its unread buffer stayed over the server's limit for 30 seconds.

While a subscription's queue is long, the server widens its batching, never narrows it, and says so in a batch_pressure notice whose detail is the batching in force. Your own batching returns, without a notice, once the queue shortens.

Liveness

The silence limit under Frames also counts the pong your client returns to the server's WebSocket ping, which comes at least twice within the limit; most libraries send that pong on their own. If yours does not, send a ping frame more often than the limit. After a 4009, reconnect at once.

Plan changes and revocation

The server checks your key once a minute. A change of plan or billing period arrives as a plan_changed notice, with the plan codes in detail.from and detail.to, and the new limits apply from then. Subscriptions already open stay as they are: a lower cap on subscriptions, allow lists, filter score or connections applies to your next subscribe and your next connection. A key that no longer authenticates, because it was revoked or expired or its account was suspended or closed, closes the socket 4003 at that check; the bye before it names, in detail.code, the code a REST request would get (When a key is refused). Once the month's stream units are spent, the socket closes 4006 (Stream units).

Close codes

Every close the server starts is preceded by a bye, with retryable and the close's detail. 1013, the one close that would not be, is not sent today. When a bye carries retryAfterMs, wait that long before you reconnect. After your own bye, the server sends what is queued, as far as your socket keeps reading, acknowledges it, and closes 1000; what your socket had no room for is not sent, so resume from the last seq you processed.

A frame over 65,536 bytes never reaches the server: the transport drops the connection with no bye and no close frame, and your client sees 1006.

A deploy closes 1001. Its bye carries retryAfterMs, each subscription's resume point in detail.subs[].seq, and detail.lastSeq, the earliest of them. Before that bye the server sends each subscription's queued events, as far as your socket keeps reading, and any pending dropped notice, so a resume point never lies past an event you were neither sent nor told was dropped. Reconnect after retryAfterMs, then resume each subscription with from set to its own resume point, or every one from lastSeq and deduplicate on id; a null resume point means subscribe afresh.

Treat a 4xxx code the table below does not list as not retryable, unless its bye says it is.

Every code an error frame carries is on Errors.