NAV

API Documentation

This is the documentation for OpenGamma's REST APIs.

Our Margin Service allows the user to calculate initial margin on a portfolio across a range of central counterparties (CCPs) and methodologies. The following margin methodologies are currently supported:

The service is constantly updated to include the latest changes to these methodologies.

The service can be accessed programmatically through the APIs described below.

Data requirements

To perform margin calculations the only data requirement is:

OpenGamma subscribes to the market data and CCP scenario data necessary to perform calculations for the latest valuation date.

The service provides the following outputs:

Portfolio Formats

Overview

Each calculation methodology supports portfolio data in several formats. These are:

For compatibility across methodologies, it is recommended to use the OpenGamma formats if possible. Each format is described in detail below.

Standard OTC CSV

This example CSV file specifies one FRA and one Swap using the OTC CSV format:

Strata Trade Type, Id Scheme, Id,     Trade Date, Convention,            Buy Sell, Period To Start, Tenor, Fixed Rate, Notional
Fra,               OG,        123401, 2017-06-01, GBP-LIBOR-3M,          Buy,      P2M,             ,      0.5,        1000000
Swap,              OG,        123411, 2017-06-01, GBP-FIXED-1Y-LIBOR-3M, Buy,      P1M,             P5Y,   0.4,        2000000

Our recommended input format is the Strata OTC CSV format which is supported across all methodologies. For full details of the format, please refer to the Strata documentation.

Standard Sensitivity CSV

This example CSV file specifies sensitivity to the GBP discount and GBP-LIBOR-3M forward curves:

(Note that the official Strata format requires a "Sensitivity Type" column, but that is optional in the margin service. When omitted, the type is always ZeroRateDelta.)

Sensitivity Tenor,GBP,GBP-LIBOR-3M
1D,                1,  0.2
1W,                2,  0.3
2W,                3,  0.4
1M,                4,  0.5
3M,                5,  0.6
6M,                6,  0.7
1Y,                7,  0.8
2Y,                8,  0.9
5Y,                5,  0.5
10Y,              -2, -0.2

Our recommended input format is the Strata Sensitivities CSV format which is supported for those methodologies that accept sensitivities. For full details of the format, please refer to the Strata documentation. Using sensitivities instead of portfolio data is especially useful when performance or file size are key requirements.

The valid sensitivity types are:

The CSV format uses a reference to define the curve that the sensitivities refer to. The input can specify one of the following:

The currency is the standard ISO-4217 three-letter code. The floating rate and index are as defined in Strata.

The tenors are defined in terms of days, weeks, months and years. They range from 1D (1 day) to 60Y (60 years). Tenors must not mix day-based and month/year-based. There is no standard set of tenors, as every CCP supports a different set. To handle this, we map the provided set of tenors to those supported by the CCP.

We recommend the following as a good starting point for the tenors to provide. We would advise against providing more tenors than this, and it is usually fine to provide fewer:

1D, 1W, 2W, 1M, 2M, 3M, 4M, 5M, 6M, 9M, 12M, 15M, 18M, 21M, 2Y, 3Y, 4Y, 5Y, 6Y, 7Y, 8Y, 9Y, 10Y, 12Y, 15Y, 20Y, 25Y, 30Y, 35Y, 40Y, 45Y, 50Y, 55Y, 60Y

If multiple files are uploaded with sensitivities, the sensitivities will be merged (providing that the identifier columns in the Strata format are not used).

OpenGamma Strata

Strata is OpenGamma's award-winning open source analytics and market risk library.

Strata includes support for several portfolio input formats which work as standard across every margin methodology.

Serialized Strata portfolios

To serialize a Strata SwapTrade to XML:

SwapTrade trade = createTrade();
String xml = JodaBeanSer.COMPACT.xmlWriter().write(trade);

The XML representation (truncated below) clearly shows the properties of the trade, and could be generated directly if desired:

<?xml version="1.0" encoding="UTF-8"?>
<bean type="com.opengamma.strata.product.swap.SwapTrade">
 <info>
  <id>example~1</id>
  <counterparty>example~A</counterparty>
  <settlementDate>2014-09-12</settlementDate>
  <attributes>
   <entry key="description">Fixed vs Libor 3m</entry>
  </attributes>
 </info>
 <product>
  <legs>
   <item type="RateCalculationSwapLeg">
    <payReceive>Pay</payReceive>
    <accrualSchedule>
     <startDate>2014-09-12</startDate>
     <endDate>2021-09-12</endDate>
     ...

To serialize a Strata SwapTrade to JSON:

SwapTrade trade = createTrade();
String json = JodaBeanSer.COMPACT.jsonWriter().write(trade);

The JSON representation (truncated below) clearly shows the properties of the trade, and could be generated directly if desired:

{
 "@bean": "com.opengamma.strata.product.swap.SwapTrade",
 "info": {
  "id": "example~1",
  "counterparty": "example~A",
  "settlementDate": "2014-09-12",
  "attributes": {
   "description": "Fixed vs Libor 3m"
  }
 },
 "product": {
  "legs": [{
   "@bean": "RateCalculationSwapLeg",
   "payReceive": "Pay",
   "accrualSchedule": {
    "startDate": "2014-09-12",
    "endDate": "2021-09-12",
     ...

For programmatic use alongside Strata, the object representation of a portfolio can be serialized as XML or JSON using Joda-Beans serialization. This serialized form can then be used as the portfolio input to the margin API.

The Java SDK takes care of this serialization automatically, allowing Strata trades and positions to be passed into its API directly. Alternatively, each Strata CalculationTarget (i.e. trade or position) can be serialized individually to Joda-Beans XML or JSON as shown in the examples. The list of serialized trades and positions forms the list of portfolio data to submit to the Margin Service.

Each CCP accepts a different set of CalculationTarget. Types include:

FpML

The FpML XML format for OTC trades is also supported as a portfolio input format. Strata's comprehensive product model is itself based on FpML.

LCH OTC

The LCH OTC methodology supports the following portfolio formats:

Please refer to the LCH secure members area for a detailed description of the LCH Report formats.

LCH OTC SMART CSV format

Example SMART CSV file containing 2 trades:

counterparty,tradeId,tradeType,notional,currency,effectiveDate,terminationDate,payLegType,payLegSpread,payLegPaymentPeriod,payLegDayCountFraction,payLegCompoundingMethod,payLegIndexPeriod,payLegStub,recLegType,recLegSpread,recLegPaymentPeriod,recLegDayCountFraction,recLegCompoundingMethod,recLegIndexPeriod,recLegStub,rollConvention,VNS Details,Delta,Gamma,NPV,Status,Error Message
House,2,IRS,90000000,USD,28/12/2010,28/12/2022,FLOAT,0,3M,ACT/360,,,,FIXED,0.024,,30/360,,,,,,,,,,
House,4,IRS,101750000,USD,13/09/2003,13/09/2033,FIXED,0.0527625,,30/360,,,,FLOAT,0,3M,ACT/360,,,,,,,,,,

This is a CSV format which is the same as that supported by the LCH SMART desktop application.

Column Name Format Description
counterparty
Required		 Text Counterparty name, for reporting purposes only.
tradeId
Required		 Text Unique trade identifier.
tradeType
Required		 OIS, IRS, FRA, ZCS, VNS The type of trade.
notional
Required		 Positive number Notional in local currency.
currency
Required		 ISO currency code Currency of the trade.
effectiveDate
Required		 yyyy-MM-dd, dd-MMM-yyyy, dd/MM/yy, dd/MM/yyyy, yyyy/MM/dd Effective date of the trade. Unadjusted for IRS, adjusted for FRA.
terminationDate
Required		 yyyy-MM-dd, dd-MMM-yyyy, dd/MM/yy, dd/MM/yyyy, yyyy/MM/dd Termination date of the trade. Unadjusted for IRS, adjusted for FRA.
payLegType
Required		 FIXED, FLOAT Pay leg type.
recLegType
Required		 FIXED, FLOAT Receive leg type.
payLegSpread
Required		 If the leg is FIXED then the rate as a percentage (%). If the leg is FLOAT then the spread in basis points (bp). Pay leg spread or rate.
recLegSpread
Required		 If the leg is FIXED then the rate as a percentage (%). If the leg is FLOAT then the spread in basis points (bp). Receive leg spread or rate.
payIndexName A supported index name Pay leg index name.
recIndexName A supported index name Receive leg index name.
payLegPaymentPeriod
Required		 1M, 3M, 6M, 12M Pay leg payment period.
recLegPaymentPeriod
Required		 1M, 3M, 6M, 12M Receive leg payment period.
payLegDayCountFraction 30/360, ACT/ACT, ACT/360, ACT/365, 30E/360 Pay leg day count convention. Defaults from the currency convention if not specified.
recLegDayCountFraction 30/360, ACT/ACT, ACT/360, ACT/365, 30E/360 Receive leg day count convention. Defaults from the currency convention if not specified.
payLegCompoundingMethod FLAT, STRAIGHT Pay leg compounding method.
recLegCompoundingMethod FLAT, STRAIGHT Receive leg compounding method.
payLegIndexPeriod 1M, 3M, 6M, 12M Pay leg index period. Defaults to leg payment period. Not to be set for OIS trades.
recLegIndexPeriod 1M, 3M, 6M, 12M Receive leg index period. Defaults to leg payment period. Not to be set for OIS trades.
payLegStub SHORT_START, LONG_START, SHORT_END, LONG_END Pay leg stub period handling.
recLegStub SHORT_START, LONG_START, SHORT_END, LONG_END Receive leg stub period handling.
rollConvention EOM, IMM, NONE Roll convention. Defaults to NONE.

Any other columns are designed for the SMART desktop application. These may be present but will be ignored. Variable notional swaps are not currently supported by the SMART CSV format.

Eurex OTC

The Eurex OTC methodology supports the following portfolio formats:

Eurex OTC CSV Format

Example Eurex OTC CSV file containing a single trade:

internalTradeID,tradeType,currency,effectiveDate,terminationDate,legType,legSpread,legIndex,interestFixedAmount,notional,paymentPeriod,periodStartVNS,compounding,compoundingIndexPeriod,stub,firstRate,firstInterpolationTenor,secondInterpolationTenor,dayCountMethod,businessDayConvention,paymentCalendar,adjustment,rollMethod,legType,legSpread,legIndex,interestFixedAmount,notional,paymentPeriod,periodStartVNS,compounding,compoundingIndexPeriod,stub,firstRate,firstInterpolationTenor,secondInterpolationTenor,dayCountMethod,businessDayConvention,paymentCalendar,adjustment,rollMethod
1,IRS,EUR,03/06/2015,03/06/2017,floatingLeg,,EURIBOR,,984042345,6M,,,,,,,,ACT/360,MODFOLLOWING,EUTA,,,fixedLeg,0.001214452,,,984042345,6M,,,,,,,,ACT/360,MODFOLLOWING,EUTA,,

This is the standard Eurex OTC CSV format. The following fields are required:

The following trade fields must be specified:

Column Name Format Description
internalTradeId
Required		 Text Unique trade identifier.
tradeType
Required		 OIS, IRS, ZCIS, VNS, FRA The type of trade.
currency
Required		 EUR, CHF, GBP, USD, JPY Currency of the trade.
effectiveDate
Required		 yyyy-MM-dd, d-MMM-yyyy, dMMMyyyy, dd/MM/yy, dd/MM/yyyy, yyyy/MM/dd Effective date of the trade.
terminationDate
Required		 yyyy-MM-dd, d-MMM-yyyy, dMMMyyyy, dd/MM/yy, dd/MM/yyyy, yyyy/MM/dd Termination date of the trade.

In addition, the following leg fields must be specified twice, with one set per leg. The fields for each leg must appear together, with the legType field used to indicate the start of a leg.

Column Name Format Description
legType
Required		 fixedLeg, floatingLeg The leg described by the fields which immediately follow.
legSpread
Required		 If the leg type is fixedLeg then the rate as a percentage (%). If the leg is floatingLeg then the spread in basis points (bp). Leg spread or rate.
legIndex A supported index name Leg index name. Defaults to the index for trade type and currency, except for ZCIS trades where the index must be provided.
interestFixedAmount Number If the leg type is fixedLeg then the known interest amount in the currency of the trade. Required if a rate is not specified in legSpread.
notional
Required		 Positive number The leg notional in local currency.
paymentPeriod 1T for zero-coupon, 1M, 3M, etc Leg payment period. Defaults from the currency convention if not specified.
periodStartVNS yyyy-MM-dd, d-MMM-yyyy, dMMMyyyy, dd/MM/yy, dd/MM/yyyy, yyyy/MM/dd For VNS only, the start date of the period represented by this row. An additional row is required for each change in notional.
compounding FLAT, STRAIGHT, SPREADEXCLUSIVE, NONE Leg compounding method, defaults to NONE.
compoundingIndexPeriod 1M, 3M, etc The accrual frequency. Defaults to the payment period.
stub ShortInitial, LongInitial, ShortFinal, LongFinal Defaults to ShortInitial.
firstRate Number Rate to apply to the first period of the trade.
firstInterpolationTenor 1W, 2W, etc The tenor of the first index to use when linearly interpolating between two indices in the legIndex family to obtain the stub rate. Defaults to the accrual tenor.
secondInterpolationTenor 1W, 2W, etc The tenor of the second index to use when linearly interpolating between two indices in the legIndex family to obtain the stub rate. Defaults to firstInterpolationTenor.
dayCountMethod 30/360, ACT/ACT, ACT/360, ACT/365, 30E/360 Leg day count convention. Defaults from the legType and rate type.
businessDayConvention Preceding, Following, ModPreceding, ModFollowing Defaults to ModFollowing
paymentCalendar Calendar code Combines the specified calendar with the calendar for the trade currency.
adjustment Unadjusted, Adjusted Specifies the start date business day adjustment. Defaults to Adjusted using the business day convention.
rollMethod EOM, IMM, Standard Defaults to Standard.

For variable-notional swaps, one row is required for each change in notional. If the swap includes a stub period then this must be indicated on the first row.

Eurex OTC Sensitivities CSV Format

Example Eurex OTC Sensitivities CSV file containing sensitivities to 5 GBP curves at multiple tenors:

Maturity,GBP.SONIA.ON,GBP.LIBOR.1M,GBP.LIBOR.1Y,GBP.LIBOR.3M,GBP.LIBOR.6M
ON,109.6348242,260.0774112,-418.6946032,-165.135269,-13.682645
10M,-611.157218,702.8095749,-12847.10854,-32.82816523,59.8478585
11M,-5124.389841,-34.20966984,354.3236035,1.203367248,-3.05029726
15M,-45172.77912,399.425105,-450.1766265,-36.34373966,22.53807156
18M,-17151.75602,220.0584175,-451.0728531,-104.4429463,-20.11474715
10Y,-389.4213151,-3276.46478,3013.299915,4.215100471,-4.142389134
11Y,-424.8966138,-3174.311444,3590.421195,0.303772546,-0.298711188
12Y,-827.5463643,-8029.602532,8129.02009,0.021892857,-0.021505114
15Y,-1807.181108,-18641.04948,19003.84111,0.000529446,-0.000514757

This is the standard Eurex CSV format for specifying an OTC portfolio as sensitivities to its risk factors, rather than trades. The resulting file contains a table of curves against tenors. These can be pre-aggregated into a single CSV file, or specified over multiple files. Without full trade details, the methodology uses a delta-based approximation rather than full valuation, which can significantly increase its performance with a slight trade-off in accuracy.

Column Name Format Description
Maturity
Required		 ON, 1D, 1W, 2W, 3W, 1M, ..., 12M, 1Y, ... A tenor that exists in the Eurex curve.
Curve name (1 column per curve)
Required		 [Currency Code].[Index].[Index Period] Sensitivity amount for the given Maturity and curve. Leave blank if there is no sensitivity or the tenor does not exist for the curve.

Eurex ETD

The Eurex ETD methodology supports the following portfolio formats:

Eurex ETD CSV Format

Example Eurex ETD CSV file containing 5 positions:

OpenGammaId,Product ID,Product ID Type,Expiry Year,Expiry Month,Expiry Day,Version Number,Product Settlement Type,Call Put Flag,Exercise Price,Exercise Style Flag,Instrument Type,Assigned/Notified Balance,Exercised/Allocated Balance,Long Balance,Short Balance
25,FESX,EUREX,2016,6,17,,C,,,,Future,0,0,0,13584
26,FGBL,EUREX,2016,6,8,,C,,,,Future,0,0,0,155
27,FGBM,EUREX,2016,6,8,,C,,,,Future,0,0,504,0
97,VGM6,BBG,2016,6,,0,,,,,Future,,,0,1
98,SX5E,BBG,2016,12,16,0,C,C,1000,EUROPEAN,Option,0,0,0,1300

This is the standard Eurex ETD format with the addition of an OpenGammaId field for the identification of each position.

Column Name Format Description
Product ID
Required		 Text Eurex product code or Bloomberg ticker.
Product ID Type EUREX, BBG Specifies the type of Product ID.
Expiry Year
Required		 YYYY Actual expiry year.
Expiry Month
Required		 Month number Actual expiry month.
Expiry Day Day number Actual expiry day, required for flex contracts.
Version Number
Required		 Number The contract version number. Required for options. Use 0 otherwise.
Product Settlement Type C, E, D, N, P, S, T, A The settlement type. Required for flex contracts.
Call Put Flag C, P Specifies a call or put option.
Exercise Price Number The option exercise or strike price.
Exercise Style Flag A or AMERICAN, E or EUROPEAN The exercise style. Required for flex options.
Instrument Type
Required		 Future, Option, Flex Option, Flex Future The instrument type.
Long Balance
Required		 Positive number The long quantity in this position. Use 0 if only short.
Short Balance
Required		 Positive number The short quantity in this position. Use 0 if only long.
OpenGammaId Text A unique identifier which can be used to unambiguously tie position-level results back to this input. Defaults to a generated identifier from an incrementing sequence.

CME OTC

The CME methodology supports the following portfolio formats, which are all compatible with CME CORE:

Example CME OTC-format CSV file containing a single swap:

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
OpenGamma,TEST,45,ZERO_COUPON,BRL,20180101,20200302,123456789.2,PAY,0,BRL-CDI,1T ,1T ,NONE,BRL-CDI,N/A,1T ,NONE,,,123456789.2

In addition to these formats, the CME OTC methodology also supports the (OpenGamma Standard OTC CSV format).

CME ETD

The CME methodology supports the following portfolio format for cross-margining with OTC only:

Example CME ETD-format CSV file containing a single position

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,,,ED,201903,,,,,100,

JSCC OTC

The JSCC OTC IRS methodology supports the following portfolio format:

JSCC OTC IRS CSV Format

Example JSCC OTC IRS CSV file containing a single trade:

Date,Clearing Member Code,Clearing Member Short Name,2nd Layer Type,2nd Layer,3rd Layer,Original Counterparty ID,Original Counterparty Name,Clearing House Trade Reference,Internal Trade ID,Trade Group ID,Source,External Reference,Trade Date,Registration Date And Time,Maturity Date,Trade Status,Backload Flag,Currency,Notional Amount,Swap Type,Trade Effective Date,Trade NPV,Stub At,Pay Leg Type,Pay Rate,Pay Spread,Pay Index,Pay Rate Index Tenor,Pay Day Count Fraction,Pay Payment Frequency,Pay Business Day Convention,Pay Holiday Centers,Pay Calc Period Frequency,Pay Compounding Method,Pay Stub Type,Rec Leg Type,Rec Rate,Rec Spread,Rec Index,Rec Rate Index Tenor,Rec Day Count Fraction,Rec Payment Frequency,Rec Business Day Convention,Rec Holiday Centers,Rec Calc Period Frequency,Rec Compounding Method,Rec Stub Type,Roll Date Convention,Mutual Put Option Flag,Pay Stub Index Tenor,Pay Stub Index Tenor 2,Pay First Payment Date,Pay First Period Calc End Date,Pay Fixing Holiday Centers,Pay Fixing Days Offset,Pay Reset In Arrears,Rec Stub Index Tenor,Rec Stub Index Tenor 2,Rec First Payment Date,Rec First Period Calc End Date,Rec Fixing Holiday Centers,Rec Fixing Days Offset,Rec Reset In Arrears,Pay Initial Period Rate,Pay Initial Period Fix Lag,Pay Stub Rate,Pay Stub End Date,Pay Stub Fixed Amount,Rec Initial Period Rate,Rec Initial Period Fix Lag,Rec Stub Rate,Rec Stub End Date,Rec Stub Fixed Amount,Roll Date,Additional Pay Date,Additional Pay Amount,NPV change,Unique Swap ID,Legal Entity ID,Un-adjusted Trade Effective Date,Un-adjusted Maturity Date,Notional Amount Change Flag,Current Notional Amount,Mutual Put Break Date,Pay Payment Lag,Rec Payment Lag,Execution Platform,Execution Platform Type,Netting Flag,PAI,External Reference (Child)
13/06/2016,910,Test Bank,Client,0,JJJ,,,710772,SP3287854,,,Test25-2,01/06/2016,01/06/2016 11:57,10/05/2055,Cleared,N,JPY,50000000,IRS,10/05/2016,4826696,,Fixed,0.1,0,,,ACT/365,SA,MOD_FOLLOW,"LON, TOK",SA,,,Float,0,0,LIBOR,6M,ACT/360,SA,MOD_FOLLOW,"LON, TOK",SA,,,DAY,,,,10/11/2016,10/11/2016,,,,,,10/11/2016,10/11/2016,LON,2,BEG_PER,0,0,,,,0.00479,2,,,,10,,,-295480,1050000001IRS00000000JSCC00000000000706713,FUKUDA,10/05/2016,10/05/2055,N,50000000,,0,0,,,N,23,Test25

This is a CSV format which is the standard trade report published by JSCC.

Column Name Format Description
Date
Required		 dd/MM/yyyy Close of business date.
Clearing Member Code
Required		 Text Clearing Member Code for reporting purposes only.
Clearing Member Short Name
Required		 Text Clearing Member Short Name for reporting purposes only.
2nd Layer Type
Required		 Text 2nd Layer Type for reporting purposes only.
2nd Layer
Required		 Text 2nd Layer for reporting purposes only.
3rd Layer
Required		 Text 3rd Layer for reporting purposes only.
Clearing House Trade Reference
Required		 Text Unique trade identifier.
Internal Trade ID Text Optional internal trade identifier.
Trade Date
Required		 dd/MM/yyyy Trade date.
Currency
Required		 AUD, EUR, USD, JPY Currency of the trade.
Notional Amount
Required		 Positive number Notional in local currency.
Swap Type
Required		 OIS, IRS, Basis Swap The type of swap.
Stub At Start, End Position of stub. Defaults to None.
Pay Leg Type
Required		 Fixed, Float Pay leg type.
Pay Rate
Required		 Rate as a percentage (%) Pay leg rate for fixed leg. Set to 0 for float leg.
Pay Spread
Required		 Spread in basis points (bp). Pay leg spread for float leg. Set to 0 for fixed leg or if no spread.
Pay Index
Required		 LIBOR, TIBOR,D-TIBOR, OIS, EURIBOR, BBSW Pay leg index name.
Pay Rate Index Tenor
Required		 1D, 1M, 3M, 6M Pay leg index period. Set to 1D for OIS trades.
Pay Day Count Fraction
Required		 30/360, ACT/ACT, ACT/360, ACT/365, ACT/365I, 30E/360, 30E*/360 Pay leg day count convention.
Pay Payment Frequency
Required		 MTH, QTR, SA, PA, ZC Pay leg payment frequency.
Pay Business Day Convention
Required		 MOD FOLLOW, FOLLOWING, PRECEDING Pay leg business day convention.
Pay Holiday Centers
Required		 TOK, LON, NYC, TARGET, SYD Pay leg payment holiday center. To use multiple holiday centers, separate each by a comma followed by a space.
Pay Calc Period Frequency
Required		 MTH, QTR, SA, PA, ZC Calculation period frequency.
Pay Compounding Method Straight, Flat Compunding method. Defaults to None.
Pay Stub Type Short, Long Type of stub. Defaults to Short.
Rec Leg Type
Required		 Fixed, Float Receive leg type.
Rec Rate
Required		 Rate as a percentage (%) Receive leg rate for fixed leg. Set to 0 for float leg.
Rec Spread
Required		 Spread in basis points (bp). Receive leg spread for float leg. Set to 0 for fixed leg or if no spread.
Rec Index
Required		 LIBOR, TIBOR, D-TIBOR, OIS, EURIBOR, BBSW Receive leg index name.
Rec Rate Index Tenor
Required		 1D, 1M, 3M, 6M Receive leg index period. Set to 1D for OIS trades.
Rec Day Count Fraction
Required		 30/360, ACT/ACT, ACT/360, ACT/365, ACT/365I, 30E/360, 30E*/360 Receive leg day count convention.
Rec Payment Frequency
Required		 MTH, QTR, SA, PA, ZC Receive leg payment frequency.
Rec Business Day Convention
Required		 MOD FOLLOW, FOLLOWING, PRECEDING Receive leg business day convention.
Rec Holiday Centers
Required		 TOK, LON, NYC, TARGET, SYD Receive leg payment holiday center. To use multiple holiday centers, separate each by a comma followed by a space.
Rec Calc Period Frequency
Required		 MTH, QTR, SA, PA, ZC Calculation period frequency.
Rec Compounding Method Straight, Flat Compounding method. Defaults to None.
Rec Stub Type Short, Long Type of stub. Defaults to Short.
Roll Date Convention
Required		 NONE, EOM, IMM, DAY Roll date convention.
Roll Date Number Roll date of month when Roll Date Convention is DAY.
Pay Stub Index Tenor e.g. 1W Tenor used to calculate pay leg stub interest rate, if applicable.
Pay Stub Index Tenor 2 e.g. 1W Second tenor used to calculate pay leg stub interest rate with interpolation. Leave empty to use the stub interest rate without interpolation.
Pay Fixing Holiday Centers TOK, LON, NYC, TARGET, SYD Pay leg fixing holiday center. To use multiple holiday centers, separate each by a comma followed by a space. Defaults to the holiday center of the index.
Pay Fixing Days Offset
Required		 Number The number of business days between reset date and fixing date for the pay leg.
Pay Reset In Arrears BEG_PER, END_PER Pay leg reset timing. For OIS set to END_PER Defaults to BEG_PER.
Rec Stub Index Tenor
Required		 Text Tenor used to calculate stub interest rate.
Rec Stub Index Tenor 2
Required		 Text Tenor used to calculate stub interest rate. If the stub interest rate without interpolation is used then field should be null.
Rec Fixing Holiday Centers TOK, LON, NYC, TARGET, SYD Receive leg fixing holiday center. To use multiple holiday centers, separate each by a comma followed by a space. Defaults to the holiday center of the index.
Rec Fixing Days Offset
Required		 Number The number of business days between reset date and fixing date for the receive leg.
Rec Reset In Arrears BEG_PER, END_PER Receive leg reset timing. For OIS set to END_PER. Defaults to BEG_PER.
Pay Initial Period Rate Rate as a percentage (%) Rate to be used for initial period when the pay leg is the floating leg.
Pay Initial Period Fix Lag
Required		 Number The number of business days between reset date and fixing date on the first period of the pay leg.
Pay Stub Rate Rate as a percentage (%) Rate applied on stub period where the pay leg is the floating leg, if applicable.
Rec Initial Period Rate Rate as a percentage (%) Rate to be used for initial period when the receive leg is the floating leg.
Rec Initial Period Fix Lag
Required		 Number The number of business days between reset date and fixing date on the first period of the receive leg.
Rec Stub Rate Rate as a percentage (%) Rate applied on stub period where the receive leg is the floating leg, if applicable.
Un-adjusted Trade Effective Date
Required		 dd/MM/yyyy Trade date before adjusting for day convention.
Un-adjusted Maturity Date
Required		 dd/MM/yyyy Maturity date before adjusting for day convention.
Pay Payment Lag
Required		 Number The number of business days between calculation and payment date for the pay leg.
Rec Payment Lag
Required		 Number The number of business days between calculation and payment date for the receive leg.

Any other columns present in the standard JSCC report are not required and will be ignored.

SPAN

The SPAN methodology supports the following format:

OpenGamma SPAN CSV Format

Example portfolio containing 2 positions:

Strata Position Type,Exchange,Contract Code Type,Contract Code,Expiry,Expiry Week,Expiry Day,Quantity,Put Call,Exercise Price
FUT,XCBT,BBG,FV,201712,,,100,,
FUT,XCBT,BBG,TY,201712,,,200,,

This is an extension of the Strata ETD CSV position format which additionally provides support for the use of Bloomberg tickers.

Column Name Format Description
Strata Position Type
Required		 FUT, OPT, SEC The type of the security.
Exchange MIC code The exchange code, required if Contract Code Type specifies exchange contract codes.
Contract Code Type BBG, EXG The type of contract code. BBG to provide a Bloomberg ticker, or EXG to provide an exchange contract code. Defaults to EXG.
Contract Code
Required		 Text The contract code, which must be consistent with the specfied type.
Expiry
Required for futures and options		 yyyy-MM, yyyyMM, yyyy/MM, MMM-yyyy, MMM-yy, MMMyyyy, MMMyy, d/M/yyyy The year-month of the expiry.
Expiry Week Number The week number for weekly-expiring futures.
Expiry Day Number The day-of-month for daily-expiring or flex futures.
Quantity
Required		 Number The total quantity. A positive number represents a long position, and a negative number represents a short position.
Put Call
Required for options		 P, Put, C, Call The put/call flag.
Exercise Price
Required for options		 Number The option exercise or strike price.
Trade Price
Required for price based add-ons (e.g. LME DCVM)		 Text CCY VALUE The trade price with its currency. (e.g. USD 100)

SIMM

The SIMM methodology supports the following format:

ISDA CRIF CSV/TSV Format

This is the standard ISDA format for SIMM. The file extension must be either .csv or .tsv to indicate the expected delimiter.

For further information about each field please refer to the ISDA documentation.

Column Name Format Description
ProductClass
Required		 Text The product class.
RiskType
Required		 Risk_IRCurve, Risk_Inflation, Risk_CreditQ, Risk_CreditNonQ, Risk_Equity, Risk_Commodity, Risk_FX, Risk_IRVol, Risk_CreditVol, Risk_CreditVolNonQ, Risk_EquityVol, Risk_CommodityVol, Risk_FXVol Risk factor type.
Qualifier
Required		 Text Description of the risk factor.
Bucket
Required		 Number SIMM bucket.
Label1
Required		 e.g. 3M, 5Y etc Tenor describing the vertex of the risk factor.
Label2 String Used if risk factor is a matrix, or to identify sensitivities from qualifying credit securitisations.
Amount
Required		 Number Amount of risk in AmountCurrency.
AmountCurrency
Required		 ISO currency code Currency of the Amount field.
AmountUSD Number Amount of risk in USD.

Using the APIs

There are currently two supported ways to use our APIs:

The documentation and examples below refer to the latest versions of our APIs. Older versions remain supported but users are encouraged to upgrade to the latest versions to benefit from the complete set of features.

Java SDK

Our Java SDK provides a simple way to access our APIs:

ServiceInvoker invoker = ServiceInvoker.of(CREDENTIALS);
MarginClient client = MarginClient.of(invoker);
CcpInfo lch = client.getCcpInfo(Ccp.LCH);
List<PortfolioDataFile> files = Collections.singletonList(PortfolioDataFile.of(LCH_FILE));

MarginCalcRequest request = MarginCalcRequest.of(lch.getLatestValuationDate(), lch.getDefaultCurrency(), files);
MarginCalcResult result = client.calculate(Ccp.LCH, request);

The Java SDK is an open source library which provides a simple developer interface to the complete set of APIs described below, avoiding the need to program against the REST API directly. This library is fully supported by OpenGamma, and takes care of details such as authentication and polling for results, leaving developers to focus on using the services.

For more information, see the GitHub repository. For a complete example of accessing our Margin Service using the SDK, see the MarginClientExample class.

Obtaining the SDK

Maven dependency for the Java SDK:

<dependency>
 <groupId>com.opengamma.sdk</groupId>
 <artifactId>sdk-margin</artifactId>
 <version>2.0.0</version>
</dependency>

The library is available in Maven Central and JCenter. It can be included in your Maven project by adding the dependency shown.

REST API

Our services can be accessed from any language through the REST API. Endpoints are provided for:

Schema

All API access is over HTTPS through the base URI https://api.opengamma.com/. The paths for the methods shown below are relative to this base URI.

All data is sent and received as JSON; the Content-Type header must be set to application/json as shown in the examples.

Authentication

We use OAuth 2.0 for authentication and authorization. In this protocol, you must first obtain an access token by providing your credentials to our authentication endpoint. This token is subsequently used to access restricted endpoints by passing it in the Authorization header. The value of this header must be Bearer <Token> where <Token> is replaced with the full token value.

Margin Calculation Workflow

The typical workflow for performing margin calculations is:

What-If Calculation Workflow

The typical workflow for performing a what-if calculations is:

API Versioning

Our REST APIs are versioned through the URL (e.g. .../v3/...) which specifies the major version number. We have a strict change management policy and commit never to make breaking changes to an existing API version.

For the avoidance of doubt, a breaking change means any change that would normally break an existing integration with the API, such as:

We may make certain changes which enhance an API and would not be expected to break any existing integration, such as:

If we introduce a new major API version then we will also release updated online documentation and a corresponding Java SDK version. Customers will be notified as soon as this is available.

We commit to support any previous major API versions for a minimum of 6 months. We always work with customers to understand the impact of any migration and to ensure a reasonable path forwards including, if necessary, continuing to support the previous version for longer.

Authentication API

Token

Using curl:

curl https://api.opengamma.com/auth/v3/token \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "<Your API Key>",
    "client_secret": "<Your API Secret>"
  }'

POST /auth/v3/token

Obtains an access token by presenting a client ID and client secret, using the client_credentials OAuth 2.0 flow. See RFC 6749 section 4.4.2 and 2.3.1.

Request Body Properties

Name Description
grant_type
Required		 Should always be client_credentials.
client_id
Required		 The client ID.
client_secret
Required		 The client secret.

The response body provides the access token and its expiry:

{
  "access_token": "<Your access token here>",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Response Body Properties

Name Description
access_token The access token to be used in the Authorization header of subsequent authenticated requests. This should be prefixed with Bearer.
expires_in The lifetime of the token, in seconds.
token_type Always Bearer.

Response Status Codes

Code Description
200 Success.
400 Bad request. The request arguments are invalid.
401 The request lacks valid authentication credentials.
403 The user does not have permission to access the API directly.

Margin API

List CCPs

Using curl:

curl https://api.opengamma.com/margin/v3/ccps \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Your access token here>'

GET /margin/v3/ccps

Queries the CCPs that are available for margin calculations.

This provides the ability to find out which CCPs are available for the current user.

Request Headers

Header Name Value
Content-Type
Required		 application/json
Accept
Required		 application/json
Authorization
Required		 Bearer <Your access token here>

The response body provides the available CCPs or methodologies:

{
  "ccps": [
    "lch",
    "eurex",
    "cme",
    "jscc",
    "simm"
  ]
}

Response Body Properties

Name Description
ccps The list of CCPs or methodologies that the user has permission to access. May be empty.

Response Codes

Code Description
200 Success.
401 The request lacks valid authentication credentials.
403 The user does not have permission to use this service.

Get CCP information

Using curl to obtain information for LCH:

curl https://api.opengamma.com/margin/v3/ccps/lch \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Your access token here>' \
  -H 'Content-Type: application/json'

GET /margin/v3/ccps/{ccp}

Queries a specific CCP or methodology for the available valuation dates, the supported reporting and calculation currencies, and the default CCP currency. This information is only available if the user is permissioned for the CCP.

Path Variables

Name Description
ccp The CCP or methodology to use for the calculation.

Request Headers

Header Name Value
Content-Type
Required		 application/json
Accept
Required		 application/json
Authorization
Required		 Bearer <Your access token here>

The response body provides the list of available valuation dates and details about the available currencies:

{
  "valuationDates": [
    "2017-08-15",
    "2017-08-14"
  ],
  "defaultCurrency": "GBP",
  "reportingCurrencies": [
    "EUR",
    "GBP",
    "USD"
  ],
  "calculationCurrencies": [
    "GBP"
  ],
  "calculationTypes": [
    "PORTFOLIO_SUMMARY",
    "MARGIN"
  ],
  "calculationModes": [
    "SPOT",
    "FORWARD"
   ]
}

Response Body Properties

Name Description
valuationDates The list of valuation dates currently available for the CCP or methodology. May be empty.
defaultCurrency The default currency of the CCP or methodology.
reportingCurrencies The list of currencies that the results may be reported in.
calculationCurrencies The list of currencies that the calculation can be performed in. May be empty if it is intended to be inferred from the reporting currency.
calculationTypes The calculation types that can be requested for the CCP.
calculationModes The available modes in which the calculation can be performed.

Response Status Codes

Code Description
200 Success.
401 The request lacks valid authentication credentials.
403 The user does not have permission to access the CCP or methodology.

Create margin calculation

Using curl to request a calculation for LCH:

curl https://api.opengamma.com/margin/v3/ccps/lch/calculations \
  -H 'Authorization: Bearer <Your access token here>' \
  -H 'Content-Type: application/json' \
  -d '{ 
    "calculationTypes": [
      "MARGIN",
      "PRESENT_VALUE"
    ],
    "valuationDate": "<available date, as YYYY-mm-DD>",
    "applyClientMultiplier": true, 
    "reportingCurrency": "GBP", 
    "calculationCurrency": "GBP", 
    "mode" : "SPOT",
    "portfolioData": 
    [ 
      { 
        "name": "trades.csv", 
        "data": "counterparty,tradeId,tradeType,notional,currency,effectiveDate,terminationDate,payLegType,payLegSpread,payLegPaymentPeriod,payLegDayCountFraction,payLegCompoundingMethod,payLegIndexPeriod,payLegStub,recLegType,recLegSpread,recLegPaymentPeriod,recLegDayCountFraction,recLegCompoundingMethod,recLegIndexPeriod,recLegStub,rollConvention\nXXX,FRA8,FRA,15000000,DKK,08/11/2014,08/05/2015,FLOAT,,,ACT/360,,,,FIXED,2.8,,ACT/360,,,,\nXXX,FRA12,FRA,15000000,NOK,16/07/2014,20/12/2014,FLOAT,,,ACT/360,,i,,FIXED,1.8,,ACT/360,,,,\nXXX,FRA13,FRA,15000000,PLN,12/12/2014,12/12/2015,FIXED,3,,ACT/360,,,,FLOAT,,,ACT/360,,,,\nXXX,FRA14,FRA,15000000,SEK,8/9/2014,8/12/2014,FIXED,1.5,,ACT/360,,,,FLOAT,,,ACT/360,,,,\nXXX,irsR002,IRS,646000000,GBP,16/03/2011,16/03/2051,FIXED,3,6M,ACT/ACT,,,,FLOAT,-22,12M,ACT/365,,,,\nXXX,irsR004,IRS,815000000,AUD,29/10/2010,28/02/2015,FIXED,5,ZERO C,ACT/365,STRAIGHT,1M,,FLOAT,-57,1M,ACT/365,,,,\nXXX,irsR005,IRS,524000000,JPY,20/09/2010,20/09/2025,FIXED,2,6M,ACT/365,,,,FLOAT,-70,12M,ACT/360,,,,\nXXX,oisR067,OIS,972000000,USD,15/08/2014,18/09/2014,FIXED,2,12M,ACT/ACT,,,,FLOAT,-39,12M,ACT/360,,,,\n,XXX,oisR066,OIS,966000000,CHF,24/07/2014,01/05/2015,FLOAT,92,12M,ACT/360,,,,FIXED,0,12M,ACT/365,,,,\n,XXX,irsR248,IRS,961000000,CAD,04/10/2011,04/01/2016,FIXED,1,3M,ACT/ACT,,,,FLOAT,-38,1M,ACT/365,,,,\n,XXX,irsR018,IRS,519000000,PLN,41153,42248,FLOAT,-83,3M,ACT/365,,,,FLOAT,96,12M,ACT/365,,,,\n"
      }
    ]
  }'

POST /margin/v3/ccps/{ccp}/calculations

Creates a job to calculate initial margin on a portfolio. If the job is successfully accepted then the calculation request has been queued for processing. The results are normally available for collection almost immediately, depending on the size of the portfolio and current system load.

Path Variables

Name Description
ccp The CCP or methodology to use for the calculation.

Request Headers

Header Name Value
Content-Type
Required		 application/json
Accept
Required		 application/json
Authorization
Required		 Bearer <Your access token here>

Request Body Properties

Name Description
calculationTypes The list of types to calculate.
PORTFOLIO_SUMMARY for a summary of each parsed trade/position.
MARGIN for margin calculation.
MARGIN_DETAIL for a CCP specific detailed breakdown of the margin calculation.
PRESENT_VALUE for the present value of the trades in the portfolio.
DELTA for the present value delta of the trades in the portfolio.
GAMMA for the present value gamma of the trades in the portfolio.
Note that an empty list is equivalent to a list containing just MARGIN.
type Deprecated and replaced by calculationTypes.
FULL is equivalent to a list of PORTFOLIO_SUMMARY and MARGIN.
STANDARD is equivalent to a list of MARGIN.
PARSE_INPUTS is equivalent to a list of PORTFOLIO_SUMMARY.
mode The optional calculation mode.
SPOT for a standard margin calculation at an available historical valuation date.
FORWARD for a forward margin calculation at any future valuation date.
Defaults to SPOT if omitted.
valuationDate
Required		 The valuation date for which margin will be calculated in YYYY-MM-DD format. Must be an available historical valuation date in SPOT mode, or any future date in FORWARD mode.
portfolioData
Required		 A list of files in the request, each of type PortfolioDataFile.
reportingCurrency
Required		 The currency that the result is reported in, as an ISO 4217 three-letter currency code.
calculationCurrency The currency that the calculation is performed in, as an ISO 4217 three-letter currency code. If omitted, the calculation currency will be inferred from reportingCurrency.
applyClientMultiplier Whether to perform the calculation in Client (rather than House) mode, where supported by the CCP (see the CCP documentation for details).
fpmlPartySelectionRegex The regular expression used to select the party in any FpML input. The regular expression is matched against the content of the partyId elements. If this is not specified, FpML cannot be parsed.
calcApproach The optional calculation approach.
DEFAULT uses the stanard calculation approach for the given CCP.
FULL_REVAL for a margin calculation using full revaluation mode.
DELTA_APPROX for a margin calculation using delta approximation mode.
Defaults to DEFAULT if omitted.

Request Body Properties / PortfolioDataFile

Name Description
name The file name, optionally suffixed with .zip.base64 or .gz.base64 to specify the data encoding.
data The portfolio data in a format supported by the CCP or methodology (see the CCP documentation for details) and encoded as described below.

Several data encodings are supported for maximum flexibility and to allow faster transmission of large files:

If the calculation request is accepted then the response will be 202 Accepted with an empty body and the Location header set to the path to the calculation:

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 0
Location: /margin/v3/ccps/lch/calculations/712c5e5a-c5aa-407e-949e-c42e918b01d6

Response Headers

Header Name Description
Location The path of the newly-created calculation resource, which is relative to the base URI of the API.

Response Status Codes

Code Description
202 Accepted.
400 Bad Request. The request body is invalid.
401 The request lacks valid authentication credentials.
403 The user does not have permission to access the CCP or methodology.

Get margin calculation

Using curl:

curl https://api.opengamma.com/margin/v3/ccps/lch/calculations/712c5e5a-c5aa-407e-949e-c42e918b01d6 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Your access token here>'

GET /margin/v3/ccps/{ccp}/calculations/{calcId}

Gets the status and results of a margin calculation. The calculation resource must be polled periodically until the status changes from PENDING to COMPLETED.

Path Variables

The path should correspond to that returned in the Location header of the response after creating the calculation.

Name Description
ccp The CCP or methodology to use for calculation.
calcId The calculation identifier.

Request Headers

Header Name Value
Content-Type
Required		 application/json
Accept
Required		 application/json
Authorization
Required		 Bearer <Your access token here>

Until the results are ready, the status in the response body will be PENDING:

{
  "status": "PENDING",
  "type": "FULL",
  "calculationTypes": [
    "PORTFOLIO_SUMMARY",
    "MARGIN"
  ],
  "mode": "SPOT",
  "valuationDate": "2017-08-10",
  "reportingCurrency": "GBP",
  "portfolioItems": [],
  "failures": []
}

Once the calculation has completed successfully, the status will change to COMPLETED:

{
  "status": "COMPLETED",
  "type": "FULL",
  "calculationTypes": [
    "PORTFOLIO_SUMMARY",
    "MARGIN"
  ],
  "mode": "SPOT",
  "valuationDate": "2017-08-10",
  "reportingCurrency": "GBP",
  "calculationCurrency": "GBP",
  "applyClientMultiplier": true,
  "portfolioItems": [],
  "margin": {
    "margin": -110582620.39464206,
    "marginDetails": [
      {
        "key": "Base IM",
        "value": -101214539.79557736
      },
      {
        "key": "BASIS_RISK",
        "value": 0
      },
      {
        "key": "UNSCALED_VAR",
        "value": 0
      },
      {
        "key": "DIVERSIFICATION",
        "value": 0
      },
      {
        "key": "IMMFP_OUTRIGHT",
        "value": -9368080.599064698
      },
      {
        "key": "IMMFP_BASIS",
        "value": 0
      },
      {
        "key": "IMM1",
        "value": 0
      },
      {
        "key": "IMM2",
        "value": -9368080.599064698
      },
      {
        "key": "TOTAL_IMM",
        "value": -9368080.599064698
      },
      {
        "key": "CRIM",
        "value": 0
      }
    ],
    "breakdown": {
      "totalMargin": -110582620.39464206,
      "baseMargin": -100080600.29060206,
      "addOns": -10502020.10404,
      "netLiquidatingValue": 0.0
    }
  },
  "failures": [
    {
      "reason": "PARSING",
      "message": "Unable to load trade: Text '8/9/2014' could not be parsed at index 1",
      "attributes": {}
    },
    {
      "reason": "INVALID",
      "message": "Unable to add trade 'oisR067': ValidationException: Trade has expired: termination date=18-9-2014,today=10-8-2017",
      "attributes": {
        "tradeId": "oisR067",
        "exceptionMessage" : "Trade has expired: termination date=18-9-2014,today=10-8-2017"
      }
    }
  ]
}

Response Body Properties

Name Description
status The status of the calculation: PENDING or COMPLETED.
calculationTypes The list of types that were calculated.
type The type of the calculation: FULL, STANDARD, or PARSE_INPUTS. This corresponds to the type of the original calculation request.
mode The calculation mode: SPOT, or FORWARD. This corresponds to the mode of the original calculation request.
valuationDate The valuation date of the calculation.
reportingCurrency The reporting currency. This is the currency of all amounts in the results.
calculationCurrency
OPTIONAL		 The optional currency that the calculation was performed in.
applyClientMultiplier
OPTIONAL		 Whether to perform the calculation in Client (rather than House) mode, where supported.
portfolioItems A summary of each item in the portfolio, may be empty. Returned if calculationTypes contains PORTFOLIO_SUMMARY.
margin
OPTIONAL		 The result of the margin calculation. Returned if calculationTypes contains MARGIN.
marginDetail
OPTIONAL		 The CCP-specific detailed breakdown of the margin calculation. Returned if calculationTypes contains MARGIN_DETAIL.
tradeValuations
OPTIONAL		 The valuation of the trades in the portfolio. Returned if calculationTypes contains PRESENT_VALUE, DELTA or GAMMA.
failures The list of failures that have occurred. May be empty.

The margin data structure contains the following:

Name Description
margin The total margin, expressed in the reporting currency.
marginDetails A list containing a high level breakdown of the margin using CCP-specific terminology.
breakdown A high level breakdown of the margin using standardized terminology.

The breakdown data structure contains the following:

Name Description
totalMargin The total margin, expressed in the reporting currency.
baseMargin The base margin, expressed in the reporting currency.
addOns The total of all add-ons, expressed in the reporting currency.
netLiquidatingValue The total premium value of the options held that has been paid/received.

The marginDetail data structure for LCH contains the following:

Name Description
totalMargin The total margin, expressed in the reporting currency.
baseScenarioIds A list of the scenarios chosen to calculate base margin.
indices The indices involved in the margin calculation.
scenarios The scenarios that were selected for the margin calculation.

The indices data structure for LCH contains the following:

Name Description
indexName The name of the index, in LCH format.
diversifiedBaseMargin The diversified base margin, expressed in the reporting currency.
undiversifiedBaseMargin The undiversified base margin, expressed in the reporting currency.
indexScenarioIds A list of the scenarios chosen to calculate index-level margin.

The scenarios data structure for LCH contains the following:

Name Description
id The identifier of the scenario.
date The date of the scenario.
scaledPortfolioPnl The scaled portfolio-level PnL, expressed in the reporting currency.
unscaledPortfolioPnl The unscaled portfolio-level PnL, expressed in the reporting currency.

The tradeValuations data structure contains the following:

Name Description
totalPresentValue The total present value, expressed in the reporting currency.
totalDelta
OPTIONAL		 The present value delta, expressed in the reporting currency.
bucketedDelta
OPTIONAL		 The list of per-curve deltas, expressed in the currency of the curves.
totalGamma
OPTIONAL		 The present value gamma, expressed in the reporting currency.
bucketedGamma
OPTIONAL		 The list of per-curve gammas, expressed in the currency of the curves.
trades The list of trades.

bucketedDelta and bucketedGamma use the curveSensitivity data structure described further down.

The trade data structure contains the following:

Name Description
tradeId The identifier of the trade.
value
OPTIONAL		 The value of the trade. Returned if calculationTypes contains PRESENT_VALUE.
delta
OPTIONAL		 The value of the trade. Returned if calculationTypes contains DELTA.
gamma
OPTIONAL		 The value of the trade. Returned if calculationTypes contains GAMMA.

The value data structure contains the following:

Name Description
presentValue The present value of the trade, expressed in the reporting currency.
tradeCurrency The currency of the trade.
presentValueTradeCurrency The present value of the trade, expressed in the trade currency.

The delta / gamma data structure contains the following:

Name Description
sensitivity The present value sensitivity of the trade, expressed in the reporting currency.
curveSensitivity The list of per-curve sensitivities.

The curveSensitivity data structure contains the following:

Name Description
curveName The name of the curve.
currency The currency of the curve.
sensitivity The total of the bucketed sensitivities, expressed in the curve currency.
tenorSensitivity The bucketed sensitivities, expressed in the curve currency.

Response Status Codes

Code Description
200 Success.
401 The request lacks valid authentication credentials.
404 The given calculation resource was not found, or has expired.

Delete calculation

Using curl:

curl -X DELETE \
  https://api.opengamma.com/margin/v3/ccps/lch/calculations/712c5e5a-c5aa-407e-949e-c42e918b01d6 \
  -H 'Authorization: Bearer <Your access token here>'

DELETE /margin/v3/ccps/{ccp}/calculations/{calcId}

Cancels a margin calculation request if in progress, or deletes the results associated with the calculation if the calculation has been completed.

Path Variables

The path should correspond to that returned in the Location header of the response after creating the calculation.

Name Description
ccp The CCP or methodology to use for calculation.
calcId The calculation identifier.

Request Headers

Header Name Value
Content-Type
Required		 application/json
Accept
Required		 application/json
Authorization
Required		 Bearer <Your access token here>

The service will always respond to an authenticated user with 200 OK and empty body:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 0

Attempting to GET the calculation resource after it has been deleted will result in a 404 response.

Response Status Codes

Code Description
200 OK
401 The request lacks valid authentication credentials.

What-If API

Create what-if calculation

Using curl to request a what-if calculation:

curl https://api.opengamma.com/calcs/v1/base/whatif/v1/calcs \
  -H 'Authorization: Bearer <Your access token here>' \
  -H 'Content-Type: application/json' \
  -d '{ 
      "incrementalPortfolio": [{
        "name": "STRATA_OTC.csv",
        "data": "Id,Id Scheme,Strata Trade Type,Broker,CCP,Fund,Trader,Counterparty,Start Date,End Date,Index,Buy Sell,Notional,Fixed Rate,Day Count,Leg 1 Currency,Leg 2 Currency,Leg 1 Notional,Leg 2 Notional,Leg 1 Start Date,Leg 2 Start Date,Leg 1 End Date,Leg 2 End Date,Leg 1 Fixed Rate,Leg 2 Fixed Rate,Leg 1 Direction,Leg 1 Frequency,Leg 2 Direction,Leg 2 Frequency,Leg 1 Index,Leg 2 Index,Trade Date,Leg 1 Day Count,Leg 2 Day Count,Leg 1 Compounding Method,Leg 2 Compounding Method,Leg 1 Inflation First Index Value,Leg 1 Inflation Lag,Leg 1 Inflation Method,Leg 2 Inflation First Index Value ,Portfolio Margin Model,Bilateral Margin Methodology,Pre-calculated IA,Instrument Sub Type\r\n205,OG-Trade,Swap,,,1001,Tom,Barclays,,,,,,,,EUR,EUR,24983574,24983574,12/11/2017,12/11/2017,25/10/2027,25/10/2027,0.883759,,Pay,P12M,Receive,P6M,,EUR-EURIBOR,26/09/2017,Act/360,Act/360,,,,,,,DRIM,,,"
      }],
      "additionalBasePortfolio": [{
        "name": "ADDITIONAL_BASE.csv",
        "data": "Id,Id Scheme,Strata Trade Type,Broker,CCP,Fund,Trader,Counterparty,Start Date,End Date,Index,Buy Sell,Notional,Fixed Rate,Day Count,Leg 1 Currency,Leg 2 Currency,Leg 1 Notional,Leg 2 Notional,Leg 1 Start Date,Leg 2 Start Date,Leg 1 End Date,Leg 2 End Date,Leg 1 Fixed Rate,Leg 2 Fixed Rate,Leg 1 Direction,Leg 1 Frequency,Leg 2 Direction,Leg 2 Frequency,Leg 1 Index,Leg 2 Index,Trade Date,Leg 1 Day Count,Leg 2 Day Count,Leg 1 Compounding Method,Leg 2 Compounding Method,Leg 1 Inflation First Index Value,Leg 1 Inflation Lag,Leg 1 Inflation Method,Leg 2 Inflation First Index Value ,Portfolio Margin Model,Bilateral Margin Methodology,Pre-calculated IA,Instrument Sub Type\r\n206,OG-Trade,Swap,Barclays,LCH,1001,Tom,Barclays,,,,,,,,EUR,EUR,24983574,24983574,12/11/2017,12/11/2017,25/10/2027,25/10/2027,0.883759,,Pay,P12M,Receive,P6M,,EUR-EURIBOR,26/09/2017,Act/360,Act/360,,,,,,,DRIM,,,"
      }],
      "reportingCurrency": "USD",
      "portfolioConstraints": {
        "accountConstraints": [{
          "accountName": "myFund",
          "ccpConstraints": [{
            "ccpName": "LCH",
            "brokerConstraints": [{
              "brokerName": "BARC"
            }, {
              "brokerName": "GS"
            }]
          }, {
            "ccpName": "CME",
            "brokerConstraints": [{
              "brokerName": "BAML"
            }, {
              "brokerName": "BARC"
            }]
          }]
        }]
      },
      "withCmeCrossMarginOptimisation": "true",
      "withEurexCrossMargin" : "true",
      "withJsccCrossMargin" : "false",
      "extraGroupingValue" : "Commodities Desk"
  }'

POST /calcs/v1/base/whatif/v1/calcs

Creates a job to calculate the impact of adding additional trades into an existing base portfolio under different CCP and clearing broker scenarios.

If the job is successfully accepted then the calculation request has been queued for processing.

Request Headers

Header Name Value
Content-Type
Required		 application/json
Accept
Required		 application/json
Authorization
Required		 Bearer <Your access token here>

Request Body Properties

Name Description
incrementalPortfolio
Required		 A list of files that make up the incremental portfolio for use in the scenario, each of type PortfolioDataFile.
additionalBasePortfolio
OPTIONAL		 A list of files that describe changes to apply on top of the base portfolio currently in use by the service, each of type PortfolioDataFile.
reportingCurrency
Required		 The currency that the result is reported in, as an ISO 4217 three-letter currency code.
portfolioConstraints
Required		 An object mapping account name to the constraints to apply to allocations to that account, of type PortfolioConstraints.
withCmeCrossMarginOptimisation
OPTIONAL		 A boolean flag indicating whether the calculation should optimise the portfolios where there are incremental items to benefit from X-margin. Defaults to false.
⚠️Note: X-Margin optimisations may slow down your request significantly.
withEurexCrossMargin
OPTIONAL		 A boolean flag indicating whether the calculation should take into account Eurex X-margin. Defaults to false.
⚠️Note: There is no portfolio optimisation involved, and therefore only the resulting Initial Margin value will change.
withJsccCrossMargin
OPTIONAL		 A boolean flag indicating whether the calculation should take into account JSCC X-margin. Defaults to false.
⚠️Note: There is no portfolio optimisation involved, and therefore only the resulting Initial Margin value will change.
extraGroupingValue
OPTIONAL		 A string value of the extra grouping we want to filter the portfolio and the calculation result by, e.g. by desk within clients organisation .
⚠️Note: The grouping itself needs to be configured before this has an effect, please reach out to your RM if interested.

Request Body Properties / PortfolioDataFile

Name Description
name
Required		 The file name, optionally suffixed with .zip.base64 or .gz.base64 to specify the data encoding.
data
Required		 The portfolio data in either Strata OTC CSV format (with additional columns described below) or a custom format supported for the caller.

Several data encodings are supported for maximum flexibility and to allow faster transmission of large files:

If using Strata OTC CSV format, the following additional columns should be included:

Name Description
FUND The fund that the trade is attributed to.
CCP The CCP that the trade is placed at. Required in additionalBasePortfolio items but optional for incrementalPortfolio items, where its omission indicates that the service should run scenarios to determine the cheapest CCP for the item (alongside any other constraints specified).
BROKER The broker that the trade is placed at. Required in additionalBasePortfolio items but optional for incrementalPortfolio items, where its omission indicates that the service should run scenarios to determine the cheapest broker for the item (alongside any other constraints specified).

Additionally, all items in a PortfolioDataFile must have an Id that is unique across all trades described in the request.

Request Body Properties / PortfolioConstraints

Name Description
accountConstraints
Required		 A list of constraints to be applied to incremental trades based on their allocated account, each of type AccountConstraints. With the exception of where a single, unnamed account is used, all entries in the list must have a unique account name.

Request Body Properties / AccountConstraints

Name Description
accountName The name of the account the constraints apply to. This may be omitted if all trades are allocated to a single, unnamed account.
ccpConstraints
Required		 A list of constraints to be applied by CCP, each of type CcpConstraints. Only CCPs mentioned in the list will be considered for cheapest CCP calculations. All entries in the list must have a unique ccp name.

Request Body Properties / CcpConstraints

Name Description
ccp
Required		 The name of the CCP.
brokerConstraints
Required		 A list of constraints to be applied by broker, each of type BrokerConstraints. Only brokers mentioned in the list will be considered for cheapest broker calculations. All entries in the list must have a unique broker name.

Request Body Properties / BrokerConstraints

Name Description
broker
Required		 The name of the clearing broker.

If the calculation request is accepted then the response will be 202 Accepted with an empty body and the Location header set to the path to the calculation:

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: 0
Location: /calcs/v1/base/whatif/v1/calcs/712c5e5a-c5aa-407e-949e-c42e918b01d6

Response Headers

Header Name Description
Location The path of the newly-created calculation resource, which is relative to the base URI of the API.

Response Codes

Code Description
202 Accepted.
400 Bad request. The request body is invalid. Further details will be provided in the response body if possible.
401 The request lacks valid authentication credentials.
403 The user does not have permission to use this service.

Get what-if calculation

Using curl:

curl https://api.opengamma.com/calcs/v1/base/whatif/v1/calcs/712c5e5a-c5aa-407e-949e-c42e918b01d6 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <Your access token here>'

GET /calcs/v1/base/whatif/v1/calcs/{calcId}

Gets the status and results of a what-if calculation. The calculation must be polled periodically until the status changes from PENDING to COMPLETED.

Path Variables

The path should correspond to that returned in the Location header of the response after creating the calculation.

Name Description
calcId The calculation identifier.

Request Headers

Header Name Value
Content-Type
Required		 application/json
Accept
Required		 application/json
Authorization
Required		 Bearer <Your access token here>

The response body provides results for all scenarios completed so far. Once all scenarios have completed the status returned will change from PENDING to COMPLETE:

{
  "status": "COMPLETE",
  "valuationDate": "2020-01-01",
  "scenarioResults": [
    {
      "accountMarginBreakdowns": [
        {
          "accountName": "myFund",
          "beforeMargin": {
            "margin": {
              "currency": "USD",
              "amount": 5000.0
            },
            "baseMargin": {
              "currency": "USD",
              "amount": 4000.0
            },
            "addOnMargin": {
              "currency": "USD",
              "amount": 1000.0
            },
            "optionPremium": {
              "currency": "USD",
              "amount": 0.0
            },
            "marginDetails": [],
            "brokerCcpBreakdown": [
              {
                "broker": "BARC",
                "ccp": "LCH",
                "margin": {
                  "currency": "USD",
                  "amount": 3000.0
                },
                "baseMargin": {
                  "currency": "USD",
                  "amount": 1500.0
                },
                "addOnMargin": {
                  "currency": "USD",
                  "amount": 600.0
                },
                "optionPremium": {
                  "currency": "USD",
                  "amount": 0.0
                },
                "marginDetails": []
              },
              {
                "broker": "BAML",
                "ccp": "CME",
                "margin": {
                  "currency": "USD",
                  "amount": 2000.0
                },
                "baseMargin": {
                  "currency": "USD",
                  "amount": 2500.0
                },
                "addOnMargin": {
                  "currency": "USD",
                  "amount": 400.0
                },
                "optionPremium": {
                  "currency": "USD",
                  "amount": 0.0
                },
                "marginDetails": []
              }
            ]
          },
          "afterMargin": {
            "margin": {
              "currency": "USD",
              "amount": 4000.0
            },
            "baseMargin": {
              "currency": "USD",
              "amount": 3200.0
            },
            "addOnMargin": {
              "currency": "USD",
              "amount": 800.0
            },
            "optionPremium": {
              "currency": "USD",
              "amount": 0.0
            },
            "marginDetails": [],
            "brokerCcpBreakdown": [
              {
                "broker": "BARC",
                "ccp": "LCH",
                "margin": {
                  "currency": "USD",
                  "amount": 2250.0
                },
                "baseMargin": {
                  "currency": "USD",
                  "amount": 1000.0
                },
                "addOnMargin": {
                  "currency": "USD",
                  "amount": 500.0
                },
                "optionPremium": {
                  "currency": "USD",
                  "amount": 0.0
                },
                "marginDetails": []
              },
              {
                "broker": "BAML",
                "ccp": "CME",
                "margin": {
                  "currency": "USD",
                  "amount": 1750.0
                },
                "baseMargin": {
                  "currency": "USD",
                  "amount": 2200.0
                },
                "addOnMargin": {
                  "currency": "USD",
                  "amount": 300.0
                },
                "optionPremium": {
                  "currency": "USD",
                  "amount": 0.0
                },
                "marginDetails": []
              }
            ]
          },
          "incrementalMargin": {
            "margin": {
              "currency": "USD",
              "amount": -1000.0
            },
            "baseMargin": {
              "currency": "USD",
              "amount": -800.0
            },
            "addOnMargin": {
              "currency": "USD",
              "amount": -200.0
            },
            "optionPremium": {
              "currency": "USD",
              "amount": 0.0
            },
            "marginDetails": [],
            "brokerCcpBreakdown": [
              {
                "broker": "BARC",
                "ccp": "LCH",
                "margin": {
                  "currency": "USD",
                  "amount": -750.0
                },
                "baseMargin": {
                  "currency": "USD",
                  "amount": -500.0
                },
                "addOnMargin": {
                  "currency": "USD",
                  "amount": -100.0
                },
                "optionPremium": {
                  "currency": "USD",
                  "amount": 0.0
                },
                "marginDetails": []
              },
              {
                "broker": "BAML",
                "ccp": "CME",
                "margin": {
                  "currency": "USD",
                  "amount": -250.0
                },
                "baseMargin": {
                  "currency": "USD",
                  "amount": -300.0
                },
                "addOnMargin": {
                  "currency": "USD",
                  "amount": -100.0
                },
                "optionPremium": {
                  "currency": "USD",
                  "amount": 0.0
                },
                "marginDetails": []
              }
            ]
          },
          "standaloneMargin": {
            "margin": {
              "currency": "USD",
              "amount": 1000.0
            },
            "baseMargin": {
              "currency": "USD",
              "amount": 800.0
            },
            "addOnMargin": {
              "currency": "USD",
              "amount": 200.0
            },
            "optionPremium": {
              "currency": "USD",
              "amount": 0.0
            },
            "marginDetails": []
          },
        "crossMarginBreakdown": {
          "etdImBefore": {
            "currency": "USD",
            "amount": 0.0
          },
          "otcImBefore": {
            "currency": "USD",
            "amount": 0.0
          },
          "savingsBefore": {
            "currency": "USD",
            "amount": 0.0
          },
          "etdImAfter": {
            "currency": "USD",
            "amount": 0.0
          },
          "otcImAfter": {
            "currency": "USD",
            "amount": 4311591.546713828
          },
          "savingsAfter": {
            "currency": "USD",
            "amount": 115286.24902821798
          }
        } 
      }
      ],
      "tradeAllocations": [
        {
          "tradeId": "205",
          "broker": "BARC",
          "ccp": "LCH"
        }
      ],
      "isSuccess": true,
      "failures": []
    }
  ]
}

Response Body Properties

Name Description
status The status of the calculation: PENDING or COMPLETE. Partial calculation results may be available even when the status is PENDING.
valuationDate The valuation date of the portfolio and market data used in the margin calculations, in ISO 8601 format.
scenarioResults A list of objects describing the outcome of the completed scenarios, each of type ScenarioResult.

Response Body Properties / ScenarioResult

Name Description
accountMarginBreakdowns A list of items describing the margin breakdown of the scenario per-account, each of type AccountScenarioMarginBreakdown. Will be empty if isSuccess is false.
tradeAllocations A list of items describing the which CCP/broker each trade in the incremental portfolio was placed at in this scenario, each of type TradeAllocation.
isSuccess A boolean value indicating if the scenario completed successfully. A successful scenario is one for which a result was produced. Note - it is possible that individual items in the incremental portfolio may have failed calculation and thus not been included in a successful result. Details of any individual failures will be included in failures.
failures A list of calculation failures, each of type FailureItem.

Response Body Properties / TradeAllocation

Name Description
tradeId The id of the trade (taken from the trade’s description in the incremental portfolio).
broker The id of the broker that the trade was placed at.
ccp The id of the CCP that the trade was placed at.

Response Body Properties / FailureItem

Name Description
reason The reason for the failure, of type FailureReason from Strata.
message The error message.

Response Body Properties / AccountScenarioMarginBreakdown

Name Description
accountName The name of the account to which this breakdown applies. Will be omitted if the caller has only a single, unnamed account.
beforeMargin The total margin before adding the new allocations into the existing portfolio, of type MarginResult.
afterMargin The total margin after adding the new allocations into the existing portfolio, of type MarginResult.
incrementalMargin The change in margin after adding the new allocations into the existing portfolio, of type MarginResult.
standaloneMargin The margin of the new trades and positions alone, assuming no existing portfolio, of type MarginResult. Note - this property will not have the brokerCcpBreakdown populated.
crossMarginBreakdown The breakdown of cross margin before and after running a what-if scenario, of type CrossMarginBreakdown.

Response Body Properties / MarginResult

Name Description
margin The total margin for this entity, of type ScenarioMarginAmount.
baseMargin The total base margin for this entity, of type ScenarioMarginAmount.
addOnMargin The total add-on margin for this entity, of type ScenarioMarginAmount.
optionPremium The total option premium for this entity, of type ScenarioMarginAmount.
marginDetails The list of margin component totals for this entity, each of type MarginDetails.
brokerCcpBreakdown The list of margin totals for this entity split out by Broker and CCP, each of type MarginResultBreakdown.

Response Body Properties / MarginDetails

Name Description
detailName The name of the margin component.
amount The total amount of margin attributed to this component, of type ScenarioMarginAmount.

Response Body Properties / MarginResultBreakdown

Name Description
broker The id of the broker for which this breakdown applies.
ccp The id of the CCP for which this breakdown applies.
margin The margin for the broker-ccp combination, of type ScenarioMarginAmount.
baseMargin The base margin for the broker-ccp combination, of type ScenarioMarginAmount.
addOnMargin The add-on margin for the broker-ccp combination, of type ScenarioMarginAmount.
optionPremium The option premium for the broker-ccp combination, of type ScenarioMarginAmount.
marginDetails The list of margin components for the broker-ccp combination, each of type MarginDetails.

Response Body Properties / ScenarioMarginAmount

Name Description
currency The ISO 4217 currency code for the amount.
amount The amount of margin.

Response Body Properties / CrossMarginBreakdown

Name Description
etdImBefore The ETD IM before running the scenario, taking Cross margin into account, of type ScenarioMarginAmount.
otcImBefore The OTC IM before running the scenario, taking Cross margin into account, of type ScenarioMarginAmount.
savingsBefore The Cross margin savings before running the scenario, of type ScenarioMarginAmount.
etdImAfter The ETD IM after running the scenario, taking Cross margin into account, of type ScenarioMarginAmount.
otcImAfter The OTC IM after running the scenario, taking Cross margin into account, of type ScenarioMarginAmount.
savingsAfter The Cross margin savings after running the scenario, of type ScenarioMarginAmount.

Response Codes

Code Description
200 Success.
400 The request failed, with details of the failure(s).
401 The request lacks valid authentication credentials.
403 The user does not have permission to use this service.