Symbol lists have a tree hierarchy with hardcoded roles at each level.
Warning: New types/roles can be added at any level at any time, so your app should be able to handle them dynamically and filter appropriately.
Warning: IDs associated with symbols or symbol categories can change without explicit notice. Limited stable ID support is provided via SymbolCategoryListByInstrumentTypeRequest, where InstrumentClientType values are guaranteed to remain consistent.
0. Get category id
It is up to client to select what filtered category to use. All categories have meaningful name and description. Also see Warning from above.
Client Message:
{
"information_requests": [
{
"id": 1,
"symbol_category_list_request": {}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 1,
"is_report_complete": true,
"status_code": 0,
"symbol_category_list_report": {
"symbol_categories": [
{
"id": "1",
"name": "Exchange",
"description": "Root node for Exchanges",
"can_filter": true
},
...
Take symbol_categories[].id = 1.
Client Message:
{
"information_requests": [
{
"id": 2,
"symbol_category_list_request": {
"category_id": "1"
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 2,
"is_report_complete": false,
"status_code": 0,
"symbol_category_list_report": {
"symbol_categories": [
...
{
"id": "3516",
"name": "HMS Demo",
"description": "HMS Demo",
"parent_id": "1",
"can_filter": true,
"exchange_id": 216
},
...
Take symbol_categories[].id = 3516.
Client Message:
{
"information_requests": [
{
"id": 3,
"symbol_category_list_request": {
"category_id": "3516"
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 3,
"is_report_complete": true,
"status_code": 0,
"symbol_category_list_report": {
"symbol_categories": [
...
{
"id": "38564",
"name": "CQG Demo HMS Small",
"description": "",
"parent_id": "3516",
"can_filter": true,
"contributor_id": "501"
},
...
Take symbol_categories[].id = 38564.
1. Top Level - Products
Client Message:
{
"information_requests": [
{
"id": 4,
"symbol_list_request": {
"category_ids": [
"38564"
]
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 4,
"is_report_complete": true,
"status_code": 0,
"symbol_list_report": {
"symbols": [
...
{
"id": "CAT.1.38566",
"name": "HM.ESSM",
"description": "US 500 index $1
multiplier",
"has_child_symbols": true,
"category_ids": [
"3516",
"3523",
"3569",
"38564",
"38565"
],
"product_metadata": {
"product_id": "747"
}
},
...
]
}
}
]
}
Take symbols[].id = CAT.1.38566.
2. Second Level - Securities
Client Message:
{
"information_requests": [
{
"id": 5,
"symbol_list_request": {
"category_ids": [
"38564"
],
"parent_symbol_id": "CAT.1.38566"
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 5,
"is_report_complete": true,
"status_code": 0,
"symbol_list_report": {
"symbols": [
{
"id": "CAT.2.38571",
"name": "ESSMHS",
"description": "US 500 index $1
multiplier",
"has_child_symbols": true,
"parent_symbol_id": "CAT.1.38566"
"category_ids": [
...
"38564"
],
"source_symbol_id": "SEC.US.EP",
"security_metadata": {
"security_id": "111355",
"currency": "USD",
...
"symbol_id": "CAT.2.38571",
"source_instrument_group_name": "F.US.EP",
"processing_metadata": [
{
...
}
],
"name": "ESSMHS",
"description": "US 500 index $1 multiplier"
}
}
]
}
}
]
}
Take symbols[].id = CAT.2.38571.
3. Third Level - Contracts or Option Maturities
Client Message:
{
"information_requests": [
{
"id": 6,
"symbol_list_request": {
"category_ids": [
"38564"
],
"parent_symbol_id": "CAT.2.38571"
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 6,
"is_report_complete": true,
"status_code": 0,
"symbol_list_report": {
"symbols": [
{
"id": "CAT.3.346198",
"name": "ESSMHS0000LML",
"description": "US500
perpetual",
"cfi_code": "MMFXXX",
"has_child_symbols": false,
"contract_metadata": {
"contract_id": 1,
"contract_symbol": "X.HM.ESSMHS0000LML"
...
}
...
}
]
}
}
]
}
4. Fourth Level (Only if Third Level is Option Maturity) - Contracts
The type of each symbol can be determined by the presence of specific metadata fields:
•product_metadata (always first level)
•security_metadata (always second level)
•option_maturity_metadata (always thrid level)
•contract_metadata (either third or fourth level)
In this case, event contracts are options. To retrieve them, follow the steps below.
1. Send SymbolCategoryListByInstrumentTypeRequest with instrument_client_type = 15 (since protocol version 2.278 the named const is available InstrumentClientType.INSTRUMENT_CLIENT_TYPE_EVENT_UNDERLYING, older clients still can use 15).
This request returns the category ID for Event Underlying contracts. The next step uses SymbolCategory.id.
2. Send SymbolListRequest with category_ids set to the value obtained in step 1.
Use the depth field as follows:
o Set depth = 1 to retrieve Products
o Repeat the request using the Product parent_symbol_id to retrieve Securities
o Repeat the request again using the Security parent_symbol_id to retrieve Underlying Contracts
The next step uses ContractMetadata.contract_id.
Note:
o depth can be set to 2 or 3 to retrieve multiple levels in a single request.
o If too many symbols are returned, the request fails.
o Subscriptions for updates are not supported when parent_symbol_id is specified and depth > 1.
3. Send OptionMaturityListRequest with underlying_contract_id set to the value obtained in step 2.
The next step uses OptionMaturityMetadata.id.
4. Send InstrumentGroupRequest with instrument_group_id set to the value obtained in step 3.
Requests are done without subscribing, and using implied depth 1. Some responses are cut to save a place.
1. Request filter category
Client Message:
{
"information_requests": [
{
"id": 1,
"symbol_category_list_by_instrument_type_request": {
"instrument_client_type": 15
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 1,
"is_report_complete": true,
"status_code": 0,
"symbol_category_list_by_instrument_type_report": {
"symbol_categories": [
{
"id": "9028910",
"name": "Event Underlying",
"description": "A synthetic future used as the underlying of an event
option",
"parent_id": "3524",
"can_filter": true,
"instrument_business_type_id": 6008
}
]
}
}
]
}
Take symbol_categories[].id = 9028910.
2. Request products
Client Message:
{
"information_requests": [
{
"id": 2,
"symbol_list_request": {
"category_ids": [
"9028910"
]
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 2,
"is_report_complete": true,
"status_code": 0,
"symbol_list_report": {
"symbols": [
{
"id": "CAT.1.1199054",
"name": "ENQ",
"description": "E-mini NASDAQ-100",
"has_child_symbols": true,
"category_ids": [
"9028910"
],
"product_metadata": {
"product_id": "4392"
}
},
...
Take symbols[].id = CAT.1.1199054.
3. Request securities
Client Message:
{
"information_requests": [
{
"id": 3,
"symbol_list_request": {
"category_ids": [
"9028910"
],
"parent_symbol_id": "CAT.1.1199054"
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 3,
"is_report_complete": true,
"status_code": 0,
"symbol_list_report": {
"symbols": [
{
"id": "CAT.2.1231300",
"name": "ECNQ",
"description": "E-mini NASDAQ-100 Synthetic",
"has_child_symbols": true,
"parent_symbol_id": "CAT.1.1199054",
"category_ids": [
"246",
"271",
"274",
"3524",
"9028910"
],
"security_metadata": {
"security_id": "304039",
"currency": "USD",
...
Take symbols[].id = CAT.2.1231300.
4. Request (underlying) contracts
Client Message:
{
"information_requests": [
{
"id": 4,
"symbol_list_request": {
"category_ids": [
"9028910"
],
"parent_symbol_id": "CAT.2.1231300"
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 4,
"is_report_complete": true,
"status_code": 0,
"symbol_list_report": {
"symbols": [
{
"id": "CAT.3.5732132",
"name": "ECNQM26",
"description": "E-mini NASDAQ-100 Synthetic: June
2026",
"cfi_code": "FXXXXX",
"has_child_symbols": false,
"contract_metadata": {
"contract_id": 123,
"dialect_contract_symbol": "F.US.ECNQM26",
"correct_price_scale": 0.01,
"display_price_scale": 2,
"dialect_description": "E-mini NASDAQ-100 Synthetic: June
2026",
"dialect_title": "ECNQM26",
...
Take contract_metadata.contract_id = 123.
5. Request option maturities
Client Message:
{
"information_requests": [
{
"id": 5,
"option_maturity_list_request": {
"underlying_contract_id": 123
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 5,
"is_report_complete": true,
"status_code": 0,
"option_maturity_list_report": {
"option_maturities": [
{
"id": "625806",
"name": "ECNQD15/J26",
"description": "Event Contract on E-mini Nasdaq-100 Day 15: April
2026",
"cfi_code": "OXAXXX",
"reserved1": true,
"last_trading_date": 3009969000,
"maturity_month_year": "J26",
"instrument_group_name": "ECNQD15",
"instrument_group_empty": false,
"listing_period_type": 5,
"listing_period_value": 15,
"last_trading_date_time_utc_timestamp": {
"seconds": 1776283200
}
}
]
}
}
]
}
Take option_maturities[].id = 625806.
6. Request options (event contracts)
Client Message:
{
"information_requests": [
{
"id": 6,
"instrument_group_request": {
"instrument_group_id": "625806"
}
}
]
}
Server Response:
{
"information_reports": [
{
"id": 6,
"is_report_complete": false,
"status_code": 0,
"instrument_group_report": {
"instruments": [
{
"id": "CON.P.US.ECNQD15.J26.19500",
"name": "P.US.ECNQD15J2619500",
"description": "ECNQD15: April 2026 Put Option at
19500",
"cfi_code": "OPAXXX",
"reserved1": false,
"contract_metadata": {
"contract_id": 456,
"dialect_contract_symbol": "P.US.ECNQD15J2619500",
"correct_price_scale": 0.01,
"display_price_scale": 2,
"dialect_description": "ECNQD15: April 2026 Put Option at
19500",
"dialect_title": "P.ECNQD15J2619500",
"tick_size": 0.01,
"currency": "USD",
"tick_value": 0.01,
"cfi_code": "OPAXXX",
"last_trading_date": 3009969000,
"underlying_contract_symbol": "F.US.ECNQM26",
...