First, download and unzip the protocol from the CQG site.
Next, you need to convert the protocol files (from the WebAPI and common directories) to your desired programming language. Use the official Protobuf documentation for the chosen language. This documentation also provides information on working with the protocol, including creating, serializing, and deserializing messages.
You can install precompiled protoc.
Note: The CQG WebAPI protocol uses native Protobuf types. During generation, one of the --proto_path parameters should specify the path where these types are available (e.g., src). These types should be available along with the Protobuf compiler (protoc).
For example, the following shell commands generate Python code:
protoc --proto_path=source_proto_dir --proto_path=google_proto_dir
--python_out=destination_dir
source_proto_dir/WebAPI/*.proto
protoc --proto_path=source_proto_dir --proto_path=google_proto_dir
--python_out=destination_dir
source_proto_dir/common/*.proto
protoc --proto_path=source_proto_dir --proto_path=google_proto_dir
--python_out=destination_dir
source_proto_dir/cqg_api/*.proto
protoc --proto_path=source_proto_dir --proto_path=google_proto_dir
--python_out=destination_dir
source_proto_dir/cqg_api/common/*.proto
## and other subfolders in the source_proto_dir/cqg_api
folder
Install the Protobuf runtime.
Next, initialize your project, add the generated Protobuf files, and include the Protobuf runtime.
Prepare your project to use WebSocket Secure (WSS) communication, ensuring that it can establish a connection to the CQG WebAPI server. Plain WebSocket (WS) is not supported.
Now you are ready to send and receive messages.
All messages from the client are of type ClientMsg, and all messages from the server are of type ServerMsg.
2. InformationRequest → AccountsRequest, example here.
3. InformationRequest → LastStatementBalancesRequest, example here.
4. InformationRequest → SymbolResolutionRequest, example here.
5. MarketDataSubscription, example here.
6. TradeSubscription, example here.
7. OrderRequest, example here.
For unsubscribing:
1. MarketDataSubscription, example here.
2. TradeSubscription, example here.
Note: After logon, the CQG WebAPI server periodically sends a Ping message. The client application is expected to respond with a Pong. If the client does not respond, the server will send a UserMessage regarding the unanswered ping.
Note: It is only a small part of the available messages. The full list of client requests is available on ClientMsg and its submessages. The full list of server messages is available on ServerMsg and its submessages.
Note: Check time conversion and scaled price conversion to interpret time and price fields.
CQG provides the Prototester tool, which allows you to manually construct messages in the browser and communicate with the server without additional environment setup.
A basic implementation in Python is available on GitHub. Repository includes compiled protocol (which may not be the latest version) and other dependencies.
More details are here.
Client Message:
{
"logon": {
"user_name": "user name",
"password": "***",
"private_label": "company",
"client_app_id": "company app",
"client_version": "1.0",
"protocol_version_major": 2,
"protocol_version_minor": 240
}
}
Server Response:
{
"logon_result": {
"result_code": 0,
"base_time": "2025-02-16T06:20:12",
"session_token": "session
identifier",
"protocol_version_major": 2,
"protocol_version_minor": 240,
"user_id": 12345,
"server_time": 226779398
}
}
Client Message:
{
"logoff": {}
}
Server Response:
{
"logged_off": {
"logoff_reason": 1
}
}
Client Message:
{
"information_requests": [
{
"id": 1,
"subscribe": true,
"accounts_request": {}
}
]
}
Server Response:
A single account is returned.
{
"information_reports": [
{
"id": 1,
"is_report_complete": true,
"status_code": 1,
"accounts_report": {
"brokerages": [
{
"id": 1234,
"name": "CQG Sim",
"sales_series": [
{
"number": "12345",
"name": "CQG Sim series",
"accounts": [
{
"account_id": 123456,
"brokerage_account_number": "PS123456",
"name": "SIM123456",
"last_statement_date": 63588000,
"is_view_only": false,
"pre_trade_mid_market_mark_required": false,
"allow_external_accounts": false,
"is_omnibus": false,
"is_group_member": false,
"force_care_orders": false,
"cleared_by_statements": true,
"supports_exchange_balances_subscription": false,
"supports_exchange_positions_subscription": false
}
]
}
],
"type": 2
}
]
}
}
]
}
Client Message:
{
"information_requests": [
{
"id": 2,
"last_statement_balances_request": {}
}
]
}
Server Response:
The balance is $100,000.
{
"information_reports": [
{
"id": 2,
"is_report_complete": true,
"status_code": 0,
"last_statement_balances_report": {
"balances": [
{
"id": 1,
"account_id": 123456,
"statement_date": 63588000,
"currency": "USD",
"balance": 100000,
"total_value": 0,
"ote": 0,
"upl": 0,
"mvo": 0,
"cash_excess": 0,
"collateral": 0,
"initial_margin": 0
}
]
}
}
]
}
Client Message:
{
"information_requests": [
{
"id": 1,
"symbol_resolution_request": {
"symbol": "EP"
}
}
]
}
Server Response:
Field values may differ from what you receive.
{
"information_reports": [
{
"id": 0,
"status_code": 0,
"symbol_resolution_report": {
"contract_metadata": {
"contract_id": 1,
"contract_symbol": "F.US.EPU25",
"correct_price_scale": 0.01,
"display_price_scale": 2,
"description": "E-Mini S&P 500: September 2025",
"title": "EPU25",
"tick_size": 0.25,
"currency": "USD",
"tick_value": 12.5,
"cfi_code": "FXXXXX",
"is_most_active": false,
"last_trading_date": 18553188000,
"instrument_group_name": "F.US.EP",
"session_info_id": 206,
"mic": "GLBX",
"short_instrument_group_name": "EP",
"instrument_group_description": "E-Mini S&P
500",
"dialect_id": "0",
"country_code": "US",
"contract_size": "50 x S&P 500
Index",
"position_tracking": 1,
"speculation_type_required": false,
"maturity_month_year": "U25",
"price_display_mode": 0,
"volume_scale": {
"significand": 1
},
"volume_display_exponent": 0,
"trade_size_increment": {
"significand": 1
},
"extended_description": "E-Mini S&P 500: September
2025",
"mic_description": "CME GLOBEX",
"has_exchange_volume": true,
"maintenance_margin": 18811,
"contract_size_in_units": {
"significand": 5,
"exponent": 1
},
"contract_size_unit": {
"key": "Index points",
"text": "Index points"
},
"listing_period_type": 0,
"listing_period_value": 9,
"symbol_id": "CAT.3.2317887",
"deleted": false,
"has_inverted_price_ladder": false,
"has_yields": false,
"contributor_group_id": 91,
"market_state_group_id": 96,
"cqg_contract_symbol": "F.US.EPU25",
"pricing_convention": 1,
"bar_building_tick_types": [
3,
4
],
"quoted_in": "Terms of the S&P 500 Stock Index
Points",
"product_symbol_id": "CAT.1.899232",
"exchange_id": 91,
"supports_continuation": true,
"initial_margin": 21136,
"instrument_business_type_id": 6001,
"close_sources": [
1,
2
],
"open_close_type": 0
},
"deleted": false
}
}
]
}
Client Message:
{
"market_data_subscriptions": [
{
"contract_id": 1,
"level": 2,
"request_id": 3
}
]
}
•contract_id: Retrieved from symbol resolution.
•level: 2: LEVEL_TRADES_BBA, gets trades and settlements with volumes (if known), best asks, and best bids without volumes.
Server Response:
Subscription status + settlement, trade, BBA quotes, and market values.
{
"market_data_subscription_statuses": [
{
"contract_id": 1,
"status_code": 0,
"level": 2,
"past_quotes_included": false,
"yields_included": false,
"session_market_values_included": false,
"source_price_included": false,
"requests_for_quotation_included": false,
"trade_attributes_included": false,
"market_state_included": false,
"request_id": 3,
"off_market_trades_included": false,
"currency_rate_included": false,
"premium_included": false
}
],
"real_time_market_data": [
{
"contract_id": 1,
"quotes": [
{
"type": 5,
"quote_utc_time": 225587999,
"scaled_price": 626175
},
{
"type": 0,
"quote_utc_time": 226787548,
"scaled_price": 626225,
"scaled_volume": 1,
"sales_condition": 4
},
{
"type": 2,
"quote_utc_time": 226857784,
"scaled_price": 626425
},
{
"type": 1,
"quote_utc_time": 226861172,
"scaled_price": 626150
}
],
"is_snapshot": true,
"market_values": [
{
"scaled_open_price": 626100,
"scaled_high_price": 627000,
"scaled_low_price": 623500,
"scaled_last_price": 626225,
"scaled_yesterday_settlement": 624700,
"scaled_total_volume": 71,
"scaled_yesterday_last": 624650,
"day_index": 0,
"tick_volume": 23,
"scaled_settlement": 626175,
"trade_date": 149988000,
"scaled_last_trade_price": 626225,
"scaled_close_price": 626225,
"scaled_last_price_no_settlement": 626225,
"last_trade_utc_timestamp": {
"seconds": 1739913599,
"nanos": 548000000
}
}
],
"quotes_trade_date": 149988000,
"correct_price_scale": 0.01
}
]
}
Client Message:
{
"market_data_subscriptions": [
{
"contract_id": 1,
"level": 0,
"request_id": 4
}
]
}
Server Response:
{
"market_data_subscription_statuses": [
{
"contract_id": 1,
"status_code": 0,
"level": 0,
"past_quotes_included": false,
"yields_included": false,
"session_market_values_included": false,
"source_price_included": false,
"requests_for_quotation_included": false,
"trade_attributes_included": false,
"market_state_included": false,
"request_id": 4,
"off_market_trades_included": false,
"currency_rate_included": false,
"premium_included": false
}
]
}
Client Message:
{
"trade_subscriptions": [
{
"id": 5,
"subscription_scopes": [1],
"subscribe": true
}
]
}
Server Response:
{
"trade_subscription_statuses": [
{
"id": 5,
"status_code": 0
}
]
}
If the user has no orders yet, only completion is returned:
{
"trade_snapshot_completions": [
{
"subscription_id": 5,
"subscription_scopes": [1]
}
]
}
Client Message:
{
"trade_subscriptions": [
{
"id": 5,
"subscribe": false
}
]
}
Server Response:
{
"trade_subscription_statuses": [
{
"id": 5,
"status_code": 0
}
]
}
Place a new order: BUY 1 F.US.EPU25 MKT DAY
Client Message:
{
"order_requests": [
{
"request_id": 0,
"new_order": {
"order": {
"account_id": 123456,
"contract_id": 1,
"cl_order_id": "client unique order id",
"order_type": 1,
"duration": 1,
"side": 1,
"when_utc_timestamp": {
"seconds": 1739914600
},
"qty": {
"significand": 1
}
}
}
}
]
}
Server Response:
The server response includes multiple order statuses for the trade subscription, such as ‘in transit’, ‘in the order book’, and ‘filled.’ Order statuses come only if there is active trade subscription with order scope.
{
"order_statuses": [
{
"subscription_ids": [
5
],
"is_snapshot": false,
"status": 1,
"order_id": "1809769617",
"chain_order_id": "1809769617",
"status_utc_time": 227988204,
"submission_utc_time": 227988204,
"fill_cnt": 0,
"scaled_avg_fill_price": 0,
"order": {
"account_id": 123456,
"when_utc_time": 227788000,
"contract_id": 1,
"cl_order_id": "client unique order id",
"order_type": 1,
"duration": 1,
"side": 1,
"is_manual": true,
"is_user_attribute_checked": false,
"when_utc_timestamp": {
"seconds": 1739914600
},
"qty": {
"significand": 1
},
"execution_source_code": "Y",
"is_care_order": false
},
"transaction_statuses": [
{
"status": 1,
"trans_id": 394602971392,
"trans_utc_time": 227988204,
"cl_order_id": "client unique order id",
"trans_utc_timestamp": {
"seconds": 1739914800,
"nanos": 204300000
},
"mifid_execution_decision": "NORE",
"execution_source_code": "Y",
"is_automated": false,
"mifid_execution_decision_is_algo": false,
"username": "test user"
}
],
"entered_by_user": "test user",
"first_statement_date": 149988000,
"account_id": 123456,
"status_utc_timestamp": {
"seconds": 1739914800,
"nanos": 204300000
},
"submission_utc_timestamp": {
"seconds": 1739914800,
"nanos": 204268000
},
"avg_fill_price_correct": 0,
"fill_qty": {
"significand": 0
},
"remaining_qty": {
"significand": 1
},
"mifid_execution_decision": "NORE",
"mifid_execution_decision_is_algo": false,
"operator_id": "4567"
}
]
}
{
"order_statuses": [
{
"subscription_ids": [
5
],
"is_snapshot": false,
"status": 3,
"order_id": "1809769617",
"chain_order_id": "1809769617",
"exec_order_id": "2118-40E6515CE38E38E4",
"status_utc_time": 227988206,
"submission_utc_time": 227988204,
"fill_cnt": 0,
"scaled_avg_fill_price": 0,
"order": {
"account_id": 123456,
"when_utc_time": 227788000,
"contract_id": 1,
"cl_order_id": "client unique order id",
"order_type": 1,
"duration": 1,
"side": 1,
"is_manual": true,
"is_user_attribute_checked": false,
"when_utc_timestamp": {
"seconds": 1739914600
},
"qty": {
"significand": 1
},
"execution_source_code": "Y",
"is_care_order": false
},
"transaction_statuses": [
{
"status": 3,
"trans_id": 394602971648,
"trans_utc_time": 227988206,
"cl_order_id": "client unique order id",
"route_cl_order_id": "OrderID1809769617",
"trans_utc_timestamp": {
"seconds": 1739914800,
"nanos": 206820000
},
"mifid_execution_decision": "NORE",
"execution_source_code": "Y",
"is_automated": false,
"mifid_execution_decision_is_algo": false
}
],
"entered_by_user": "test user",
"first_statement_date": 149988000,
"account_id": 123456,
"status_utc_timestamp": {
"seconds": 1739914800,
"nanos": 206820000
},
"submission_utc_timestamp": {
"seconds": 1739914800,
"nanos": 204268000
},
"avg_fill_price_correct": 0,
"fill_qty": {
"significand": 0
},
"remaining_qty": {
"significand": 1
},
"detailed_dom_order_id": "2118-40E6515CE38E38E4",
"route_cl_order_id": "OrderID1809769617",
"mifid_execution_decision": "NORE",
"mifid_execution_decision_is_algo": false,
"operator_id": "4567"
}
]
}
{
"order_statuses": [
{
"subscription_ids": [
1
],
"is_snapshot": false,
"status": 8,
"order_id": "1809769617",
"chain_order_id": "1809769617",
"exec_order_id": "2118-40E6515CE38E38E4",
"status_utc_time": 227988207,
"submission_utc_time": 227988204,
"fill_cnt": 1,
"scaled_avg_fill_price": 626175,
"order": {
"account_id": 123456,
"when_utc_time": 227788000,
"contract_id": 1,
"cl_order_id": "client unique order id",
"order_type": 1,
"duration": 1,
"side": 1,
"is_manual": true,
"is_user_attribute_checked": false,
"when_utc_timestamp": {
"seconds": 1739914600
},
"qty": {
"significand": 1
},
"execution_source_code": "Y",
"is_care_order": false
},
"transaction_statuses": [
{
"status": 11,
"trans_id": 394602971904,
"trans_utc_time": 227988207,
"cl_order_id": "client unique order id",
"scaled_fill_price": 626175,
"trades": [
{
"trade_id": "24732144128",
"contract_id": 1,
"statement_date": 149988000,
"trade_utc_time": 227988000,
"trade_date": 149988000,
"scaled_price": 626175,
"side": 1,
"leg_execution_id": "67BA-40E6515CE38E38E4_20250218",
"trade_utc_timestamp": {
"seconds": 1739914800
},
"price_correct": 6261.75,
"qty": {
"significand": 1
}
}
],
"route_cl_order_id": "OrderID1809769617",
"trans_utc_timestamp": {
"seconds": 1739914800,
"nanos": 207373000
},
"mifid_execution_decision": "NORE",
"fill_qty": {
"significand": 1
},
"execution_source_code": "Y",
"is_automated": false,
"mifid_execution_decision_is_algo": false
}
],
"entered_by_user": "test user",
"first_statement_date": 149988000,
"account_id": 123456,
"status_utc_timestamp": {
"seconds": 1739914800,
"nanos": 207373000
},
"submission_utc_timestamp": {
"seconds": 1739914800,
"nanos": 204268000
},
"avg_fill_price_correct": 6261.75,
"fill_qty": {
"significand": 1
},
"remaining_qty": {
"significand": 0
},
"fill_utc_timestamp": {
"seconds": 1739914800,
"nanos": 207332000
},
"detailed_dom_order_id": "2118-40E6515CE38E38E4",
"route_cl_order_id": "OrderID1809769617",
"mifid_execution_decision": "NORE",
"mifid_execution_decision_is_algo": false,
"operator_id": "4567"
}
]
}