Skip to content
QuantLabTickDirect

DocsProtocol

Connection flow

The steps from authentication to receiving ticks, and what to do when a reply does not arrive.

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

ClientTick server
Authenticate
  1. 1Hello

    Start authentication

  2. 2Challenge

    A 16-byte cookie

  3. 3Authenticate

    A JWT signed with your API key, with the cookie as nonce

  4. 4AuthenticateAck

    Your subscriber token

Subscribe
  1. 5Subscribe

    The symbol names you want

  2. 6SubscribeAck

    A symbol ID for each symbol

Receive
  1. 7Ticks

    Sent as ticks arrive

  2. 8Heartbeat

    Every second

  3. 9HeartbeatAck

    Whether the subscription is alive

  1. Send Hello. The Tick server replies with a cookie (16 bytes) in Challenge. The cookie can be used for about 20 to 30 seconds, and only from the same source that sent Hello.
  2. Create a JWT with the private key of your API key and send it in Authenticate. Put the cookie in the JWT nonce as a URL-safe Base64 string without padding (Authentication (JWT)).
  3. If the result in AuthenticateAck is Accepted, you receive a subscriber token (16 bytes). Put this token in every Subscribe and Heartbeat after that.
  4. Send the names of the symbols you want in Subscribe. SubscribeAck returns a symbol ID for each symbol. Ticks carries symbol IDs, not symbol names.
  5. Once the subscription is set up, Ticks start 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.
  6. Send Heartbeat every second. After 5 seconds without one, the Tick server ends the subscription.
  7. When subscribed in HeartbeatAck becomes 0, the subscription has ended (the reason is in endReason). Start over from Hello.

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.

  • Subscribe and Authenticate are safe to resend. If you authenticate again from the same source with the same API key, you get the same subscriber token.
  • If Authenticate is rejected with InvalidCookie, the cookie has expired. Start over from Hello.
  • Each reply carries the requestId of its request unchanged. You can use it to match replies to resent requests.

Changing or ending a subscription

  • Subscribe replaces 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 Subscribe can 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).

  • Heartbeat stopped 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.