Page tree
Skip to end of metadata
Go to start of metadata

Steps to Run Margin Calculation

  1. Populate "MarketData" folder with latest IRS Risk Data unzip file "IRSrd.yyyymmdd.zip" available through SFTP --> FIRMPUB/CDSRD
  2. Start "irsServiceMode" and let the application run portfolio
  3. Build a portfolio to meet one of the three sample uploads below
  4. Send request to service
    1. Run: Specify IP Address/Port portfolio
      1. Example:  http://127.0.0.1:8086?Portfolio=(encodedContentHere)
    2. Identify portfolio format to generate from reference system
    3. Encode portfolio payload to HTTP 
    4. Transmit request to service 
      • Send GET Request
      • Include Header: 
        • Host
        • HTTP Version
        • Specify Content Type - all are supported
          • Margin API users may continue using "xml"
        • Connection: Close
    5. Response will include:
      • Content Type
      • Size of Package
      • Payload
    6. Service will respond synchronously for each margin request based on each connection with the service 
  5. Margin calculator will produce one of three outputs
    1. SUCCESS with conc, base, maint - The portfolio margined successfully
    2. SUCCESS without conc, base, maint - There is a formatting issue
    3. FAILURE - There is either a formatting issue and/or a portfolio issue

Sample Code

CME has provided sample annotated code to help licensees understand how to interact with service mode. CME does not plan to make changes to the sample code to support additional programming languages. The sample code can be found in IRSMargin/SampleData/Client/ 

Additional notes

The service mode allows users to make margin call into their local instance of web-service.

To run service mode, user needs to run irsServiceMode application, located in IrsMargin folder. Once run service mode loads IRS risk data and is listening for incoming messages, the user can send in requests via REST API or web service.

When running in service mode, the software supports multiple request message formats.  Users can simply pass the .csv or FIXML formats, FPML is not currently supported. 

There are two main methods to interact in service mode.

  1.  API 
  2. Web Service 

 API 

The Service software supports POST types of requests.

POST

To use POST requests, request must be submitted to http://127.0.0.1:8086/Calc.  “Calc” is case sensitive.  Standard POST headers are all accepted, however the only header that is required is “Content-Length” (case sensitive) and is to accurately define the message body length.  The message is expected in its entirety: chunked encoding is not permitted.  The body may consist of any amount of data, treated as key/value pairs, however the only one required is portfolio (case sensitive), and should be presented as “portfolio=(HTTP encoded portfolio)”.  Note that for POST requests, the portfolio does not have to be HTTP encoded, but it is recommended.  An example of a POST request is below:

The sample service message refer to CORE Margin API messages to show interoperability with Margin API. Some of the features in CORE Margin API such as schema, transaction id, portfolio id will not be required. 

Web Service

Using a web browser, a user can pull up web service located IrsMargin/home folder. See image.

The portfolio can be in csv or fixml format.


Supported Formats:All of the supported service mode message formats are included as .txt files in the IrsMargin/SampleData directory. 

Basic Upload Template - .csv

 This is the minimalist IRS upload template. A description of each field is below. To export a simple upload .csv file, click here.

Name
Description
Comments:
Firm IDID of the Firm- A portfolio is based on FIRM & Account IDExample: "test"
Account IDThis is the account (portfolio) that the trade(s) exist within. Example: 1234
Product Type This field determines the product type of interest rate swapVanilla, FRA, OIS, Basis, ZERO_COUPON
CurrencyThis field determines the currency of the interest rate swap.AUD, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, JPY, MXN, NOK, NZD, PLN, SEK, SGD, USD, ZAR
Effective DateThis field is the start date of the interest rate swapMM/DD/YYYY
Maturity DateThis field is the end or expiration date of the interest rate swap.MM/DD/YYYY
NotionalQuantity of currency units on trade100,000,000
DirectionThis field is based on the fixed rate of the swap. It is used to determine if the account is either paying or receiving the fixed rate P = Pay; R = Receive
Fixed RateThis field is the pre-negotiated rate of the swap, determined by the two parties involved in the trade.  Rate should be expressed as decimal: "0.0425" is 4.25%


Sample Request Message

Sample Request Message for Existing Margin API Users: Users may use Margin API message envelope around well formed .csv file

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:transactionReq xmlns:ns2="http://cmegroup.com/schema/core/1.0" reqUserId="ak"><transaction portfolioId="0" type="TRADE" id="0"><payload encoding="STRING" format="CSV"><string>Firm ID,Account ID,Product Type ,Currency,Effective Date,Maturity Date,Notional,Direction,Fixed RateTEST,1234,Vanilla,AUD,6/3/2015,6/3/2017,10000000,P,0.05
TEST,1234,Vanilla,ZAR,6/3/2015,6/3/2017,10000000,R,0.05
</string></payload></transaction></ns2:transactionReq>

Simple Upload Template B - .csv

This upload template contains more fields. To export a Simple Upload .csv file,click here

Name
Description
Comments
Firm IDID of the Firm- CORE's portfolio is based on FIRM & Account IDExample: TestFirm
Account IDThis is the account (portfolio) that the trade(s) exist within. Example: ACCT123
Product Type This field determines the product type of interest rate swapVanilla, FRA, OIS, Basis, ZERO_COUPON
CurrencyThis field determines the currency of the interest rate swap.*Download IRS Supported Products list from CME CORE for additional information
Effective DateThis field is the start date of the interest rate swapMM/DD/YYYY
Maturity DateThis field is the end or expiration date of the interest rate swap. MM/DD/YYYY
NotionalQuantity of currency units on trade100,000,000
DirectionThis field is based on the fixed rate of the swap. It is used to determine if the account is either paying or receiving the fixed rate P = Pay; R = Receive
Fixed RateThis field is the pre-negotiated rate of the swap, determined by the two parties involved in the trade. "0.0425" is 4.25%
FV Notional*Notional Value used for BRL Zero Coupon Swaps Only 
Leg1 IndexIndex used to express the floating leg reference curve (only required for Basis and FRAs)*Download IRS Supported Products list from CME CORE for additional information
Leg1 Index TenorIndex tenor for floating interest rate reference curve (only required for Basis and FRAs)*Download IRS Supported Products list from CME CORE for additional information
Leg1 PayfreqLeg 1 coupon period frequency*Download IRS Supported Products list from CME CORE for additional information
Leg1 CompMethodLeg 1 coupon period compounding method*Download IRS Supported Products list from CME CORE for additional information
Leg1 SpreadLeg 1 spread over the floating index rate0.0025 = 25 basis points; express basis points in decimal format
Leg2 IndexIndex used to express the floating leg reference curve (populated on all swaps except FRAs)*Download IRS Supported Products list from CME CORE for additional information
Leg2 Index TenorIndex tenor for floating interest rate reference curve (populated on all swaps except when using OIS curve, "1- Day" is implied when left blank*Download IRS Supported Products list from CME CORE for additional information
Leg2 PayfreqLeg 2 coupon period payment frequency*Download IRS Supported Products list from CME CORE for additional information
Leg2 CompMethodLeg 2 coupon period compounding method*Download IRS Supported Products list from CME CORE for additional information
Leg2 SpreadLeg 2 spread over the floating index rate0.0025 = 25 basis points; express basis points in decimal format


Sample Request Message for Existing Margin API Users: Users may use Margin API message envelope around well formed .csv file

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:transactionReq xmlns:ns2="http://cmegroup.com/schema/core/1.2" reqUserId="ab"><transaction portfolioId="123" type="TRADE" id="0"><payload encoding="STRING" format="CSV"><string>Firm ID,Account ID,Product Type,Currency,Effective Date,Maturity Date,Notional,Direction,Fixed Rate,Leg1 Index,Leg1 IndexTenor,Leg1 Payfreq,Leg1 CompMethod,Leg2 Index,Leg2 IndexTenor,Leg2 Payfreq,Leg2 CompMethod,Leg1 Spread,Leg2 Spread
Test,FUTURESPM,Vanilla,USD,9/22/2016,9/22/2026,"100,000,000",P,0.03123,N/A,N/A,6M,NONE,USD-LIBOR-BBA,3M,6M,FLAT,N/A,N/A
Test,FUTURESPM,OIS,USD,9/22/2016,9/22/2026,"10,000,000",P,0.03123,N/A,N/A,1T,NONE,USD-Federal Funds-H.15-OIS-COMPOUND,N/A,1T,NONE,N/A,N/A
Test,FUTURESPM,ZERO_COUPON,USD,9/22/2016,9/22/2026,"10,000,000",P,0.03123,N/A,N/A,6M,NONE,USD-LIBOR-BBA,3M,3M,NONE,N/A,N/A
Test,FUTURESPM,FRA,EUR,9/16/2016,12/16/2017,"10,000,000",P,0.0048,EUR-EURIBOR-Reuters,3M,N/A,N/A,N/A,N/A,N/A,N/A,N/A,N/A
Test,FUTURESPM,Basis,EUR,9/22/2016,9/22/2026,"10,000,000",P,N/A,EUR-EURIBOR-Reuters,3M,3M,NONE,EUR-EURIBOR-Reuters,1M,1M,NONE,0.002463,0.023576
</string></payload></transaction></ns2:transactionReq>

 

Trade Register Format

The trade register format includes all 186 filed headers which are generated when an IRS trade is cleared at the CME. CME trade registers can be downloaded from CME’s secure FTP site. These files can then be copied into the string of a user’s payload and margined via the IRS deployable software. The trade register format is the most detailed version of the three upload formats and is designed to handle any combination of trade attributes and product types.


Use Case: The trade register format should be utilized when a user is looking to perform a detailed portfolio margin analysis for trades which the user has executed and were cleared at the CME.  CME makes IRS trade registers available to clearing members and IRS buy side market participants. 


Special Request Types

Support for variable notional swaps

Two parts in a single service message:

  1. Trade Header (IRS Portfolio)
    1. Trade Details
  2. Notional Schedule Header (IRSNS file)
    Note that trade id needs to be the same on trade ID and notional schedule Sample request message:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:transactionReq xmlns:ns2="http://cmegroup.com/schema/core/1.2" reqUserId="ab"><transaction portfolioId="${marginPortfolio}" type="TRADE" id="0"><payload encoding="STRING" format="CSV"><string>Firm ID,Account ID,ClearedTradeId,Product Type ,Currency,Effective Date,Maturity Date,NotionalType,Notional,Direction,Fixed Rate,Leg1 Index,Leg1 IndexTenor,Leg1 Payfreq,Leg1 CompMethod,Leg2 Index,Leg2 IndexTenor,Leg2 Payfreq,Leg2 CompMethodTest,1234,5678,Vanilla ,USD,6/18/2013,6/18/2025,Schedule,"23,000,000.00",P,0.03123,N/A,N/A,3M,NONE,USD-LIBOR-BBA,3M,3M,FLAT
Cleared Trade ID,Step Date,Step Value
5678,6/18/2013,"23,000,000.00"
5678,9/18/2013,"22,950,000.00"
5678,12/18/2013,"22,470,832.98"
5678,3/18/2014,"21,991,665.97"
5678,6/18/2014,"21,512,498.95"
5678,9/18/2014,"21,033,331.93"
5678,12/18/2014,"20,554,164.91"
5678,3/18/2015,"20,074,997.90"
5678,6/18/2015,"19,595,830.88"
5678,9/18/2015,"19,116,663.86"
5678,12/18/2015,"18,637,496.84"
5678,3/18/2016,"18,158,329.83"
5678,6/18/2016,"17,679,162.81"
5678,9/18/2016,"17,199,995.79"
5678,12/18/2016,"16,720,828.77"
5678,3/18/2017,"16,241,661.76"
5678,6/18/2017,"15,762,494.74"
5678,9/18/2017,"15,283,327.72"
5678,12/18/2017,"14,804,160.70"
5678,3/18/2018,"14,324,993.69"
5678,6/18/2018,"13,845,826.67"
5678,9/18/2018,"13,366,659.65"
5678,12/18/2018,"12,887,492.63"
5678,3/18/2019,"12,408,325.62"
5678,6/18/2019,"11,929,158.60"
5678,9/18/2019,"11,449,991.58"
5678,12/18/2019,"10,970,824.56"
5678,3/18/2020,"10,491,657.55"
5678,6/18/2020,"10,012,490.53"
5678,9/18/2020,"9,533,323.51"
5678,12/18/2020,"9,054,156.49"
5678,3/18/2021,"8,574,989.48"
5678,6/18/2021,"8,095,822.46"
5678,9/18/2021,"7,616,655.44"
5678,12/18/2021,"7,137,488.43"
5678,3/18/2022,"6,658,321.41"
5678,6/18/2022,"6,179,154.39"
5678,9/18/2022,"5,699,987.37"
5678,12/18/2022,"5,220,820.36"
5678,3/18/2023,"4,741,653.34"
5678,6/18/2023,"4,262,486.32"
5678,9/18/2023,"3,783,319.30"
5678,12/18/2023,"3,304,152.29"
5678,3/18/2024,"2,824,985.27"
5678,6/18/2024,"2,345,818.25"
5678,9/18/2024,"1,866,651.23"
5678,12/18/2024,"1,387,484.22"
5678,3/18/2025,"908,317.20"
</string></payload></transaction></ns2:transactionReq>

Brazilian Real (Zero Coupon Swaps)

 

Note: FV Notional is required on simple upload. This can be calculated using the equation below:

 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:transactionReq xmlns:ns2="http://cmegroup.com/schema/core/1.0" reqUserId="ak">
    <transaction portfolioId="${marginPortfolio}" type="TRADE" id="0"><payload encoding="STRING" format="CSV">
        <string>Firm ID,Account ID,ClearedTradeId,Product Type ,Currency,Effective Date,Maturity Date,Notional,Direction,Fixed Rate,Leg1 Index,Leg1 IndexTenor,Leg1 Payfreq,Leg1 CompMethod,Leg2 Index,Leg2 IndexTenor,Leg2 Payfreq,Leg2 CompMethod,Leg1 Spread,Leg2 Spread,FV_Notional
Test,1234,1D BRL,ZERO_COUPON,BRL,9/6/2011,9/6/2021,"10,000,000",P,0.03123,N/A,N/A,1T,NONE,BRL-CDI,N/A,1T,NONE,N/A,N/A,1234
</string></payload></transaction></ns2:transactionReq>

IRS and Futures 

Cross margining with Futures, wherein users can allocate futures into OTC account to reduce margin requirements is supported as well. Note the firm id and account id in futures upload should match with IRS portfolios. Also, margin type should be ‘OTC’ for the software to margin futures positions via IRS model instead of SPAN. NOTE, exchange, clearing code and  period code,  are required fields where as Ticker Symbol and Product Name are optional.

Following products are utilized for Cross Margining

  • All OTC IRS Swaps
  • Futures
    • Eurodollar Futures
    • US Treasury Bond
    • 10 year US Treasury Note
    • 5 year US Treasury Note 
    • 2 year US Treasury Note 
    • Ultra 10 year US Treasury Note
    • 30 day Fed Funds

Sample Message for Margin API users

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:transactionReq xmlns:ns2="http://cmegroup.com/schema/core/1.0" reqUserId="ab">
<transaction portfolioId="${marginPortfolio}" type="TRADE">
<payload encoding="STRING" format="CSV">
<string>
Firm Id,Acct Id,Exchange,Ticker Symbol,Product Name,CC Code,Period Code,Put / Call,Strike,Underlying Period Code,Net Positions,Margin Type
Test,1234,CME,GEZ9,,ED,201912,,,,1000,OTC
</string>
</payload>
</transaction>
<transaction portfolioId="${marginPortfolio}" type="TRADE">
<payload encoding="STRING" format="CSV">
<string>
Firm ID,Account ID,ClearedTradeId,Product Type ,Currency,Effective Date,Maturity Date,Notional,Direction,Fixed Rate,Leg1 Index,Leg1 IndexTenor,Leg1 Payfreq,Leg1 CompMethod,Leg2 Index,Leg2 IndexTenor,Leg2 Payfreq,Leg2 CompMethod,Leg1 Spread,Leg2 Spread
Test,1234,Vanilla ,Vanilla ,USD,9/22/2016,9/22/2026,"100,000,000",P,0.03123,N/A,N/A,6M,NONE,USD-LIBOR-BBA,3M,6M,FLAT,N/A,N/A
</string>
</payload>
</transaction>
</ns2:transactionReq>

Historical Margin Analysis: Run Service Mode with Multiple Risk Data Sets 

This feature provides a mechanism to perform historical margin analysis. Multiple market data file can be loaded within single instance of software. This eliminates the need to keep updating the market data folder when a user wants to run margin analysis for different dates. To take advantage of this features, follow the instructions below.

 

For both batch mode and service mode, you have the ability to specify the default folders by either tweaking a setting found in IrsMargin.ini, or by specifying an application startup parameter.

The new ini setting, by default, is:IrsMargin.Default.MarketDataFileName=DeployableData.zip

       The way to specify default market files at the command line is with the -f parameter for either batch or service:

                ./irsServiceMode -f DefaultData.zip

       The -f parameter can be a list of multiple files and directories (provided the directory is an exact match and appears to have our expected structure) if separated by a comma and contain no spaces:

                   ./irsServiceMode -f irsrd.20170201.nr.zip,irsrd.20170202.nr.zip,Data  - This would load 2 files and a folder called “Data”

The -f parameter can specify partial matches for files:

                  ./irsServiceMode -f 201701 - This would load all the zip files containing “201701” in their filename in the market data folder

                   ./irsServiceMode -f zip         - This would load all the zip files in the market data folder

 A few notes about partial matching and the -f parameter:

  • Partial matching only works with files.  Directories need to be exactly specified.
  • All files and directories need to live in the market data folder.  You can change the default market data folder location, but the data will need to live there.
  • A point in time, whether from a zip archive or directory, may only be loaded once.  In other words, no multiple “20170301” points in time.  It wouldn’t matter if one is NR and the other Prod.
  • Wildcards are not supported.  So “*201601*” or “*2017020?.nr.zip” won’t work.
  • Market data zip archives are now extracted as the name of the zip file with a “.dir” extension.  Note these extracted folders are not cleaned up by DML as of this point.  They will be reused though if the software can determine the data matches what the archive file name indicates.
  • Take caution with this setting: with an argument of “-f i” would load any zip file found with an ‘i’ in the file name if found in the market data folder.

For service mode, the market data file with the latest point in time will serve as the default.  If users want to target a different market data file, they will need to use the XML envelope format for your request. A new “pit” attribute that would need to be specified in the input message.  For example: 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:transactionReq xmlns:ns2="http://cmegroup.com/schema/core/1.2" reqUserId="ab"><transaction portfolioId="123" type="TRADE" id="0" pit="2016-02-21"><payload encoding="STRING" format="CSV"><string>Firm ID,Account ID,Product Type,Currency,Effective Date,Maturity Date,Notional,Direction,Fixed Rate,Leg1 Index,Leg1 IndexTenor,Leg1 Payfreq,Leg1 CompMethod,Leg2 Index,Leg2 IndexTenor,Leg2 Payfreq,Leg2 CompMethod,Leg1 Spread,Leg2 Spread
Test,FUTURESPM,Vanilla,USD,9/22/2016,9/22/2026,"100,000,000",P,0.03123,N/A,N/A,6M,NONE,USD-LIBOR-BBA,3M,6M,FLAT,N/A,N/A
</string></payload></transaction></ns2:transactionReq>

Note that a single request may not contain differing points in time.  Those will need to be separated by separate request.

It’s not possible to select a point in time other than the default when sending raw CSV requests.  

If user does not specify a point in time in the XML envelope format or when using a simple CSV request, the user gets a default point in time.

A new end point in service mode,  this is a simple page that will indicate what points in time the service currently has available and which is the default.  Below is an example:

In service mode, erroneous requests will be responded with status 200 (ok). Below is an example of an invalid response (but still status 200 - ok) due to a bad point in time specified on a request:

In service mode, program arguments have been added.  To see the listing of possible args, type “irsServiceMode /?” (similar to batch mode).  Note that the IP and Port can now be changed via program arguments, but will not permanently overwrite what’s in the IrsMargin.ini: they’re only for the session.

 

Incremental Margin Analysis

This feature lets a user do incremental or what-if analysis. Adding a trade incrementally to an existing portfolio of 10 trades required a user to send 11 trades to the deployable library to get margin numbers. However, using this feature the user can cache the margin calculation from first 10 trades and then send the incremental 1 trade to the library. This significantly improves performance for users who might load EOD book to the library and then perform incremental analysis to design a strategy.

A flag (returnMargincache="1") in Service Mode activates the service to return margin cache data along with calculated margin numbers. This will only work if the flag (returnMargincache="1") is present in the XML envelope. A raw csv request does not return margin cache.

See example below on XML envelope to activate this feature:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ns2:transactionReq xmlns:ns2="http://cmegroup.com/schema/core/1.2" reqUserId="ab"><transaction portfolioId="123" type="TRADE" id="0" returnMarginCache="1" ><payload encoding="STRING" format="CSV"><string>Firm ID,Account ID,Product Type,Currency,Effective Date,Maturity Date,Notional,Direction,Fixed Rate,Leg1 Index,Leg1 IndexTenor,Leg1 Payfreq,Leg1 CompMethod,Leg2 Index,Leg2 IndexTenor,Leg2 Payfreq,Leg2 CompMethod,Leg1 Spread,Leg2 Spread
Test,FUTURESPM,Vanilla,USD,9/22/2016,9/22/2026,"100,000,000",P,0.03123,N/A,N/A,6M,NONE,USD-LIBOR-BBA,3M,6M,FLAT,N/A,N/A
</string></payload></transaction></ns2:transactionReq>

When this request is sent in, the service responds with margin numbers and margin cache (highlighted in yellow)


Note the margin cache is encrypted. A user can now include (copy and paste into new request) this margin cache for further margin calculations. Deployable Library will match, ‘Firm id’, ‘Account id’ and ‘point in time’ in the margin cache to the incremental trade(s) and add the incremental trade to existing margin cache numbers to give new margin numbers. 


 

  • No labels