Margin Service API - Developer Guide

Developers new to CME Group's Margin Service API can refer to this flowchart for development guidance. Hyperlinks take you to examples and further information where appropriate.    

Margin API Input Formats

A user of Margin API can specify transactions in FIXML, FpML and CSV formats. Multiple formats are supported for each asset class.

Financial Products Markup Language (FpML)

FpML is an XML message standard for the OTC derivatives industry. This API supports a CME-specific flavor of FpML based on the FpML 5.4 specification.

FIXML

Financial Information eXchange protocol is an electronic communications protocol. This API supports standard FIXML following the FIXML 5.0 SP2 specification

Trade Register CSV Format

This format contains 186 headers (fields) and contains every possible detail of the trade. The trade register format is the most detailed version of the upload formats and is designed to handle any combination of trade attributes and product types.

Simple CSV Format

This format contains fewer headers (fields); IRS (21) ; Futures and Options (12); FX(9) which will be used to determine the structure and composition of the portfolio(s) that will be used for margin analysis. The software’s defaulting logic will examine the required fields provided and default the remaining attributes of the trade(s) in order to calculate a margin result for the overall portfolio(s).

Basic CSV Format

 The basic upload format for IRS includes 9 field headers which will be used to determine the structure and composition of the portfolio(s) that will be used for margin analysis. The software’s defaulting logic will examine these fields and default the remaining attributes of the trade(s) in order to calculate a margin result for overall portfolio(s). The defaulting logic is designed to obtain the most generic version of the interest rate swap. This basic upload format is designed to be used for Vanilla, FRA, and OIS swaps.

Asset Class Inputs

A user has options in the amount of detail they want to provide (as input) to represent a trade. By using the Basic format a user only provides 9 headers, which identify account, product type, currency, notional amount, direction and rate. API defaults the remaining fields to build a Trade Register for the solver. So unless a user is trying to model a unique IRS trade, the easiest input format would be Basic CSV format with 9 fields. Alternatively, using existing Trade Registers, for assets cleared through CME, would work well to check margin requirements.

Delta Ladder is the change of IRS portfolio value given a 1 basis point change to the underlying. Delta Ladder uses currency curves to compute the value of a portfolio at a given date. A Delta Ladder file input will provide a very quick response for margin calculation. 

For Futures & Options trades can be represented using ticker information/product code or clearing code and maturity code, in addition to quantity.

For FX, either ticker or Clearing code is required in addition to long and/or short notional values and maturity date.

Basic Upload Fields for IRS

Firm ID

Description:         ID of the Firm- CORE's portfolio is based on FIRM & Account ID.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

Account ID         

Description:        This is the account (portfolio) that the trade(s) exist within.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

Product Type

Description:        This field determines the product type of interest rate swap.

Format:              Field contents must be in the format noted in the Field Header column below.

Examples(s):      Field Header                     Description

                                FRA                              Forward Rate Agreement Swap

                                OIS                               Overnight Index Swap

                                Vanilla                           Vanilla Swap

                                Basis                             Basis Swap

                                ZERO_COUPON           Zero Coupon Swap 

Currency             

Description:        This field determines the currency of the interest rate swap.

Format:               Field contents must be in the format noted in the Field Header column below. 

Example(s):        Field Header                     Description

                              AUD                                       Australian Dollar              

Effective Date 

Description:        This field is the start date of the interest rate swap.

Format:              MM/DD/YYYY; M/D/YYYY            

Example(s):        07/09/2015; 7/9/2015

Maturity Date

Description:        This field is the end or expiration date of the interest rate swap.

Format:              MM/DD/YYYY, M/D/YYYY

Example(s):        07/09/2015; 7/9/2015

Notional

Description:        This field is the total value of the underlying position’s assets.

Format:               Field contents must be numerical and rounded to two decimal places.

Example(s):        100,000,000; 100,000,000.00; 100000000

Direction

Description:        This field is based on the fixed rate of the swap. It is used to determine if the party that is executing the swap is either paying or receiving the fixed rate.

Format:               Field contents must be in the format below.

Example(s):        Pay, Receive; PAY, RECEIVE; P, R

Fixed Rate

Description:        This field is the pre-negotiated rate of the swap, determined by the two parties involved in the trade.

Format:               Field contents must be in decimal format as shown in the Percentage in Decimal Format below.

Example(s):        Percentage                         Percentage in Decimal Format

                                100%                                    1.0         

                                95%                                        .95

                                10.58%                                   .1058

                                1.5568%                                 .015568

                                .08%                                       .0008    

Swaptions Specific Fields

Buy_Sell

Description:        This field indicates if the executing party is buying or selling the right to enter in to the underlying swap at expiration.

Format:               Field contents must be in the format below.

Example(s):        Buy, Sell; BUY, SELL; B, S

Premium_Payment_Amount

Description:        This field indicates the amount of premium paid, or to be paid, upon execution of the Swaption trade. 

Format:               Field contents must be numerical and rounded to two decimal places.

Example(s):        100,000,000; 100,000,000.00; 100000000

Premium_Payment_Date

Description:        This field indicates the date in which the premium was, or is to be, paid.

Format:               MM/DD/YYYY; M/D/YYYY            

Example(s):        07/09/2015; 7/9/2015

Expiration_Date

Description:        This field indicates the date in which the Swaption will expire.

Format:               MM/DD/YYYY; M/D/YYYY            

Example(s):        07/09/2015; 7/9/2015

Simple Upload Fields for IRS

FV Notional*

Description:        This field is the total future value of the underlying position’s assets.

Format:               Field contents must be numerical and rounded to two decimal places.

Example(s):        100,000,000; 100,000,000.00; 100000000

Cleared Trade ID

Description:        This field is the unique identifier for the trade (optional).

Format:               Field contents must be alphanumeric and can contain symbols.

Example(s):        1234; Abcd; AB1234 #; AB_1234

Leg1 Index & Leg2 Index

Description:        These are the indexes that are used to determine the floating rates of the legs of the trade.

Format:               Leg Index must match its base currency and be in the format below. Field contents must be in the format noted in the Index(s) column below.  If NONE, please populate the field with N/A.

Example(s):        Base Currency                             Index(s)

                              AUD                                        AUD-BBR-BBSW

Leg1 IndexTenor & Leg2 IndexTenor

Description:        The length of time used for the rate calculation period of the leg’s index. 

Format:               Two characters; first character is numeric and the second is alphabetic.

Example(s):        1D, 28D, 1M, 3M, 6M, 1Y

Leg1 Payfreq & Leg2 Payfreq

Description:        The payment frequency of the coupon of the leg of the interest rate swap.

Format:              Two characters; first character is numeric and the second is alphabetic. 

Example(s):        1D, 28D, 1M, 3M, 6M, 1Y

Leg1 CompMethod & Leg2 CompMethod

Description:        The method that is used for compounding of the leg of the interest rate swap. 

Format:              Field contents must be in the format below. 

Example(s):        None; Flat; Straight; SpreadExclusive

Leg1 Spread & Leg2 Spread

Description:        The pre-negotiated rate that is applied to the leg of the interest rate swap in addition to the floating index rate.  

Format:               Field contents must be in decimal format as shown in the Percentage in Decimal Format below.

Example(s):        Percentage                         Percentage in Decimal Format

                                100%                                     1.0         

                                95%                                         .95

                                10.58%                                    .1058

                                1.5568%                                  .015568

                                .08%                                        .0008

Simple Upload Fields for Futures and Options

Required Fields:

For futures- it is only necessary to populate one of the following: Ticker, or Maturity Code and Clearing Code, or Maturity Code and Product Name.

For options- it is required to populate the Ticker, or the Clearing Code, Product Name, and option details.
 

Firm ID                

Description:        ID of the Firm- CORE's portfolio is based on FIRM & Account ID.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

Account ID         

Description:        This is the account (portfolio) that the trade(s) exist within.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123
 

Exchange

Description:         Name of CME Group Exchange the contracts are listed with.

Format:               Field contents must be in the format below. 

Example(s):        CME, NYMEX, COMEX, CBT

Ticker Symbol  

Description:        CME Globex ticker symbol associated with the product.

Format:               Field contents must be a valid CME Globex ticker symbol

Example(s):        GEH5                                   Futures ticker

                           GEH5 C0100                        Options ticker

Product Name    

Description:        Name of the futures and options product.  

Format:              Must match the product name (“Desc” column) as specified on CME’s product reference file.   

Example(s):        S&P 500 FUTURES; LIVE CATTLE FUTURES; EURODOLLAR FUTURES; EURODOLLAR OPTIONS

CC Code

Description:        CME Clearing House Product Code.

Format:               Must match the clearing code (“ID” column) specified on CME’s product reference file.

Example(s):        CC Code                                               Product Name

                                SP                                                  S&P 500 FUTURES

                                48                                                   LIVE CATTLE FUTURES

                                ED                                                  EURODOLLAR FUTURES

                                ED                                                  EURODOLLAR OPTIONS

Period Code

Description:        Value date for consummating the forward transaction (contract date).

Format:               YYYYMM; YYYYMMDD if applicable (select futures and options contracts)

Example(s):        201512, 201603, 20150710, 20150814

Put / Call

Description:        Whether the option trade is a PUT or CALL.

Format:               P or C / PUT or CALL/ Put or Call. 

Example(s):        P, C, PUT, CALL, Put, Call

Strike

Description:        Strike price for options.

Format:               Field contents must be numerical and also match strike price format specified for the option contract (“InstrmtStrkPx” column) as defined in the product reference file. 

Example(s):        111, 112.75, 106.125  

Underlying Period Code

Description:        Period Code for the Underlying Future.

Format:              YYYYMM; YYYYMMDD if applicable (select futures and options contracts)

Example(s):        201512, 201603, 20150710, 20150814
 

Net Positions

Description:        Determines the direction of the net position: negative equals a short position, positive equals a long position.

Format:              Must be an integer. 

Example(s):        0, 10, 100, -100, -100000

Margin Type

Description:        FUT for Futures in SEG account, OTC for futures in the PM account.

Format:              Field contents must be in the format below. 

Example(s):        FUT, OTC

Clearing Firm                    

Description:        ID of the Firm- CORE's portfolio is based on FIRM & Account ID.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

Account Number            

Description:        This is the account (portfolio) that the trade(s) exist within.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

Notional

Description:        This field is the total value of the underlying position’s assets.

Format:               Field contents must be numerical and rounded to two decimal places.

Example(s):        100,000,000; 100,000,000.00; 10000000

Simple Upload Fields for OTCFX

Firm                      

Description:        ID of the Firm- CORE's portfolio is based on FIRM & Account ID.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

Account              

Description:        This is the account (portfolio) that the trade(s) exist within.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

Ticker   

Description:        CME Globex ticker symbol associated with the product.

Format:               Field contents must be a valid CME Globex ticker symbol

Example(s):        AUDUSD; USDBRL; EURGBP

Long Notional & Short Notional

Description:        This field is the total value of the underlying position’s assets for the long and short currencies.

Format:               Field contents must be numerical and rounded to two decimal places.

Example(s):        100,000,000; 100,000,000.00; 10000000

Long Currency & Short Currency               

Description:        This field determines the currency of the long and short legs of the OTCFX trade.

Format:               Field contents must be in the format noted in the Field Header column below. 

Example(s):        Field Header                     Description

                              AUD                               Australian Dollar              

Exchange

Description:        Name of CME Group Exchange the contracts are listed with.

Format:               Field contents must be in the format below. 

Example(s):        CME

Maturity Date

Description:        This field is the end or expiration date of the interest rate swap.

Format:               MM/DD/YYYY; M/D/YYYY; YYYYMMDD

Example(s):        07/09/2015; 7/9/2015; 20150709
 

Simple Upload Fields for Delta Ladder

Value Date

Description:        This field is the point in time in which the delta values were calculated to create the delta ladder.

Format:              MM/DD/YYYY; M/D/YYYY            

Example(s):        07/09/2015; 7/9/2015

CMF ID                

Description:        ID of the Firm- CORE's portfolio is based on FIRM & Account ID.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

PB Account ID   

Description:        This is the account (portfolio) that the trade(s) exist within.

Format:               Any format of letters, numbers, and special characters.

Example(s):        Test123

Curve Name

Description:        This is the index that is associated with the calculated DV01 values across the various tenor points.

Format:               Field contents must be in the format below

Example(s):        Curve names

                              AUD_BBSW_6M_ERS

Currency             

Description:        This field determines the currency of the curve.

Format:              Field contents must be in the format noted in the Field Header column below. 

Example(s):        Field Header                            Description

                              AUD                                       Australian Dollar              

Tenor Points

Description:        These fields represent the various points along the delta ladder curve that DV01 risk of the portfolio is evaluated at.

Format:               Field contents must be in the format below. 

Example(s):        Tenor points:

Performance

The headers for CSV formats (Trade Register/Simple/Basic) are very specifc and ideally a user should use the templates defined on CME CORE Margin Calculator webpage, as reference for API inputs. If the headers are not in the same format as expected by the API engine, the user will experience errors in loading trades into the engine.

API has a limit of 1000 trades per request. So if a user needs to margin more than 1000 trades, the user will need to do so in steps. Using add Transactions the user will have to enter trades, 1000 at a time. To add more trades, to the same portfolio, a user will update trades(remove old add new) in the add transaction, making sure portfolio id is the same as before.  So a portfolio containing 80,000 trades will require a user to enter trades 80 times using the same portfolio id. To get margin on this portfolio, a user will now POST (submit) the portfolio id to get a margin id. Use GET (poll) with margin id to display margin results.

For FX and futures and options asset class the engine performance does not vary with respect to number of trades.

CME CORE API (REST – based) provides two ways to calculate IRS Margins:

1. Full evaluation that matches CME’s exact end of day calculation.

2. Delta Ladder approximation engine which tends to get within 1-2% of (1) for simple portfolios and 5-10% for more complicated trades.

Delta Ladder should always come back to you in 1 – 2 seconds. The full evaluation depends on portfolio suite but is also very scalable. 

Open

The above graph shows % difference in margins calculated using Simple/Basic CSV on Y axis in comparison to same trade represented in Trade Register format, the X axis represents number of trades.

For a Vanilla IRS, margin results for a trade represented in Trade Register or Simple/Basic format are very close. The difference in results (chart above) is 0.15% higher margin for Simple/Basic CSV format in comparison to the same trade that is represented in Trade Register CSV format.

Note a user has to specify only 9 field headers for Basic CSV format in comparison to 186 field headers for Trade Register CSV format. When using Basic/Simple CSV format API automatically defaults to the most generic version of the swap. If the user intended to model a more customized swap it is best to use Trade Register CSV format. Trade Register is the most detailed representation of a trade, margin results generated using this format is accurate.

Engine Response time 

Open

The above graph shows engine response time to calculate margins in seconds on the Y axis and number of trades on the X axis for two CSV formats, Simple and Trade Register.

The graph shows engine performance scales linearly with number of trades. There is little difference in performance based on input CSV format used.

Margin calculation over API is scheduled to be down every week from Friday 5 pm EST to Sunday 11 pm EST.