CME STP BaCE API Functional Specification
The CME STP BaCE API uses standard Simple Object Access Protocol (SOAP) Web services calls secured by Transport Layer Security (TLS) 1.2. The API supports both querying and submitting data. All API calls must be must be encoded for SOAP.
In this specification, only the example for changing a user password is encoded for SOAP. For clarity, all other examples are unencoded.
Do not add UTF encoding. CME STP BaCE adds UTF-16 encoding during processing.
The following topics describe each function available through the API and the supporting XML methods and elements.
Contents
Architecture
The following diagram shows the basic communications model of CME STP BaCE API.
API Functions
You can submit the following types of data as XML through the API:
When you submit trade records to CME STP BaCE, you can use either standard CME STP BaCE reference data values, or your company’s own data values, which are mapped by CME STP BaCE.
The following table summarizes the actions available from the API, which are described in greater detail below.
Action | API Method |
---|---|
saveDeals(username, password, CHML.Deals.Deal) | |
Verify and reject trades, and update reference numbers for trades | updateDeals(username, password, CHML.CHRequest.UpdateRequest) |
getReferenceData(username, password, CHML.CHRequest.RefDataQuery) | |
changePassword(username, password, newPassword) |
API Methods and XML Elements
The following diagram maps the given API method to its corresponding XML element.
Uniquely Identifying Trades
You use the following trade identifiers to uniquely identify a trade in CME STP BaCE:
Trade Identifier | Description | Example - New Trade | Example - Amended Trade |
---|---|---|---|
CHDealID | CME STP BaCE uses this to uniquely identify a trade. This ID does not change across multiple versions of a trade. | CHDealID="10261356" | CHDealID="10261356" |
CHTransactionID | CME STP BaCE uses this to uniquely identify a version of a trade. This ID changes for each version of a trade, and it is globally unique. | CHTransactionID=""1242334" | CHTransactionID=""1258794" |
CHVersionID | CME STP BaCE uses this to uniquely identify the version number of the trade. It is incremented with each trade amendment. | CHVersionID="1" | CHVersionID="2" |
Submitting Trade Records (saveDeals)
Use the saveDeals method to submit trade records to CME STP BaCE,
Syntax
saveDeals(username, password, CHML.Deals.Deal)
Parameters
Parameter | Description | Type |
---|---|---|
username | Username provided by CME STP BaCE. Usually a username dedicated to the API. | string |
password | Password provided by CME STP BaCE. | string |
CHML.Deals.Deal | An XML string that represents one or more deals (trade records). For a complete list of request parameters, refer to "Submitting trade records (CHML.Deals.Deal)" in the CME BaCE XML Schema Reference. To submit multiple trade records, create the Deals element, which can contain multiple Deal elements. | string |
Example: Broker-Submitted Trade
Updating Trade Records (updateDeals)
Trading companies use the updateDeals method to verify and reject trade records and to update the reference number for a trade.
Syntax
updateDeals(username, password, CHML.CHRequest.UpdateRequest)
Parameters
Parameter | Description | Type |
---|---|---|
username | Username provided by CME STP BaCE. Usually and API dedicated username. | string |
password | Password provided by CME STP BaCE. | string |
CHML.CHRequest.UpdateRequest | An XML string that represents the information to update in the trade. There are three types of update:
| string |
Example: Accept a Single Deal - Submission and Response
Example: Accept Deal and Update Reference Number in a Single Call
Querying Reference Data (getReferenceData)
Use the getReferenceData method to retrieve CME STP BaCE reference data.
Syntax
getReferenceData(username, password, CHML.CHRequest.RefDataQuery)
Parameters
Parameter | Description | Type |
---|---|---|
username | Username provided by CME STP BaCE. Usually a username dedicated to the API. | string |
password | Password provided by CME STP BaCE. | string |
CHML.CHRequest.RefDataQuery | An XML string that represents query parameters. For a complete list of request parameters, refer to "Querying CME STP BaCE for reference-data tables in the database (CHML.CHRequest.RefDataQuery)" in the CME STP BaCE XML Schema Reference. | string |
Filter Attributes
Attribute | Description | Type |
---|---|---|
TableName | Table name to query for reference data. If this is not specified, CME STP BaCE returns all tables in the reference data. | string |
UpdatedSinceDate |
The date and time have the following format: YYYY-MM-DDThh:mm:ss.nnn, for example, 2012-03-05T10:02:24.617 | dateTime |
Example: Retrieving All Reference Data Tables
getReferenceData("acme_api", "***acmepassword***",
"<CHML SchemaVersion="6.2">
<CHRequest>
<RefDataQuery/>
</CHRequest>
</CHML>")
Example: Retrieving All Reference Data Tables that Have Changed Since Given Date
getReferenceData("acme_api", "***acmepassword***",
"<CHML SchemaVersion="6.2">
<CHRequest>
<RefDataQuery
UpdatedSinceDate ="2013-02-01"/>
<RefDataQuery/>
</CHRequest>
</CHML>")
Example: Retrieving only the COMPANY Table
getReferenceData("acme_api", "***acmepassword***",
"<CHML SchemaVersion="6.2">
<CHRequest>
<RefDataQuery
TableName ="COMPANY"/>
<RefDataQuery/>
</CHRequest>
</CHML>")
Change User Password (changePassword)
Use the changePassword method to change a user password.
Syntax
changePassword(username, password, newPassword)
All CME STP BaCE passwords expire after 90 days. CME STP BaCE recommends that all API interfaces use the changePassword method to automatically change the password to avoid API account interruptions.
Parameters
Parameter | Description | Type |
---|---|---|
username | Username provided by CME STP BaCE. Usually an API dedicated username. | string |
password | Password provided by CME STP BaCE. | string |
newPassword | New password. | string |
Example: Change User Password
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ch="http://www.confirmhub.com/ns/ch/v6.2/ch.api">
<soapenv:Header/>
<soapenv:Body>
<ch:changePassword>
<!--Optional:-->
<ch:username>acme_api</ch:username>
<!--Optional:-->
<ch:password>acme_old_password</ch:password>
<!--Optional:-->
<ch:newPassword>acme_new_password</ch:newPassword>
</ch:changePassword>
</soapenv:Body>
</soapenv:Envelope>
Example: Change User Password - Unencoded
changePassword ("acme_api", "acme_old_password", "acme_new_password")
API Error Codes
The following error codes may be returned after calling an API method:
The error code is displayed in the CHResponse.Code element.
The error message is displayed in the CHResponse.Details element.
Error Code | Description | Recommendation |
---|---|---|
3 | This indicates password or account errors. | Generate an alert, pause the service, and inspect your credentials. |
10 | This indicates that the submitted XML document has an unknown format. | Generate an alert. Do not retry the transaction, which is problematic and must be corrected. |
12 | This indicates an error in the request due to invalid XML. This may be caused by one of the following, as indicated in the error message:
| Generate an alert. Do not retry the transaction, which is problematic and must be corrected. |
17 | This indicates an error in the request for one of the following reasons, as indicated in the error message:
| Generate an alert. Do not retry the transaction, which is problematic and must be corrected. |
26 | This indicates an expired password. | Generate an alert, pause the service, and inspect your credentials. Use the changePassword API method to change your password. You can resubmit after changing your password. |
100 | This general service error often indicates connection timeouts or other system issues not captured by other error codes. | Generate an alert, but keep retrying the transaction. The CME STP BaCE API service may be unavailable some nights and weekends for regular maintenance. Please consider this in your alerting mechanism. |
How was your Client Systems Wiki Experience? Submit Feedback
Copyright © 2024 CME Group Inc. All rights reserved.