developers:websocket:connecting [WIKI]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Connecting and Authenticating ======

To start using the **Plus500 Futures Technologies WebSocket API**, clients must establish a secure WebSocket connection and authenticate before subscribing to data streams or submitting orders.

===== WebSocket Connection =====

<WRAP 50%>
^ **Environment** ^ **WebSocket URL** ^
| **Live** | %%wss://wss.t4login.com/v1%% |
| **Simulator** | %%wss://wss-sim.t4login.com/v1%% |
</WRAP>




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

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.

===== 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 `api_key` field).  
- **Username/Password Authentication** (send `firm`, `username`, `password`, `app_name`, and `app_license`).  

**Example LoginRequest (API Key Authentication):**
<code>
{
  "api_key": "abc123-xyz789"
}
</code>

**Example LoginRequest (Username/Password Authentication):**
<code>
{
  "firm": "T4Futures",
  "username": "trader123",
  "password": "securepassword",
  "app_name": "CustomTradingApp",
  "app_license": "LICENSE-4567"
}
</code>

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

**Example Successful LoginResponse:**
<code>
{
  "result": "LOGIN_SUCCESS",
  "session_id": "sess-123456789",
  "user_id": "user-456",
  "firm_id": "firm-789",
  "roles": ["Trader", "RiskManager"]
}
</code>

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

^ LoginResult Code ^ Meaning ^
| `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. |

For detailed message formats, refer to the [[message_reference|Message Reference]] page.

===== 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.  

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.

===== 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]]).

----

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