File: WebAPI/metadata_2.proto
Request to resolve a symbol pattern or specific symbol identifier to a specific contract with optional subscription for metadata updates. Symbol resolution rules:
1. If the requested symbol points to a symbol prefix rather than a specific contract then it is resolved into the most active contract for this symbol prefix (e.g., ‘EP’ is resolved to ‘EPU3’). The update is sent when an active contract is changed (e.g., the update might contain the following ‘EPZ3’).
2. If the requested symbol points to an expired contract SymbolResolutionReport is returned with ‘deleted’ field set to True.
3. If the requested symbol points to a specific contract that is tradable right now then it is resolved to itself. Update is sent only when metadata for such contract is changed or expired. In case of expiration SymbolResolutionReport is returned with ‘deleted’ field set to True.
4. If requested symbol points to an option instrument without specific month and strike it is resolved to the lead (first non-spot) month of the underlying future or its own front month if the underlying contract is not a future (e.g., ‘C.EP’ is resolved to ‘C.EPU131600’). Update is sent only when the resolved option contract is expired (strike is not updated to follow underlying contract market price).
5. If requested symbol points to an option instrument without strike or with invalid strike it is resolved to at-the-money strike for the specified month and year (except for expired options).
6. If requested symbol is a symbol prefix that follows ‘?N’ or ‘??N’ (where N is number, e.g., EP?2) then it is resolved to Nth nearest contract. N = 1 means ‘front’ contract, N = 2 means the nearest contract that follows the front, etc. ‘?’ and ‘??’ are different for futures only and ‘?’ means Nth nearest regular future and ‘??’ means Nth nearest spot or regular future. Update is sent when the front contract expired and replaced with the following contract (relative position change). N = 0 is a special case that means ‘most active’ contract which works the same way as (1.). If requested symbol is a symbol prefix that follows ‘?(-N)’ or ‘??(-N)’ then it is resolved to Nth previous contract.
7. If the requested short symbol is resolved to multiple instruments, the returned instrument will be chosen based on supplied lists of preferred instrument types and preferred countries:
o If both lists are supplied, the type preference will be applied before the country preference;
o If only the type list is supplied, it will be applied before the default country preference;
o If only the country list is supplied, the default type preference will be applied before the supplied country preference;
o If neither list is supplied, the default type and country preferences are applied. For example, ‘AMP’ can be resolved to ‘S.US.AMP’ or ‘S.AU.AMP’ depending on preferred countries having preferred instrument types ‘S’.
Note: Available and active contract lists are updated within 24 hours of an expiring contract’s final trading session. Metadata updates for affected contracts, when a subscription is present, are sent when the list updates occur. Initial resolution requests use the same lists, so the best way to avoid inconsistency and unnecessary server load is to subscribe and process updates when notified.
Limits: The request rate is 10000 per 24 hours by default.
Response: SymbolResolutionReport.
Type: string
Description: Symbol pattern to resolve.
Required: yes.
Type: string
Description: Comma-separated list of preferred instrument types. Type is encoded as a single character:
•F - Future
•C - Call Option
•P - Put Option
•S - Equity
•T - Bond
•U - Strategy
•X - Cash and others
Example: ‘F,C,P,X’.
Type: string
Description: Comma-separated list of preferred countries. Two-letter ISO 3166-1 country codes or some CQG-specific exchange codes. Example: ‘US,AU’.
Type: string
Description: Optional dialect ID to resolve the symbol in a dialect different from user_session_2.Logon.dialect_id.
See: user_session_2.Logon.dialect_id.
Type: string
Description: Optional dialect ID indicating the preferred dialect for returned metadata. If not set, SymbolResolutionRequest.resolution_dialect_id will be used.
Note: There is no guarantee that the metadata will be returned in this dialect. If it cannot be satisfied, the metadata will be returned without dialect-specific fields (i.e., as in the default CQG dialect).