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.
Asset Class | Format | CSV | CSV | CSV | CSV |
IRS | FpML | Trade register | Simple | Basic | Delta Ladder |
F&O | FIXML | Simple | |||
FX | FIXML | Simple |
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) ; F&O (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
IRS (CSV format) | # headers |
Trade Register | 200+ |
Simple | 21 |
Basic | 9 |
Delta Ladder | 28 |
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.
F&O (CSV format) | # headers |
Simple | 12 |
For Futures & Options trades can be represented using ticker information/product code or clearing code and maturity code, in addition to quantity.
FX (CSV format) | # headers |
Simple | 9 |
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
CAD Canadian Dollar
CHF Swiss Franc
CZK Czech Koruna
DKK Danish Krone
EUR Euro Member Countries (EURO)
GBP British Pound Sterling
HKD Hong Kong Dollar
HUF Hungary Forint
JPY Japanese Yen
MXN Mexican Peso
NOK Norwegian Krone
NZD New Zeeland Dollar
PLN Polish Zloty
SEK Swedish Krona
SGD Singapore Dollar
USD United States Dollar
ZAR South African Rand
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
Swaptions fields are optional and should only be populated when a user would like to upload a Swaption trade.
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
*Only used for BRL zero coupon swaps
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
CAD CAD-BA-CDOR
CHF CHF-LIBOR-BBA
CZK CZK-PRIBOR-PRBO
DKK DKK-CIBOR-DKNA13; DKK-CIBOR2-DKNA13
EUR EUR-EURIBOR-Reuters; EUR-EURIBOR-Telerate (Incoming); EUR-EONIA-OIS-COMPOUND (OIS swaps only)
GBP GBP-LIBOR-BBA; GBP-WMBA-SONIA-COMPOUND (OIS swaps only)
HKD HKD-HIBOR-HKAB
HUF HUF-BUBOR-Reuters
JPY JPY-LIBOR-BBA; JPY-TONA-OIS-COMPOUND (OIS swaps only)
MXN MXN-TIIE-Banxico
NOK NOK-NIBOR-NIBR
NZD NZD-BBR-FRA
PLN PLN-WIBOR-WIBO
SEK SEK-STIBOR-SIDE
SGD SGD-SOR-VWAP; SGD-SOR-Reuters
USD USD-LIBOR-BBA; USD-Federal Funds-H.15 (Basis swaps only); USD-Federal Funds-H.15-OIS-COMPOUND (OIS swaps only)
ZAR ZAR-JIBAR-SAFEX
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
See IRS supported products list to determine the acceptable index tenors for each product type and currency.
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
See IRS supported products list to determine the acceptable payment frequencies for each product type and currency.
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
See IRS supported products list to determine the acceptable compound methods for each product type and currency.
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 F&O
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 F&O 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
CAD Canadian Dollar
CHF Swiss Franc
CLP Chilean Peso
CNY Chinese Renminbi
COP Colombian Peso
CZK Czech Koruna
DKK Danish Krone
EUR Euro Member Countries (EURO)
GBP British Pound Sterling
HKD Hong Kong Dollar
HUF Hungary Forint
IDR Indonesian Rupiah
ILS Israeli Shekel
INR Indian Rupee
JPY Japanese Yen
KRW Korean Won
MXN Mexican Peso
NOK Norwegian Krone
NZD New Zeeland Dollar
PEN Peruvian Nuevo Sol
PHP Philippines Peso
PLN Polish Zloty
RUB Russian Ruble
SEK Swedish Krona
SGD Singapore Dollar
THB Thai Baht
TWD Taiwan Dollar
USD United States Dollar
ZAR South African Rand
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
BRL_CDIOIS_1D_ERS
BRL_CDI_1D_ERS
CAD_BA_3M_ERS
CHF_LIBOR_6M_ERS
CZK_PRIBOR_6M_ERS
DKK_CIBOR_6M_ERS
EUR_EONIA_1D_ERS
EUR_EURIBOR_1M_ERS
EUR_EURIBOR_3M_ERS
EUR_EURIBOR_6M_ERS
GBP_LIBOR_1M_ERS
GBP_LIBOR_3M_ERS
GBP_LIBOR_6M_ERS
GBP_SONIA_1D_ERS
HKD_HIBOR_3M_ERS
HUF_BUBOR_6M_ERS
JPY_LIBOR_3M_ERS
JPY_LIBOR_6M_ERS
JPY_TONAR_1D_ERS
MXN_TIIEOIS_1M_ERS
MXN_TIIE_1M_ERS
NOK_NIBOR_6M_ERS
NZD_BKBM_3M_ERS
PLN_WIBOR_6M_ERS
SEK_STIBOR_3M_ERS
SGD_SOR_6M_ERS
USD_FEDFUNDS_1D_ERS
USD_LIBOR_1M_ERS
USD_LIBOR_3M_ERS
USD_LIBOR_6M_ERS
ZAR_JIBAR_3M_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
CAD Canadian Dollar
CHF Swiss Franc
CZK Czech Koruna
DKK Danish Krone
EUR Euro Member Countries (EURO)
GBP British Pound Sterling
HKD Hong Kong Dollar
HUF Hungary Forint
JPY Japanese Yen
MXN Mexican Peso
NOK Norwegian Krone
NZD New Zeeland Dollar
PLN Polish Zloty
SEK Swedish Krona
SGD Singapore Dollar
USD United States Dollar
ZAR South African Rand
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:
91D
183D
274D
365D
457D
548D
639D
731D
1096D
1461D
1826D
2192D
2557D
2922D
3287D
3653D
4383D
5479D
7305D
9131D
10958D
14610D
18263D
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 F&O 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.
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
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.