CME Reference Data API Version 3
The CME Reference Data APIv3, hosted on Google Cloud (GC) is a set of JSON RESTful web service APIs that provide real-time restricted access to product and instrument referential data using OAuth, an open protocol that supports secure authorization in a simple, standard method and decouples authentication from authorization. CME Reference Data APIv3 provides product and instrument reference data for all CME Group, BrokerTec, EBS, Hosted Partners and CME Group-cleared markets.
Products contain all available products - BrokerTec, EBS, futures, options on futures, spreads and products - on an underlying asset or related index or related future.
Instruments are the individual traded and cleared contracts.
Information includes:
Contract specifications
Product codes and symbols for all CME Group venues
Trade and order type eligibility
Instrument life cycle dates including first and last trade date, all notice dates, delivery dates and settlement dates.
Client systems can automate their product and instrument definitions by pulling the information from the CME Reference Data APIs, reducing the manual work involved in setting up new products. All customers are strongly encouraged to develop to the CME Reference Data APIs and integrate it into their product definition architecture.
BrokerTec and EBS product information is not supported in the Security Definition Flat File (secdef.dat) alongside CME Futures and Options products.
For pre-listed instruments with next day activation, clients should start polling CME Reference Data API version 3 for the instruments after 3:00 p.m. CT.
Contents
- 1 Testing and Certification
- 2 Restricted Access
- 3 Accessing CME Reference Data API Endpoints
- 4 Returned Attributes
- 5 Sorted Results
- 6 Pagination
- 7 Collection Header
- 8 Errors
- 9 Searches
- 9.1 Special Characters
- 9.2 Query Searches
- 9.2.1 Query Samples
- 10 Record Relationships
- 11 Query Parameters
- 12 BrokerTec Display Groups
- 13 Product and Instrument Attribute Details
- 14 CME Globex Trading Hours and Holiday Schedules
- 15 Product Retention Rules
- 16 CME Reference Data API Version 3 for EBS Market
- 17 Contact Information
Testing and Certification
Certification is not required. Testing is strongly encouraged.
Restricted Access
CME Reference Data API version 3 uses OAuth, an open protocol that supports secure authorization in a simple, standard method and decouples authentication from authorization.
Authorization and Entitlement
A registered OAuth API ID is required to access the CME Reference Data API version 3 services. API IDs for CME Group Logins are created and managed in the Customer Center under My Profile.
Complete the step(s) that are applicable to your account:
New Clients | Clients with Existing CME Group Logins |
|---|---|
| Login to CME Customer Center and under My Profile click API Management where clients can:
|
Requesting Entitlement
Client's API IDs must be entitled and registered by the Enterprise Access and Entitlements (EASE) team to view and consume the BrokerTec and EBS content.
To request access in the New Release environment, complete the following forms:
To request access in the Production environment, complete the following forms:
CME Group requires customers to create unique OAuth API IDs for both the New Release and Production environments.
Default Entitlements
Entitlement registration is not required to access Futures and Options attributes; clients can simply log into the API with their API ID credentials.
Accessing CME Reference Data API Endpoints
To access CME Reference Data API version 3 endpoints in the New Release and Production environments, an OAuth API ID and access token are required.
The following endpoints are used by client applications to communicate with the OAuth Authorization Server to request and refresh access tokens.
Client systems are allowed to use any API tool of their choice to request and refresh access tokens to access CME Reference Data API version 3 endpoints using the OAuth protocol.
See Client API Service Adoption using OAuth 2.0 Protocol for an example of using a token.
OAuth 2.0 Authorization Server Access Token Retrieval Endpoints
The below endpoints are available to request and refresh access tokens in the New Release and Production environments.
OAuth 2.0 Authorization Server Endpoints | |||
|---|---|---|---|
Detail | New Release | Production | Access |
OAuth Token Endpoint | https://authnr.cmegroup.com/as/token.oauth2 | https://auth.cmegroup.com/as/token.oauth2 | OAuth Token endpoints are accessible only over the public internet. |
Tokens will expire after 30 minutes.
Authorized API ID's may access the endpoints in the New Release and Production environments:
New Release Endpoints by Market
Futures and Options | BrokerTec | EBS |
|---|---|---|
refdata.api.uat.cmegroup.com/refdata/v3/products | refdata.api.uat.cmegroup.com/refdata/v3/products | refdata.api.uat.cmegroup.com/refdata/v3/products |
refdata.api.uat.cmegroup.com/refdata/v3/instruments | refdata.api.uat.cmegroup.com/refdata/v3/instruments | refdata.api.uat.cmegroup.com/refdata/v3/instruments |
refdata.api.uat.cmegroup.com/refdata/v3/tradingSchedules | refdata.api.uat.cmegroup.com/refdata/v3/displayGroups | refdata.api.uat.cmegroup.com/refdata/v3/tradingSessionValueDates |
https://refdata.api.uat.cmegroup.com/refdata/v3/optionSeries |
Production Endpoints by Market
Futures and Options | BrokerTec | EBS |
|---|---|---|
refdata.api.cmegroup.com/refdata/v3/products | refdata.api.cmegroup.com/refdata/v3/products | refdata.api.cmegroup.com/refdata/v3/products |
refdata.api.cmegroup.com/refdata/v3/instruments | refdata.api.cmegroup.com/refdata/v3/instruments | refdata.api.cmegroup.com/refdata/v3/instruments |
refdata.api.cmegroup.com/refdata/v3/tradingSchedules | refdata.api.cmegroup.com/refdata/v3/displayGroups | refdata.api.cmegroup.com/refdata/v3/tradingSessionValueDates |
https://refdata.api.cmegroup.com/refdata/v3/optionSeries |
Network Connections
CME Reference Data product and instrument information is available over all CME Group network connections for EBS Market, eFix and BrokerTec.
There are weekly maintenance periods that occur on Friday from 10:00 p.m. CT to Saturday 7:00 p.m. CT. During these times, data may be unavailable or unreliable.
New Release Network Connections by Customer Type
Accessing RD APIv3 in the New Release environment over Cert VPN and Cert Data Center connections.
CME Group Network Connections | |||
|---|---|---|---|
Environment | Customer Type | IP | Port |
New Release | EBS eFix | 164.74.124.119 | 443 |
BrokerTec | |||
Futures and Options | |||
Production Network Connections by Customer Type
Accessing RD APIv3 in the production environment over all CME Group connections enabled for EBS Market, eFix, and BrokerTec futures and options at:
CME Group Network Connections | |||
|---|---|---|---|
Environment | Customer Type | IP | Port |
Production
| BrokerTec | 167.204.72.98 | 443 |
EBS eFix | 167.204.72.185 | 443 | |
Futures and Options | 167.204.71.195 | 443 | |
Clients must have access to Internet-based DNS or resolve the original path name to the new IP at their side.
OWASP Compliance
RD APIv3 is hosted on Google Cloud and protected by Google Cloud Armor with preconfigured Web Application Firewall (WAF) rules leveraging the OWASP Top 10 rules.
CME Group recommends clients utilize the OWASP Top 10 rules when developing to RD APIv3.
Hours of Availability
The CME Reference Data APIs are real-time APIs available 24 hours a day, 7 days a week.
Data Refresh
Data will be updated every 7 minutes or less. Client systems should consider all returned data to be accurate as of the time of the request submission. Since the products are updated dynamically, multiple requests may return different results.
Weekly Maintenance
There are weekly maintenance periods that occur on Friday from 10:00 p.m. CT to Saturday 7:00 p.m. CT. During these times, data may be unavailable or unreliable.
Returned Attributes
All attributes for a product or instrument are always returned. Attributes that are undefined or have no value for a particular product or instrument will return "null."
Sorted Results
CME Reference Data API does not support sorted results.
Pagination
To make responses more manageable, CME Reference Data API returns results in pages.
The metadata "type" will return the page.
By default, 1000 results per page are included, displayed results per page can be requested (up to 2000) using the size parameter.
CME Reference Data API also supports a page parameter to allow clients to view a specific page in the result set.
If pagination (page and size values) is passed in the URL explicitly, then the same will be used to retrieve data.
Name | Description | Additional Details |
|---|---|---|
size | Number of results returned per page | Optional query parameter.
|
The parameters below will only be shown if they are applicable. For example, you won’t see next if you are on the last page , nor would you see prev if you are on the first page.
Pagination Links
Name | Description | Additional Details |
|---|---|---|
self | href URL for the query. | |
prev | href URL for the previous page of query results. | |
first | href URL for the first page of query results. | Page=0 is the value for the first page. |
next | href URL for the next page of query results. | |
last | href URL for the last page of query result. | The page value on this reference will be one less than the total Pages value. |
Pagination Metadata
Name | Description | Additional Details |
|---|---|---|
size | Number of results returned per page. | Optional query parameter. The maximum size value is 1000 and the minimum size value is 1. If size is not specified, the default is 20. If size is specified but is less than 1 (e.g., size=0 or size=-9 ), the default of 20 is used. If size is specified but is greater than 1000 (e.g., 2000), 1000 will be used. |
totalElements | Total number of items returned by the query. | |
totalPages | Number of pages required to list all items. | Only included when results are paginated. |
number | Current page number; numbering starts with 0. | |
type | Indicates if pagination is used for the data return. | Will return a page for responses with less than 10,000 results. |
Collection Header
CME Reference Data API does not support attributes in collection headers.
Errors
CME Reference Data API uses standard HTTP response codes to indicate success or failure of an API request.
Codes in the 2xx range indicate success; codes in the 4xx range indicate success or failure of an API / query request; and codes in the 5xx range indicate an error with the CME Group servers.
Status | Explanation |
|---|---|
200 | OK
|
400 | Request was missing required information or was malformed |
401 | Unauthorized
|
403 | Forbidden - returned when the particular HTTPS method is not allowed (e.g., POST, PATCH, PUT, DELETE...) |
404 | Requested item not found |
5xx | There is a server error on the CME Group side |
Searches
CME Reference Data API supports GET requests for all product or instrument records, using the following calls:
All product records: /v3/products
All instrument records: /v3/instruments
All display groups (BrokerTec): /v3/displayGroups
All trading session value dates (EBS): /v3/tradingSessionValueDates
Special Characters
There are certain characters (/ , # , \ , < , >, space) which are reserved and unsafe characters and should not be used in queries and if used should be encoded.
Note the + (plus) is not supported and the ? should be used as a substitute. The ? is one of the wildcard characters currently supported in RD API.
Characters | Encoding |
|---|---|
/ | %2F |
# | %23 |
\ | %5C |
< | %3C |
> | %3E |
space | %20 |
+ | Not supported |
Encoded Examples:
Query | Encoded Query |
|---|---|
longName=8_11/21 09/03-10/20 | longName=8_11%2F21%2009%2F03-10%2F20 |
longName=EUROGC+_LCR_MIN_SIZE_25MM | longName=EUROGC?_LCR_MIN_SIZE_25MM |
longName=GC<10* | longName=GC%3C10* |
globexGroupCode=#USBD | globexGroupCode=%23USBD |
Query Searches
Query searches consist of one or more items that include an attribute, operator and value that are implemented as part of an HTTPS GET request.
Only the "=" operator is currently supported.
A wildcard "*" can be included in the value to return all products or instruments that match a partial value.
Terms can be combined with question mark (?) for the first parameter, and an ampersand (&) for subsequent parameters to return only the results that match ALL of the search terms.
Query parameter values are case sensitive and must be in upper case or as values returned in JSON.
Examples:
refdata.api.cmegroup.com/refdata/v3/instruments?globexSymbol=ESU3 - Total elements returned 1
refdata.api.cmegroup.com/refdata/v3/instruments?globexSymbol=eSU3 - Total elements returned 0
Query attributes are listed below.
Query Samples
Query | Query Type | Description |
|---|---|---|
/v3/products | Product | Returns information on every product cleared or hosted at CME Group. |
/v3/instruments | Instrument | Returns information on every instrument cleared or hosted at CME Group. |
/v3/products?globexProductCode=GE | Product with Globex Product Code filter | Returns information on all products traded on CME Globex under the product code "GE". |
/v3/instruments?globexSymbol=05* /v3/instruments?globexSymbol=*05 /v3/instruments?globexSymbol=*05* | Instrument with Globex Symbol filter of | * at the end of a string brings up all matches that start with the string. * at the beginning of a string brings up all matches that end with the string. * at both the beginning and end of a string brings up all matches that have that string in the middle. |
/v3/instruments?cusip=912828XU9 | Instrument with exact pattern match | Returns US & Canadian externally registered security identifier. |
/v3/products?securityType=FUT | Product with securityType Filter | Returns information on all products traded or cleared as a Futures contract. |
/v3/products?securityType=FUT&exchangeClearing=CME | Product with securityType and exchangeClearing filters | Returns information on all products cleared as a Futures contract and listed under the CME Rulebook |
/v3/products?securityType=TBOND&globexEligible=Y | Product with securityType and globexEligible filters | Returns information on all US Treasury Bond products and eligible to trade on CME Globex |
/v3/products?globexGroupCode=USBD& globexEligible=Y | Product with globexGroupCode and globexEligible filters | Returns information on all US Treasury Notes and Bonds products and eligible to trade on CME Globex |
/v3/displayGroups?centralGroupName=BENCH/WI | Display Group central group name | Returns central group and list of instruments |
/v3/instruments?lastTradedAfter=Tuesday, September 15, 2020 7:00:00 PM CT&lastTradedBefore=Wednesday, September 16, 2020 7:00:00 PM CT /v3/instruments?lastTradedAfter=1600214400000&lastTradedBefore=1600300800000 | Instrument with last trade date range | Returns all instruments with last trade date after a certain date and before a certain date. |
/v3/tradingSessionValueDates?rbtEligibleInd=N | Trading Session Value Dates | Returns trade date to value date (date of settlement) mapping for EBS Markets on CME Globex. |
/v3/tradingSessionValueDates?instrumentguidInt= | Trading Session Value Dates | Returns trade date to value date (date of settlement) mapping for a specific instrument for EBS Direct or EBS Markets on CME Globex . |
/v3/products?marketSegmentId= | Market Segment Id | Returns all products on Market Segment Id
|
Record Relationships
Product and instrument records are tied together by the following relationship definitions:
Product
Underlying
Overlying
Instruments
BTIC
TACO
TAS
TAM
Instruments:
Underlying
Overlying
Product
Relationships function differently for different product and instrument types. The links will only appear in the results if applicable; for instance, a BTIC product that doesn't have any related overlying products will not return Overlying→Overlying.
BTIC and BTIC+ products settling into the same underlying product (e.g. E-mini S&P 500 Futures). In this scenario clients should note there are two relationships to consider:
The BTIC+ on E-mini Standard and Poor's 500 Stock Price Index Futures
Underlying of the BTIC+ is the BTIC
bticUnderlying a BTIC on E-mini-Standard and Poor's 500 Stock Price Index Futures
underlying a E-mini-S&P 500 Futures
See Record Relationship Linkage Examples for examples of record relationship types and returned links.
Product Relationships
Customers must drill down to the outright product level to determine the underlying market for TAS, TAM, BTIC, TACO, and REPO products.
Type | Underlying | Overlying | Instruments | BTIC Underlying | TAS Underlying | TAM Underlying | TACO Underlying |
|---|---|---|---|---|---|---|---|
Future Outright | Not present | References to all products related to the outright future
| All listed instruments on the outright future | Not present | Not present | Not present | Not present |
Future Spread | Leg construction information for the future spread, with references to the outright future legs
| Only present for spreads that are used as legs for spread-of-spreads (e.g., Future Bundles as legs of Bundle Spreads) Leg construction information, with references to the future spread legs
| All listed instruments for the future spread | Not present | Not present | Not present | Not present |
Option Outright | Relationship information for the option outright
| Not present | All listed instruments for the outright option | Not present | Not present | Not present | Not present |
Basis Trade at Index Close (BTIC) Futures | Not present | References to all products related to the BTIC outright future
| All listed instruments for the BTIC outright future | Underlying product for the BTIC (e.g., E-mini S&P 500 future for the BTIC on E-mini S&P 500) | Not present | Not present | Not present |
Trade at Cash Open (TACO) Futures | Not present | References to all products related to the TACO outright future
| All listed instruments for the TACO outright future | Not present | Not present | Underlying product for the TACO future (e.g., E-mini S&P 500 future for the TACO on E-mini S&P 500) | |
Trade at Settlement (TAS) Futures | Not present | References to all products related to the TAS outright future
| All listed instruments for the TAS outright future | Not present | Underlying product for the TAS future (e.g., Sweet Crude Oil futures for the TAS Sweet Crude Oil) | Not present | Not present |
Trade at Marker (TAM) Futures | Not present | References to all products related to the TAM outright future
| All listed instruments for the TAM outright future | Not present | Not present | Underlying product for the TAM future (e.g., Sweet Crude Oil futures for the TAM London Sweet Crude Oil) | Not present |
REPO | Underlying = Physical Collateral of the REPO (e.g. US Government Bonds) | Not present | All listed instruments for the REPO | Not present | Not present | Not present | Not present |
US Treasury Actives and European Government Bonds | Not present | References to all products related to the US Actives Outrights
| All listed instruments for the US Actives | Not present | Not present | Not present | Not present |
eFix Matching Service Product | References to all products related to the eFix Matching Service Product
| Not present | All listed instruments for the eFix Matching Service products. | Not present |
How was your Client Systems Wiki Experience? Submit Feedback
Copyright © 2024 CME Group Inc. All rights reserved.