Margin Service API - What If Analysis

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:

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
Margin Service API - Analytics Margin Service API - Authentication and Entitlement Margin Service API - Developer Guide Margin Service API - Onboarding and Verification Margin Service API - Requests Margin Service API - REST Margin Service API - Types Margin Service API - Use Cases Risk API

API Workflow

Margin endpoints

CMEUS: {{API_URL}}/margins

Sample Request and Response Messages

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

IVAR Request ADD

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

IVAR Request Delete

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

What If Margin Response

<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

MARGIN Get for What-If

GET /margins/2345

Response - IRS

What-If Response for IRS

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

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

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

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