Differences

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

--- developers:apiv2:connecting [2026/09/07 13:36] – created chad
+++ developers:apiv2:connecting [2026/09/07 21:58] (current) – [WebSocket Connection] chad
@@ Line 1: / Line 1: @@
-====== Connecting & Authenticating ======
+====== Connecting and Authenticating ======
 [[developers:apiv2|◀ WebSocket API (V2)]]
-===== 1. Open the socket =====
+===== WebSocket Connection =====
-Connect to a [[developers:apiv2|V2 endpoint]] over WSS (TLS, port 443):
+Clients must connect using WebSocket Secure (WSS) over SSL/TLS on port 443. Messages are encoded with Google Protocol Buffers.
-^ Environment ^ URL ^
+<WRAP 50%>
-| Simulator | ''wss://wss-sim.t4login.com/v2'' |
+^ **Environment** ^ **WebSocket URL** ^
-| Live | ''wss://wss.t4login.com/v2'' |
+| **Simulator** | %%wss://wss-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>
-**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.
+Develop and certify against the Simulator.
-===== 2. Log in =====
-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.
+==== Heartbeat ====
-  * **Username / password** — set ''firm'', ''username'', ''password'', ''app_name'', ''app_license''.
+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.
-Optionally set ''price_format'' to choose how prices are formatted (see [[developers:apiv2:pricing|Prices & Data Types]]).
 <code>
 // ClientMessage
-login_request {
+heartbeat { timestamp: 1725600000000 }   // UTC epoch milliseconds
-  api_key: "YOUR_API_KEY"
-  price_format: PRICE_FORMAT_DECIMAL
-}
 </code>
-The server replies with a ''LoginResponse'':
+===== 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`).
-  * ''result'' — a ''LoginResult''. Anything other than ''LOGIN_RESULT_SUCCESS'' means login failed; read ''error_message''.
+**Example LoginRequest (API Key Authentication):**
-  * ''session_id'', ''user_id'', ''firm_id'', ''roles'' — your session identity and permissions.
+<code>
-  * ''exchanges'' — the exchanges/market-data you are entitled to.
+{
-  * ''accounts'' — the accounts you can view/trade.
+  "apiKey": "abc123-xyz789"
-  * ''authentication_token'' (optional) — a short-lived token (see below).
+}
+</code>
-**Roles matter.** Order routing requires the appropriate role; without it, market data and account subscriptions still work but order submissions are rejected.
+**Example LoginRequest (Username/Password Authentication):**
+<code>
+{
+  "firm": "T4Futures",
+  "username": "trader123",
+  "password": "securepassword",
+  "appName": "CustomTradingApp",
+  "appLicense": "LICENSE-4567"
+}
+</code>
-===== 3. Stay connected (heartbeat) =====
+If authentication succeeds, the server will return a `LoginResponse` with a session ID and assigned roles.
-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.
+**Example Successful LoginResponse:**
 <code>
-// ClientMessage
+{
-heartbeat { timestamp: 1725600000000 }   // UTC epoch milliseconds
+  "result": "LOGIN_SUCCESS",
+  "sessionId": "sess-123456789",
+  "userId": "user-456",
+  "firmId": "firm-789",
+  "roles": ["Trader", "RiskManager"]
+}
 </code>
-===== 4. Authentication token (optional) =====
+If authentication fails, the server will return an error message. Some common reasons for failure include:
-''LoginResponse'' may include an ''authentication_token''. You can also request a fresh one at any time:
-  * Send ''AuthenticationTokenRequest'' with a ''request_id''.
+^ LoginResult Code ^ Meaning ^
-  * Receive ''AuthenticationToken'' with ''token'' and ''expire_time'' (or ''fail_message'').
+| `LOGIN_FAILED` | Invalid credentials. |
+| `TWO_FACTOR_REQUIRED` | Two-factor authentication is required. |
+| `UNAUTHORIZED` | API key or username/password is incorrect. |
+| `PASSWORD_EXPIRED` | The password must be changed before logging in. |
+| `LOCKED_OUT` | Too many failed login attempts. |
-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.
+For detailed message formats, refer to the [[developers:apiv2:reference|Message Catalog]] page.
-===== 5. Reconnecting =====
+===== 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.
+===== Next Steps =====
-  - Send ''LoginRequest'' again.
+Once authenticated, clients can:
-  - Re-subscribe to markets and accounts, and reconcile order state from the account snapshot.
+  * 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]]).
-**Maintenance window:** connections are dropped for weekly maintenance (around midnight Friday) and service resumes Sunday morning. Build automatic reconnect-and-resubscribe into your client.
+----
+💡 **Tip:** Test your WebSocket connection using tools like `wscat` or a sample SDK.