- Level 1, required: accept a connection and send records.
- Level 2, optional: answer history requests. They fill the platform’s record buffer on a cold start, close the hole a reconnect leaves, and are how a run launched from a date, or over a date window, gets that range.
Transports
The URL scheme in the source descriptor selects the transport:- WebSocket (
wss://). The connection itself is the subscription. The platform sends no greeting; the only frame it can ever send is a replay request (level 2). - SSE (
https://). A GET request withAccept: text/event-stream; the response body is the stream.
ws:// and http:// are rejected), a valid certificate, and a publicly
reachable address — private and internal networks are refused. Credentials cannot be embedded in the URL
(wss://user:pass@... is rejected); to restrict access, use a signed token in the query string. On ordinary
connections the URL is used unchanged. A connection that carries a replay request (level 2) re-assembles the
query to add the replay_* parameters, which can reorder your parameters and normalize their encoding — so sign
parameter values, not the raw query string, and do not use query parameter names starting with replay_ for your
own purposes.
The platform reads your HTTP answer on the SSE response and on the WebSocket handshake. A 404 or 410 means the
stream is gone for good: subscribed indicators stop with external_feed_gone. A 401 or 403 means unauthorized:
they stop with external_feed_auth_failed. A 429 makes the platform back off and retry. Any other failure is
retried with increasing delays and never reaches the indicator as an error.
Records
Over WebSocket, every frame is a JSON object with atype field. Frames without type, and types other than the
ones below, are ignored.
One record (WebSocket)
timeis the record’s timestamp: Unix seconds, UTC. A fractional part is allowed.dataholds the record fields as one flat object. Names match the dataclass schema declared in the script, and a field of a nested dataclass uses a dotted name, exactly like a CSV column:"data": {"signal": 0.42, "risk.beta": 1.1}. A record that does not match the schema — an unknown field, a missing non-optional field, a nested object, a wrong value type — is dropped at intake, and the stream continues. An optional field may be absent ornull.- An optional
idfield is read only for the platform’s diagnostics. When present, it must be a JSON string; any other type makes the whole record undecodable, and it is dropped.
{"type": "heartbeat"}resets the silence clock and does nothing else. Send heartbeats when the gaps between records can exceed thestale_afteryour consumers declare.{"type": "error", "code": "...", "message": "..."}refuses the stream. On a live connection the platform stops serving this feed and subscribed indicators fail withexternal_feed_gone; use it when you want the platform to stop trying — for example, for a stream that no longer exists. On a short window connection (level 2) it only ends that window request.
data:, without the type wrapper:
One record (SSE)
- The blank line after each event is required: it terminates the event.
- Comment lines (starting with
:) count as heartbeats. - The
id:andretry:fields are ignored. Theevent:field is ignored too, with one exception:event: replay_done(level 2, below).
Two rules about timestamps
The platform orders, resumes and deduplicates the stream by the record timestamp, so two rules are hard requirements:- Time does not decrease. Each record’s
timeis equal to or later than the previous one. A record older than the previous one is dropped. - An equal timestamp is a revision. A record with the same
timeas the previous one replaces it. It is treated as a new version of the same logical record, not as a separate event.
Answering history requests (level 2)
The platform asks for recent past in exactly three ways. A feed that ignores them is a valid level-1 feed: everything works, indicators just get less history. The one hard compatibility rule: never close the connection because of an unfamiliar frame or query parameter.
A connection that carries none of them is a plain live subscription: send live records right away.
Timestamps are integer Unix seconds, UTC.
from_time is inclusive, to_time is exclusive. After the done frame
of a request with to_time, either side may close the connection.
Over WebSocket, a request is the one frame the platform sends right after connecting — without a request it sends
nothing:
Requests (WebSocket)
Requests (SSE)
The done frame
Finish every answer with a done frame that repeats the request it answers: the same parameters, with the same values, as integers, without thereplay_ prefix. Leave out the parameters that were not sent.
End of an answer (WebSocket)
End of an answer (SSE)
A date window, start to finish
Rules around the answer
- Send what you have; nothing is a valid answer. With nothing to send, send the done frame right away.
- A done-framed answer is final — an empty answer with a done frame means you hold no records in that range, and the platform does not substitute its own buffer. Without a done frame, the records that arrived are used as they are; for a window the platform falls back to its buffer only when nothing usable arrived at all.
- The done frame is a signal, not a guarantee: the platform also ends the answer on its own silence timeout, overall deadline and size caps.
- Records outside the requested bounds are dropped by the platform. Send no more than
countrecords: the platform keeps the newestcountof what it read, but it stops reading at the record limit below, so a long oversend leaves it with the oldest ones. countis never more than the replay record limit below: a larger history is asked for as that limit.
What your server actually sees
The platform turns user launches into a small set of requests, and the users themselves are invisible to you:- The first connection the platform opens to your feed asks for the last records before the present moment, as many as its record buffer holds. They fill the buffer, which then serves live subscribers without asking you again. When you finish that answer with the done frame, the platform closes the connection and opens the live one from the last record it got — a live-from-a-point request — so nothing you published in between is lost. Finish that one with the done frame too: without it the platform cannot tell whether anything was missed in between, and reports a gap to every subscriber. A feed that ignores the first request and just streams live keeps that first connection as its live one.
- A reconnect after a dropped live connection asks for live from the last record the platform received. Answer it, and the outage leaves no hole.
- A launch from a date arrives as a separate short connection asking for a window, where
to_timeis the present moment. - A run over a date window arrives the same way, carrying the user’s own two dates.
- A trading strategy’s live run asks for the last records before the moment it starts, on a short connection.
- A launch by history depth is served from the platform’s buffer and never reaches your server.
One connection, one answer (pseudocode)