Skip to main content

Protocol Buffers Integration

Futures WebSocket supports both JSON and Protobuf push formats. When using Protobuf, follow the integration process below.

Connect with the Protobuf WSS URL:

wss://contract.mexc.com/edge?Trans-Protocol=Protobuf

Important distinction:

  • Client uplink (subscribe, unsubscribe, PING): UTF-8 JSON strings
  • Server downlink market pushes: raw Protobuf binary byte arrays (not JSON)

1.PB File Definition
The PB definition files can be obtained from: https://github.com/mexcdevelop/websocket-future-proto/

2.Generate Deserialization Code
Use the tool at https://github.com/protocolbuffers/protobuf to compile the .proto files and generate deserialization code.

Java

# Run under the proto folder
protoc *.proto --java_out=<java_output_path>

Python

# Run under the proto folder
protoc *.proto --python_out=<python_output_path>

Others

Multiple languages are supported, including C++, C#, Go, Ruby, PHP, JS, etc. For details, see https://github.com/protocolbuffers/protobuf.

3.Data Deserialization
Use the generated PB code to deserialize the binary bytes returned by the server.

Java
Include the protobuf-java dependency:

<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>{protobuf.version}</version><!-- Specify the version as per your project requirements -->
</dependency>

Parsing example:

// Assemble the object
com.mxc.quotation.common.data.vo.pb.Ticker.Builder tickerBuilder =
com.mxc.quotation.common.data.vo.pb.Ticker.newBuilder();

// Serialize to binary
com.mxc.quotation.common.data.vo.pb.Ticker result = tickerBuilder.setSymbol("BTCUSDT")
.build();
byte[] serializedData = result.toByteArray();

// Deserialize into a Ticker object
com.mxc.quotation.common.data.vo.pb.Ticker ticker =
com.mxc.quotation.common.data.vo.pb.Ticker.parseFrom(serializedData);

Python

Parsing example:

import Ticker_pb2

# 1. Create a Ticker object
ticker = Ticker_pb2.Ticker()
# 2. Assign fields
ticker.symbol = "BTCUSDT"

# 3. Serialize to binary bytes
serialized_data = ticker.SerializeToString()

# 4. Deserialize from binary bytes
ticker_new = Ticker_pb2.Ticker()
ticker_new.ParseFromString(serialized_data)

Subscribe to a Data Stream​

Subscribe

{
"method": "sub.ticker",
"param": {
"symbol": "BTC_USDT"
}
}

Unsubscribe from a Data Stream​

Unsubscribe

{
"method": "unsub.ticker",
"param": {
"symbol": "BTC_USDT"
}
}

PING/PONG Mechanism​

Subscribe

{
"method": "ping"
}

Sample data

{
"channel": "pong",
"data": 1587453241453
}