Basics
- Communication uses UDP. Each datagram carries one message of up to 1,200 bytes.
- Messages are encoded with FIX SBE (Simple Binary Encoding), in little-endian byte order (Message format).
- Control (authentication, subscription, Heartbeat) and delivery (
Ticks) use the same port. The Tick server sends ticks to the source (IP address and port) that the client sent from. - Use one UDP socket for everything from authentication to receiving ticks. If the source port changes, the Tick server treats the client as a different subscriber.
- Data from the Tick server is not encrypted.
Steps
- 1HelloStart authentication
Start authentication
- 2ChallengeA 16-byte cookie
A 16-byte cookie
- 3AuthenticateA JWT signed with your API key, with the cookie as nonce
A JWT signed with your API key, with the cookie as nonce
- 4AuthenticateAckYour subscriber token
Your subscriber token
- 5SubscribeThe symbol names you want
The symbol names you want
- 6SubscribeAckA symbol ID for each symbol
A symbol ID for each symbol
- 7TicksSent as ticks arrive
Sent as ticks arrive
- 8HeartbeatEvery second
Every second
- 9HeartbeatAckWhether the subscription is alive
Whether the subscription is alive
- Send
Hello. The Tick server replies with a cookie (16 bytes) inChallenge. The cookie can be used for about 20 to 30 seconds, and only from the same source that sentHello. - Create a JWT with the private key of your API key and send it in
Authenticate. Put the cookie in the JWTnonceas a URL-safe Base64 string without padding (Authentication (JWT)). - If the result in
AuthenticateAckisAccepted, you receive a subscriber token (16 bytes). Put this token in everySubscribeandHeartbeatafter that. - Send the names of the symbols you want in
Subscribe.SubscribeAckreturns a symbol ID for each symbol.Tickscarries symbol IDs, not symbol names. - Once the subscription is set up,
Ticksstart arriving from the next tick on. The latest values at the time you subscribe are not sent, so for a symbol that moves little, you do not know its value until the next tick. - Send
Heartbeatevery second. After 5 seconds without one, the Tick server ends the subscription. - When
subscribedinHeartbeatAckbecomes 0, the subscription has ended (the reason is inendReason). Start over fromHello.
When a reply does not arrive
Over UDP, both requests and replies can be lost. If a reply does not arrive, wait about 0.5 to 1 second and send the same step again.
SubscribeandAuthenticateare safe to resend. If you authenticate again from the same source with the same API key, you get the same subscriber token.- If
Authenticateis rejected withInvalidCookie, the cookie has expired. Start over fromHello. - Each reply carries the
requestIdof its request unchanged. You can use it to match replies to resent requests.
Changing or ending a subscription
Subscribereplaces the subscription with the set of symbols you send (it does not add to it). To add symbols, send the current symbols as well.- One
Subscribecan carry up to 64 symbols. - Sending an empty set ends the subscriber. The IP address slot is freed immediately as well. To receive ticks again, start over from
Hello.
Request rate limits
The Tick server limits the number of requests per source IP address. Hello and Authenticate are each limited to 10 per second. Requests beyond the limit get a rejection (RateLimited) or no reply at all. Do not keep sending at short intervals.
Why a subscription ends
A subscription ends in the following cases. You can tell the reason from endReason in HeartbeatAck (Result codes).
Heartbeatstopped for 5 seconds- You sent an empty
Subscribe - You reissued your API key, or the contract period ended
- The same source authenticated again with another API key
- The Tick server restarted
In every case, once the cause is resolved, you can receive ticks again by starting over from Hello.