Differences

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

--- developers:websocket [2025/03/14 02:50] – created chad
+++ developers:websocket [2025/03/14 19:15] (current) – [Message Structure Overview] chad
@@ Line 1: / Line 1: @@
-====== Plus500 Futures Technologies WebSocket API ======
+===== WebSocket API Introduction =====
-Welcome to the **Plus500 Futures Technologies WebSocket API**! Our API delivers **high-performance, real-time market data and trading capabilities** using **Google Protocol Buffers (Protobuf)** for ultra-efficient binary messaging. Designed for **speed, scalability, and security**, this API ensures seamless access to market data and order execution with minimal latency.
+The WebSocket API provides a high-performance, low-latency communication channel for real-time trading data and order execution. This section introduces the key technologies used in the API: **WebSockets** and **Google Protocol Buffers (Protobuf)**.
-With an **industry-standard design**, it is easy to integrate and built to meet the demands of **futures traders, risk managers, and financial platforms**.
+==== WebSockets ====
+WebSockets establish a persistent, full-duplex connection between the client and server, allowing for continuous bi-directional message exchange. This ensures minimal latency, making it ideal for market data feeds and order updates.
-===== Key Capabilities =====
+**Key Advantages:**
+  * Persistent connection reduces handshake overhead
+  * Low-latency, real-time data exchange
+  * Efficient bandwidth usage compared to REST APIs
-^ Feature ^ Included ^ Description ^
+==== Google Protocol Buffers (Protobuf) ====
-| **Real-time Quotes** | ✅ | Stream live bid/ask price updates for any instrument. |
+The API utilizes Protobuf for efficient, compact, and high-speed message serialization. Unlike JSON or XML, Protobuf messages are smaller and faster to parse, making them well-suited for high-frequency trading applications.
-| **Level 1 Data** | ✅ | Access top-of-book best bid and offer (BBO). |
-| **Level 2 (Market Depth)** | ✅ | View **up to 10 levels** of bid/ask depth. |
-| **Market by Order (MBO)** | ✅ | See individual resting orders in the order book. |
-| **Trade Feed (Ticker)** | ✅ | Get a **real-time execution stream** of all trades. |
-| **Order Management** | ✅ | Submit, modify, and cancel orders programmatically. |
-| **Position & Account Monitoring** | ✅ | Track open positions, P&L, and margin usage. |
-| **Instrument Metadata** | ✅ | Retrieve contract specs, tick sizes, and margin requirements. |
-| **Spread Trading** | ✅ | Execute spread orders with **complex multi-leg strategies**. |
-| **Risk & Margin Data** | ✅ | Get real-time margin requirements and risk exposure. |
-| **Historical Data Requests** | ✅ | Fetch recent trade history and market activity. |
-| **Efficient Binary Encoding** | ✅ | Uses Protobuf for **low-bandwidth, high-speed** messaging. |
-| **Secure Authentication** | ✅ | Ensures safe access with API key-based authentication. |
-| **Robust Reconnection** | ✅ | Auto-reconnect and resume subscriptions on disconnection. |
-===== Why Use This API? =====
+**Why Protobuf?**
+  * **Compact Encoding:** Reduces message size for faster transmission
+  * **High Performance:** Faster serialization/deserialization than JSON
+  * **Schema Evolution:** Backward-compatible changes allow for future expansion without breaking existing clients
-  * **Fast & Reliable** – Designed for **high-frequency updates and real-time execution**.
+==== Communication Model ====
-  * **Compact & Efficient** – Protobuf minimizes bandwidth, ensuring **fast message processing**.
+The API follows a structured messaging approach:
-  * **Comprehensive Market Data** – Access **Level 1, Level 2, and Market by Order** data.
+  * **Client Messages:** Requests sent from clients to the server (e.g., order submission, subscription requests)
-  * **Built for Futures Trading** – Includes **contract metadata, spread trading, and risk monitoring**.
+  * **Server Messages:** Responses and real-time updates sent from the server (e.g., trade confirmations, market data)
-  * **Scalable & Industry-Proven** – Handles **thousands of concurrent connections**.
-  * **Secure & Encrypted** – Uses **WSS (WebSocket Secure) over SSL/TLS** to protect data.
-  * **Event-Driven & Easy to Integrate** – A simple subscription model delivers the data you need.
-===== Getting Started =====
+==== Message Structure Overview ====
-To begin integrating, visit the [[getting_started|Getting Started]] guide for **connection details, authentication steps, and demo projects**.
+All messages sent to the server must be wrapped in a **ClientMessage** envelope, and all messages received from the server will be contained within a **ServerMessage** envelope. This ensures a consistent structure and simplifies message parsing.
+=== Client Message Structure ===
+A **ClientMessage** is the top-level wrapper for all messages sent to the server. It contains fields for various message types, such as authentication requests, order submissions, and subscription requests.
+Example **ClientMessage**:
+<code>
+message ClientMessage {
+  oneof payload {
+    AuthenticationRequest authentication_request = 1;
+    MarketSubscription market_subscription = 2;
+    OrderRequest order_request = 3;
+    // ... other client messages
+  }
+}
+</code>
+=== Server Message Structure ===
+A **ServerMessage** is the top-level wrapper for all responses and updates from the server. It encapsulates messages related to market data, account updates, and execution reports.
+Example **ServerMessage**:
+<code>
+message ServerMessage {
+  oneof payload {
+    AuthenticationResponse authentication_response = 1;
+    MarketSnapshot market_snapshot = 2;
+    OrderUpdate order_update = 3;
+    // ... other server messages
+  }
+}
+</code>
+=== Message Tools ===
+The [[https://github.com/CTS-Futures/t4-api-tools|T4 API Tools repository]] has code that makes wrapping messages from your client very easy.
+<bootnote>
+Reach out to support if you would like a API tool's for a language we have not covered yet.
+</bootnote>
+^ **Platform** ^ **Client Message Helper** ^
+| **.Net** | [[https://github.com/CTS-Futures/t4-api-tools|ClientMessageHelper.cs]]|
-For a detailed breakdown of all available messages, see the [[message_reference|Message Reference]].
-----
-💡 **Tip:** Use WebSocket clients like `wscat` or our sample SDKs to test the API before building your integration.
-===== Next Steps =====
-  * Connect and Authenticate to **market data streams** ([[api:websocket:connecting|Connecting and Authenticating]]).