Versions Compared

Version Old Version 1 New Version Current
Changes made by

Space Sync for Confluence

Space Sync for Confluence

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The Margin Service API includes incremental margin calculation for OTC Interest Rate Swaps. This feature allows users to conveniently margin newly added trades or remove trades in an existing portfolio. 

The margin response is designed to allow users to easily perform ‘What if’ scenario analysis. The response includes the:   

  • total margin amount

  • base margin amount

  • incremental margin change for the edited trades.

See the following topics on this page:

Table of Contents

API Call Scenarios

Use the API Call to achieve the following:

  • Dynamically measure the change in risk in a portfolio: Incremental Historical Value at Risk (IVAR) is useful for running a base portfolio each day and then adding or removing a subset of trades without having to do a margin rerun.

  • Convenient intraday ‘What-if’ margin analysis: We recommend using the IVAR request by staging portfolios in the evening and running them via a normal margin call.  Once results have been successfully calculated on the base portfolio, the IVAR function can be leveraged throughout the day for ‘What-if’ margin analysis.  

  • Execute ‘What-if’ margin analysis without impacting the state of the portfolio: Any trades that are added or removed to the portfolio via IVAR are simply for calculation purposes and do not change the state of the portfolio. To modify the state of the portfolio, users can use the Add Transactions to commit executed trades to the portfolio, and can use that going forward for ‘What-If’ requests.

Perform a Call

To perform incremental margining, submit a margin request, including the following:

  •  A reference to an existing portfolio ID

  • 1 or more transactions.

  • Transactions with an ID and a status of "DELETED" would be removed from the portfolio for the margin run

  • Transactions without an ID and status of "INSERTED" would be added into the portfolio for the run, just like the all-in-one request

Once this is completed, Margin API calculates margin.  This is asynchronous, so that a user can poll for their margin results after submitting their request.

The margin response includes all the normal amounts of a margin request plus:

  • The initial margin in the base of amounts is assumed to be the total amount (including the changes) 

  • The base amount in the incremental block indicate what the base margin would have been without changes

  • The diff amount in the incremental block indicates the difference between the initial margin in the main block and the base incremental margin

The response also includes the transactions in the request, with a status of either SUCCESS or ERROR to indicate which were included in the request. 

Related Content

Child pages (Children Display)
pageMargin Service API

API Workflow

Gliffy
nameIVAR API Workflow
pagePin1

Margin endpoints

CMEUS: {{API_URL}}/margins

Sample Request and Response Messages

Request - ADD a transaction. This example is adding 3 IRS

Code Blocktitle
IVAR Request ADD
Code Block
<?xml version="1.0" encoding="UTF-8"?>
<core:marginReq xmlns:core="http://cmegroup.com/schema/core/1.2" reqUserId="YourUserId">
<margin portfolioId="123456">
<transactions>
<transaction type="TRADE" id="0" status="INSERTED">
<payload encoding="STRING" format="CSV">
<string>
Firm ID,Position Account ID,ClearedTradeId,Currency,Effective Date,Maturity Date,Notional,Direction,Fixed Rate,FloatingIndex,FloatingIndexTenor,FixedPayFrequency
Test,1234,3M PLN,USD,09/06/2011,09/06/2021,"10,000,000",P,0.03123,USD-LIBOR-BBA,6M,6M
Test,1234,1M PLN,USD,09/06/2011,09/06/2021,"10,000,000",P,0.03123,USD-LIBOR-BBA,6M,6M
Test,1234,6M PLN,USD,09/06/2011,09/06/2021,"10,000,000",P,0.03123,USD-LIBOR-BBA,6M,6M
</string>
</payload>
</transaction>
</transactions>
<amounts ccy="AUD" conc="0.0" init="0.0" maint="0.0" nonOptVal="0.0" optVal="0.0"/></margin></core:marginReq>

Request - DELETE a transaction. This example is adding 3 IRS

Code Blocktitle
IVAR Request Delete
Code Block
<?xml version="1.0" encoding="UTF-8"?>
<core:marginReq xmlns:core="http://cmegroup.com/schema/core/1.2">
	<margin portfolioId="123456">
		<transactions>
			<transaction type="TRADE" id="789123" status="DELETED"/>
			<transaction type="TRADE" id="789124" status="DELETED"/>
		</transactions>
		<amounts ccy="AUD" conc="0.0" init="0.0" maint="0.0" nonOptVal="0.0" optVal="0.0"/>
	</margin>
</core:marginReq>

Response - MARGIN REQUEST ID

After your request you will be returned a Margin Request id - use this to poll for your results:

code

title

What If Margin Response
Code Block
<marginRpt status="PROCESSING">
  <margin id="2345" portfolioId="123" createTime="2013-01-09 12:02:13" updateTime="2013-01-09 12:02:13" />
</marginRpt>

Request - MARGIN GET
You should now poll for your results using the margin id

Code Blocktitle

MARGIN Get for What-If
Code Block
GET /margins/2345 

Response - IRS

Code Blocklanguagexmltitle
What-If Response for IRS
Code Block
languagexml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:marginRpt xmlns:ns2="http://cmegroup.com/schema/core/1.2" status="SUCCESS">
	<margin id="123456" createTime="2013-12-18T14:48:53+00:00" updateTime="2013-12-18T14:49:00+00:00">
		<amounts ccy="USD" conc="0.0000000000" init="2146839.6137499997" maint="2146839.6137499997">
			<incremental initBaseAmt="1549954.0475000022" initDiffAmt="596885.5662499975" maintBaseAmt="1549954.0475000022" maintDiffAmt="596885.5662499975" concBaseAmt="0.0000000000" concDiffAmt="0.0000000000"/>
		</amounts>
	</margin>
</ns2:marginRpt>

 

No Schema Specified Response
Code Block
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:marginRpt xmlns:ns2="http://cmegroup.com/schema/core/1.2" status="SUCCESS">
    <margin settleQual="COMP" id="218891" createTime="2016-02-09T15:10:01+00:00" updateTime="2016-02-09T15:10:09+00:00">
        <amounts ccy="USD" conc="144927.5478010595" init="1323848.6193822473" maint="1203498.7448929521">
            <incremental initBaseAmt="2015052.2727481321" initDiffAmt="-691203.6533658848" maintBaseAmt="1831865.7024983019" maintDiffAmt="-628366.9576053498" concBaseAmt="144927.5478010595" concDiffAmt="0.0000000000"/>
        </amounts>
    </margin>
</ns2:marginRpt>
Schema 1.1 Specified Response
Code Block
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:marginRpt xmlns:ns2="http://cmegroup.com/schema/core/1.1" status="SUCCESS">
    <margin settleQual="COMP" id="218891" createTime="2016-02-09T15:10:01+00:00" updateTime="2016-02-09T15:10:09+00:00">
        <amounts ccy="USD" conc="144927.5478010595" init="1323848.6193822473" maint="1203498.7448929521">
            <incremental initBaseAmt="2015052.2727481321" initDiffAmt="-691203.6533658848" maintBaseAmt="1831865.7024983019" maintDiffAmt="-628366.9576053498" concBaseAmt="144927.5478010595" concDiffAmt="0.0000000000"/>
        </amounts>
    </margin>
</ns2:marginRpt>
Schema 1.3 Specified Response

/MarginServiceApi/1.3/margins/12345

Code Block
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ns2:marginRpt xmlns:ns2="http://cmegroup.com/schema/core/1.3" status="SUCCESS">
    <margin settleQual="COMP" id="12345" createTime="2016-02-09T15:10:01+00:00" updateTime="2016-02-09T15:10:09+00:00">
        <amounts ccy="USD" conc="144927.5478010595" init="1323848.6193822473" maint="1203498.7448929521" skew="99039.9583514053520048037171363830566406">
            <incremental initBaseAmt="2015052.2727481321" initDiffAmt="-691203.6533658848" maintBaseAmt="1831865.7024983019" maintDiffAmt="-628366.9576053498" concBaseAmt="144927.5478010595" concDiffAmt="0.0000000000" skewBaseAmt="99039.9583514053229009732604026794433593" skewDiffAmt="0.0000000000291038304567337036132813"/>
        </amounts>
    </margin>
</ns2:marginRpt>