Differences

This shows you the differences between two versions of the page.

--- developers:apiv2:connecting [2026/09/07 13:40] – chad
+++ developers:apiv2:connecting [2026/09/07 21:58] (current) – [WebSocket Connection] chad
@@ Line 7: / Line 7: @@
 Clients must connect using WebSocket Secure (WSS) over SSL/TLS on port 443. Messages are encoded with Google Protocol Buffers.
-^ Environment ^ URL ^
+<WRAP 50%>
-| Live | ''wss://wss.t4login.com/v2'' |
+^ **Environment** ^ **WebSocket URL** ^
-| Simulator | ''wss://wss-sim.t4login.com/v2'' |
+| **Simulator** | %%wss://wss-sim.t4login.com/v2%% |
-| Live (Admin) | ''wss://wssadmin.t4login.com/v2'' |
+| **Simulator (Admin)** | %%wss://wssadmin-sim.t4login.com/v2%% |
-| Simulator (Admin) | ''wss://wssadmin-sim.t4login.com/v2'' |
+| **Live** | %%wss://wss.t4login.com/v2%% |
+| **Live (Admin)** | %%wss://wssadmin.t4login.com/v2%% |
+</WRAP>
 Develop and certify against the Simulator.
-**Framing:** send and receive **binary** frames. Each frame is exactly one serialized ''ClientMessage'' (client → server) or ''ServerMessage'' (server → client). The WebSocket frame is the message boundary — there is no extra length prefix.
-==== Heartbeat ====
-Send a ''Heartbeat'' every **20 seconds**; the server does the same. If the server receives nothing for **3 consecutive heartbeat intervals** it closes the connection.
+==== Heartbeat ====
+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.
 <code>
@@ Line 27: / Line 28: @@
 ===== Authentication =====
+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`).
-The **first** message you send must be a ''LoginRequest'' (wrapped in a ''ClientMessage''). Authenticate with either method:
+**Example LoginRequest (API Key Authentication):**
+<code>
+{
+  "apiKey": "abc123-xyz789"
+}
+</code>
-  * **API key** — set ''api_key'' only.
+**Example LoginRequest (Username/Password Authentication):**
-  * **Username / password** — set ''firm'', ''username'', ''password'', ''app_name'', ''app_license''.
+<code>
+{
+  "firm": "T4Futures",
+  "username": "trader123",
+  "password": "securepassword",
+  "appName": "CustomTradingApp",
+  "appLicense": "LICENSE-4567"
+}
+</code>
-Optionally set ''price_format'' to choose how prices are formatted (see [[developers:apiv2:pricing|Pricing and Data Types]]).
+If authentication succeeds, the server will return a `LoginResponse` with a session ID and assigned roles.
+**Example Successful LoginResponse:**
 <code>
-// ClientMessage
+{
-login_request {
+  "result": "LOGIN_SUCCESS",
-  api_key: "YOUR_API_KEY"
+  "sessionId": "sess-123456789",
-  price_format: PRICE_FORMAT_DECIMAL
+  "userId": "user-456",
+  "firmId": "firm-789",
+  "roles": ["Trader", "RiskManager"]
 }
 </code>
-The server replies with a ''LoginResponse'':
+If authentication fails, the server will return an error message. Some common reasons for failure include:
-  * ''result'' — a ''LoginResult''. Anything other than ''LOGIN_RESULT_SUCCESS'' means login failed; read ''error_message''.
+^ LoginResult Code ^ Meaning ^
-  * ''session_id'', ''user_id'', ''firm_id'', ''roles'' — session identity and permissions.
+| `LOGIN_FAILED` | Invalid credentials. |
-  * ''exchanges'' — the exchanges and market data you are entitled to.
+| `TWO_FACTOR_REQUIRED` | Two-factor authentication is required. |
-  * ''accounts'' — the accounts you can view and trade.
+| `UNAUTHORIZED` | API key or username/password is incorrect. |
-  * ''authentication_token'' (optional) — a short-lived token for T4 REST services.
+| `PASSWORD_EXPIRED` | The password must be changed before logging in. |
+| `LOCKED_OUT` | Too many failed login attempts. |
-Order routing requires the appropriate role. Without it, market-data and account subscriptions still work, but order submissions are rejected.
+For detailed message formats, refer to the [[developers:apiv2:reference|Message Catalog]] page.
-==== Authentication Token ====
-''LoginResponse'' may include an ''authentication_token'', and you can request a fresh one at any time:
-  * Send ''AuthenticationTokenRequest'' with a ''request_id''.
-  * Receive ''AuthenticationToken'' with ''token'' and ''expire_time'' (or ''fail_message'').
-The token authenticates to T4 REST services. It does not resume a dropped WebSocket session — you re-authenticate on reconnect.
 ===== Reconnection & Session Handling =====
+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.
-Sessions are not resumable. On any disconnect:
+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.
-  - Reconnect to the endpoint.
-  - Send ''LoginRequest'' again.
-  - Re-subscribe to markets and accounts, and reconcile order state from the account snapshot.
-**Maintenance:** connections are dropped for scheduled maintenance every week (shutting down at midnight on Friday), resuming Sunday morning. Build automatic reconnect-and-resubscribe into your client.
 ===== Next Steps =====
+Once authenticated, clients can:
+  * Subscribe to **market data streams** ([[quote_data|Quote Data]]).
+  * Retrieve **account and position details** ([[account_data|Account Data]]).
+  * Submit **orders and manage trades** ([[order_submission|Order Submission]]).
-  * [[developers:apiv2:markets|Market Data & Definitions]]
+----
-  * [[developers:apiv2:accounts|Account Feed]]
-  * [[developers:apiv2:orders|Order Routing]]
+💡 **Tip:** Test your WebSocket connection using tools like `wscat` or a sample SDK.