Connecting and Authenticating

◀ WebSocket API (V2)

Clients must connect using WebSocket Secure (WSS) over SSL/TLS on port 443. Messages are encoded with Google Protocol Buffers.

Develop and certify against the Simulator.

To maintain an active connection, both the client and server must send a heartbeat message every 20 seconds. If no other message is sent during that interval, the server will send a heartbeat automatically. If the server does not receive any message for 3 consecutive heartbeat intervals, it will terminate the connection.

// ClientMessage
heartbeat { timestamp: 1725600000000 }   // UTC epoch milliseconds

Authentication must be performed immediately after establishing a connection by sending a `LoginRequest` message. This API supports two authentication methods: - API Key Authentication (provide only the `apikey` field). - Username/Password Authentication (send `firm`, `username`, `password`, `appName`, and `appLicense`).

Example LoginRequest (API Key Authentication):

{
  "apiKey": "abc123-xyz789"
}

Example LoginRequest (Username/Password Authentication):

{
  "firm": "T4Futures",
  "username": "trader123",
  "password": "securepassword",
  "appName": "CustomTradingApp",
  "appLicense": "LICENSE-4567"
}

If authentication succeeds, the server will return a `LoginResponse` with a session ID and assigned roles.

Example Successful LoginResponse:

{
  "result": "LOGIN_SUCCESS",
  "sessionId": "sess-123456789",
  "userId": "user-456",
  "firmId": "firm-789",
  "roles": ["Trader", "RiskManager"]
}

If authentication fails, the server will return an error message. Some common reasons for failure include:

For detailed message formats, refer to the Message Catalog page.

If the connection is lost, clients should reconnect automatically and re-authenticate as session resumption is not supported. Connections remain valid as long as heartbeats are exchanged.

The system undergoes scheduled maintenance every week, shutting down at midnight on Friday and resuming service on Sunday morning. During this period, all connections will be dropped.

Once authenticated, clients can:

• Subscribe to market data streams (Quote Data).
• Retrieve account and position details (Account Data).
• Submit orders and manage trades (Order Submission).

💡 Tip: Test your WebSocket connection using tools like `wscat` or a sample SDK.