Connecting & Authenticating

◀ WebSocket API (V2)

Connect to a V2 endpoint over WSS (TLS, port 443):

Framing: send and receive binary frames. Each frame is exactly one serialized ClientMessage (out) or ServerMessage (in). There is no extra length prefix — the WebSocket frame is the message boundary.

The first message you send must be a LoginRequest (wrapped in a ClientMessage). Two authentication methods:

• API key — set api_key only. Recommended for automated/API clients.
• Username / password — set firm, username, password, app_name, app_license.

Optionally set price_format to choose how prices are formatted (see Prices & Data Types).

// ClientMessage
login_request {
  api_key: "YOUR_API_KEY"
  price_format: PRICE_FORMAT_DECIMAL
}

The server replies with a LoginResponse:

• result — a LoginResult. Anything other than LOGIN_RESULT_SUCCESS means login failed; read error_message.
• session_id, user_id, firm_id, roles — your session identity and permissions.
• exchanges — the exchanges/market-data you are entitled to.
• accounts — the accounts you can view/trade.
• authentication_token (optional) — a short-lived token (see below).

Roles matter. Order routing requires the appropriate role; without it, market data and account subscriptions still work but order submissions are rejected.

Send a Heartbeat every 20 seconds. The server does the same. If the server receives nothing for 3 heartbeat intervals (~60s) it closes the connection.

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

LoginResponse may include an authentication_token. You can also request a fresh one at any time:

• Send AuthenticationTokenRequest with a request_id.
• Receive AuthenticationToken with token and expire_time (or fail_message).

Use it where a bearer token is needed for T4 REST services. It does not resume a dropped WebSocket session — you still re-authenticate on reconnect.

Sessions are not resumable. On any disconnect:

1. Reconnect to the endpoint.
2. Send LoginRequest again.
3. Re-subscribe to markets and accounts, and reconcile order state from the account snapshot.

Maintenance window: connections are dropped for weekly maintenance (around midnight Friday) and service resumes Sunday morning. Build automatic reconnect-and-resubscribe into your client.