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.

✅ Connection Requirements:

• Protocol: WebSocket Secure (WSS) over SSL/TLS
• Port: 443 (Default for WSS)
• Message Format: Google Protocol Buffers (Protobuf)
• Keep-Alive Mechanism:
  1. The server sends a message every 20 seconds.
  2. If no other message is sent during that interval, a heartbeat will be sent.
  3. The client must also send a heartbeat every 20 seconds.
  4. If no message is received for 3 heartbeat intervals, the server will drop the connection.

After establishing a WebSocket connection, the first message a client must send is a `LoginRequest` message. This message supports two authentication methods:

• API Key Authentication – Only requires the `api_key` field.
• Username/Password Authentication – Requires `firm`, `username`, `password`, `app_name`, and `app_license`.

LoginRequest Definition (Protobuf):

message LoginRequest {
  string api_key = 1;  // API Key authentication (optional)

  string firm = 2;      // Firm ID (required for username/password login)
  string username = 3;  // Username
  string password = 4;  // Password
  string app_name = 5;  // Application name
  string app_license = 6;  // Application license key
}

Example LoginRequest Message (API Key Authentication):

{
  "api_key": "abc123-xyz789"
}

Example LoginRequest Message (Username/Password Authentication):

{
  "firm": "T4Futures",
  "username": "trader123",
  "password": "securepassword",
  "app_name": "CustomTradingApp",
  "app_license": "LICENSE-4567"
}

—

Upon receiving a `LoginRequest`, the server will return a `LoginResponse`.

LoginResponse Definition (Protobuf):

message LoginResponse {
  T4Proto.Common.LoginResult result = 1;  // Authentication result
  string session_id = 2;  // Session identifier
  string user_id = 3;  // Authenticated user ID
  string firm_id = 4;  // Firm ID
  repeated string roles = 5;  // Assigned user roles
  string error_message = 6;  // Error details (if applicable)
}

Example Successful LoginResponse:

{
  "result": "LOGIN_SUCCESS",
  "session_id": "sess-123456789",
  "user_id": "user-456",
  "firm_id": "firm-789",
  "roles": ["Trader", "RiskManager"]
}

Example Failed LoginResponse:

{
  "result": "LOGIN_FAILED",
  "error_message": "Invalid username or password"
}

If authentication fails, the server will return an error message with one of the following `LoginResult` codes:

If the connection is lost, clients should implement a reconnection strategy:

• Auto-reconnect: Attempt to reconnect immediately.
• No session resume: Clients must re-authenticate after reconnecting.
• System maintenance:
  1. The system shuts down every Friday at midnight for maintenance.
  2. Service resumes on Sunday morning.

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.