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.

Contents

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:

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:

  • CME BrokerTec Reference Data API ID Test Registration - New Release

  • CME EBS Reference Data API ID Test Registration - New Release

• To request access in the Production environment, complete the following forms:

  • CME BrokerTec Reference Data API Registration Form - Production

  • CME EBS Reference Data API ID Registration - Production

• CME Group requires customers to create unique OAuth API IDs for both the New Release and Production environments. 

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.

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. 

Authorized API ID's may access the endpoints in the New Release and Production environments:

New Release Endpoints by Market

Production Endpoints by Market

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. 

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:

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.

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.

Pagination Links

Pagination Metadata

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.

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.

Encoded Examples:

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