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

1 Architecture
2 API Functions
3 API Methods and XML Elements

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

Action	API Method
Submit trade records	saveDeals(username, password, CHML.Deals.Deal)
Verify and reject trades, and update reference numbers for trades	updateDeals(username, password, CHML.CHRequest.UpdateRequest)
Retrieve reference data	getReferenceData(username, password, CHML.CHRequest.RefDataQuery)
Change a user password	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

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

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

<?xml version="1.0"?>

<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:saveDeals>

<ch:username>adamax1</ch:username>

<ch:*acmepassword>***password12***</ch:acmepassword>

<ch:deals>

<?xml version="1.0"?><CHML SchemaVersion="6.2">

<Deals>

<Deal

Active="1" CommodityID="2" Commodity="Power" DealType="Financial" TradeTypeID="18" TradeType="Power Financial Fixed-For-Float Swap" TradeTypeCode="Fin FFF Swap" CompanyAttn="Duke Energy Ohio Inc" CompanyContact="Don Hughes" CompanyContactNumbers="Telephone 555-555-5555; Fax 555-555-5555" TotalQuantity="1600" TotalQuantityTypeID="7" TotalQuantityType="MWh" TimeZoneID="2" TimeZone="CPT" TradeDate="2013-01-01T08:54:00" DeliveryPointCode="Cin Hub" DeliveryPoint="Cinergy Hub" DeliveryPointID="10" Cleared="1">

<Submitter

CreatedDate="2013-01-01T10:02:24.587" LastModifiedDate="2013-01-01T10:02:24.617" SubmitterTypeID="1" SubmitterTypeName="Broker" SubmitterID="100000" SubmitterName="Adamax Broker 1" SubmitterDealID="1234567B" SubmitterDealIDQualifier="BrokerSoft" BidFlag="0" VersionID="1"

/>

<Period

PeriodOrder="1" UnitQuantity="50" UnitQuantityTypeID="7" UnitQuantityType="MWh" StartDate="2013-01-01" EndDate="2013-12-31"

/>

</Periods>

<Broker

ParentBrokerageCompanyID="100000" ParentBrokerageCompany="Adamax Broker 1" BrokerageCompanyID="100000" BrokerageCompany="Adamax Broker 1" BrokerageCompanyNumbers="Telephone 555-555-5555; Fax555-555-5555" BrokerageCompanyAddress="One Sugar Creek Center Blvd., Suite 700, Sugar Land, TX 77478" BrokerDealID="1234567B" BrokerName="Ben Lundquist" CompanyCommRate="0.01" CompanyComm="16.000" CompanyCommFlatRateFlag="0" CompanyCommCurrencyID="2" CompanyCommCurrency="USD" CompanyCommUnitID="7" CompanyCommUnit="MWh" CompanyTotalAmountDue="16.000" >

<ExecutionSystem

SystemName=”Acme System” SystemTradeID=”999” SystemTradeSubID=”001” ExecutorRole=”Aggressor”

/>

<CounterpartyBroker

ParentBrokerageCompanyID="100000" ParentBrokerageCompany="Adamax Broker 1" BrokerageCompanyID="100001" BrokerageCompany="Adamax Broker 1" BrokerageCompanyNumbers="Telephone 555-555-5555; Fax 555-555-5555" BrokerageCompanyAddress="One Sugar Creek Center Blvd., Suite 700, Sugar Land, TX 77478" BrokerDealID="1234567CB" BrokerName="Bryan McSpadden"

/>

<TradingCompany

CompanyID="100003" Company="Adamax Test Company 4" CompanyCode="Adamax Test Company 4" CompanyTrader="Don Hughes" CompanyTraderNumbers="Telephone 555-555-5555; Fax 555-555-5555" ReferenceNumber="" BidFlag="0" Notes=""

/>

<Counterparty

ReferenceNumber="" BidFlag="1" CompanyID="1027" CompanyCode="Brudner Energy Partners LP" Company="Brudner Energy Partners LP" CompanyTrader="Jeff Coats" CompanyTraderNumbers="Telephone 555-555-5555; Fax 555-555-5555"

/>

<SellerPrice

PriceCurrencyID="2" PriceCurrency="USD" IndexID="14" Index="Midwest ISO's Day-Ahead LMP" IndexLocationID="10" IndexLocation="Cinergy Hub" SellerPriceDisplay="Midwest ISO's Day-Ahead LMP at Cinergy Hub"

/>

<BuyerPrice

Price="38" PriceUnitID="7" PriceUnit="MWh" PriceCurrencyID="2" PriceCurrency="USD" IndexID="14" Index="Midwest ISO's Day-Ahead LMP" IndexLocationID="10" IndexLocation="Cinergy Hub" BuyerPriceDisplay="$38 USD/MWh"

/>

<CommodityType

ProductID="91" Product="Power">

<Power

PowerPeakTypeID="3" PowerPeakType="Off-peak" PowerScheduleTypeID="35" PowerScheduleTypeCode="2x16 EPT" PowerScheduleType="2x16, Saturday-Sunday Hours Ending 08:00-23:00 (EPT), Excluding NERC Holidays"

/>

</CommodityType>

</Deal>

</Deals>

</CHML>

</ch:deals>

</ch:saveDeals>

</soapenv:Body>

</soapenv:Envelope>

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

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:

verify
reject
update reference number

string

Example: Accept a Single Deal - Submission and Response

Submission

updateDeals ("acme_api", "acme_old_password",

"<CHML SchemaVersion="6.2">

<AcceptRequest

CHTransactionID="1242334"/>

</>

</UpdateRequest>

</CHRequest>

</CHML>")

Response

"<CHML>

<CHResponse

Code="0" CHTransactionID="1232332"/>

</CHResponse>

</CHResponses>

</CHML>"

Example: Accept Deal and Update Reference Number in a Single Call

updateDeals ("acme_api", "acme_old_password",

"<CHML SchemaVersion="6.2">

<AcceptRequest

CHTransactionID="1242334"/>

</>

<UpdateRefNumberRequest

CHTransactionID="1242334"

ReferenceNumber="mynum_009988"/>

</>

</UpdateRequest>

</CHRequest>

</CHML")

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

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

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

To retrieve reference data added or updated in the table after a certain date, specify that date in the U.S. Eastern time zone, which may be adjusted for Daylight Savings Time, depending on the time of year.
To retrieve all reference data from this table, you can omit this attribute.

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>

</CHML>")

Example: Retrieving All Reference Data Tables that Have Changed Since Given Date

getReferenceData("acme_api", "***acmepassword***",

"<CHML SchemaVersion="6.2">

<RefDataQuery

UpdatedSinceDate ="2013-02-01"/>

</CHRequest>

</CHML>")

Example: Retrieving only the COMPANY Table

getReferenceData("acme_api", "***acmepassword***",

"<CHML SchemaVersion="6.2">

<RefDataQuery

TableName ="COMPANY"/>

</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

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>

<ch:username>acme_api</ch:username>

<ch:password>acme_old_password</ch:password>

<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

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: XML schema validation error. Deal node not found. Schema version not found. CHML node is empty.	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: Invalid SubmitterTypeID. TradingCompany node is required but not found. Counterparty node is required but not found. Broker node is required but not found. Invalid broker. The expected value of the Broker.BrokerageCompanyID attribute is indicated in the error message. Invalid exchange. The expected value of the Exchange.ExchangeCompanyID attribute is indicated in the error message. Invalid Deal.CommodityId attribute. The value of the attribute is indicated in the error message. Invalid Deal.DealType attribute. The value of the attribute is indicated in the error message. The value must be either Physical or Financial. Invalid Submitter.SubmitterId attribute. The value of the attribute is indicated in the error message. Submitter.BidFlag attribute is required but not found. TradingCompany.BidFlag attribute is required but not found. Counterparty.BidFlag attribute is required but not found. Invalid Submitter.BidFlag attribute. The value of the attribute is indicated in the error message. It must be 0 or 1. Submitter.BidFlag attribute must be the same as TradingCompany.BidFlag. Submitter.BidFlag attribute cannot be the same as Counterparty.BidFlag. The indicated value of the TradingCompany.ReferenceNumber attribute must be the same as the indicated value of the Submitter.SubmitterDealID attribute. TradingCompany.CompanyId attribute is required but not found. Invalid TradingCompany.CompanyId attribute. The value of the attribute is indicated in the error message. Authorization failed, because the specified user is not authorized to submit deal with the specified CHBatchID, CompanyID, CommodityID, and DealType. Submission failed, because it was an attempt to submit the specified version of the deal when a newer version already exists.	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.