This topic lists Risk API specifications relevant to:
- Futures and Options (F&O) trade/position and portfolio definition
- Outputs relevant to F&O for SPAN
- CME Group's new F&O Margin Model, SPAN 2
Contents
Revision History
Risk API Integration
The Risk API reflects the data structure for integration with two of our margin services as defined below. CME Group will make additional functional and non-functional requirements available to users integrating with the Java API at: Margin Software.
Margin API: A CME Hosted REST Web-Service API. Users will leverage REST methods for PUT, POST, GET and DELETE to margin portfolios. Users will send CME JSON messages through https web service as defined in this document following the workflows outlined in CME Group's Margin Service API documentation.
Java API: A CME Deployed Library for interaction with CME Group's Margin Models. Users will directly integrate their systems with the CME .jar by building Java portfolio objects and processing margin results objects.
Inputs
Inputs for an F&O portfolio will contain the following data definitions for the Risk Portfolio Message. The Risk Portfolio Message structure will be organized by categories and further detailed through a subset of attributes within each category.
Portfolio Data Model
Category | Attribute | Description | json field names & examples | Presence | Data Type | Data Rules |
|---|---|---|---|---|---|---|
Header | RequestID | User generated Request ID for margin request | requestId | Optional | string | |
Version | Version of risk API | Version | Optional | decimal | Users should specifiy the version of the Risk API they are using | |
Sent Time | User generated system create time for message | sentTime"2018-03-01T17:43:09.422Z" | Optional | dateTime | ||
Point In Time | Business Date | Business date of margin run | businessDt"2018-02-28" | Required | date | Date format expressed as: YYYY-MM-DD |
Cycle Code | Defined description to distinguish between different point in time | cycleCode | Optional | string | Acceptable values are: AM, EARLY, ITD, or EOD | |
Run Number | Run Number field will increment if used multiple times within a specific CycleCode | runNumber"1" | Optional | integer | ||
Time | Populated with the current timestamp when the market data file gets created | time | Optional | time | ||
Portfolio | id | User-defined ID for the portfolio, margin results at portfolio level will correspond to this id | id"PORTFOLIO_1" | Conditional | string | Optional for non-omnibus portfolios |
Currency | User Defined Portfoio Currency. | currency"USD" | Required | string | See Appendix for complete list of acceptable values | |
Customer Account Type | Account Type considerations impacting the margin ratio | customerAccountType"HEDGE" | Required | string | Users set the default account type for the portfolio through this attribute Acceptable values are MEMBER, HEDGE, SPECULATOR, HEIGHTENED*, NON_HEIGHTENED*. Omnibus accounts can only be HEDGE, SPEC, HEIGHTENED*, or NON_HEIGHTENED*. *(Note: Values Heightened and Non_Heightened are not yet supported. The values SPECULATOR and HEDGE are implied as HEIGHTENED and NON_HEIGHTENED , respectively.) | |
Omnibus Indicator | Omnibus Indicator | omnibusInd"NO" | Optional | string | Acceptable values are YES or No; Defaults to NO | |
Parent Portfolio ID | ID of the parent portfolio | parentPortfolioId"1.0" | Optional | string | Used for omnibus child portfolios | |
Memo | Free form field which can be used to pass through any information to the response message | Memo | Optional | string | Used to pass additional portfolio referential data between the margin request and margin response | |
Entities | Clearing Firm ID | User defined Clearing firm alphanumeric Id | firmId"001" | Required | string | |
Account ID | User defined account alphanumeric ID | accountId | Required | string | ||
Account Name | User defined name for account | accountName"John Doe" | Optional | string | ||
Origin Type | Used to designate the manner in which transactions, postions, and funds are segregated as required by requlators | originType | Required | string | Acceptable values are: HOUS, CUST, CUSTOMER, HOUSE | |
Fund Segregation Type | Fund segregation type | segregationType"CSEG" | Optional | string | Acceptable values are CSEG, CNSEG, COTC, NSEG, SECURED | |
Positions | Customer Account Type | Account Type considerations impacting the margin ratio | customerAccountType"MEMBER" | Optional | string | Acceptable values are MEMBER, HEDGE, SPECULATOR, HEIGHTENED*, NON_HEIGHTENED*. Omnibus accounts can only be HEDGE, SPEC, HEIGHTENED*, or NON_HEIGHTENED*. *(Note: Values Heightened and Non_Heightened are not yet supported. The values SPECULATOR and HEDGE are implied as HEIGHTENED and NON_HEIGHTENED , respectively.)Users can override the default customer account type that was supplied at the Portfolio level. Acount Override is applied at the Pod, not position, level. If multiple over-rides are present within the same Pod, the deployable software will first prioritize MEMBER type for the Pod if any positions are MEMBER, then prioritize HEDGE, and finally SPECULATOR. |
Net Position | Net quantity is expressed as either positive (long) and negative (short) | netQty"1.0" | Conditional | decimal (can be negative) | Required if portfolio AccountType is not Omnibus | |
Naked Long Quantity | Buy quantity for naked margin treatment (see omnibus/PID notes) | nakedLongQty"1.0" | Conditional | decimal (cannot be negative) | Only allowable for Omnibus account types, but never required | |
Naked Short Quantity | Sell Quantity for naked margin treatment (See omnibus/PID notes) | nakedShortQty"1.0" | Conditional | decimal (cannot be negative) | Only allowable for Omnibus account types, but never required | |
Instrument | Clearing Organization Id | User defined clearing organization | clearingOrganizationId | Required | string | |
Exchange ID | Name of Exchange in which the contracts are listed | exchangeId"CBT" | Required | string | For CME Group Exchanges, acceptable values are CME, CBT, NYMEX, COMEX, NYM, CMX | |
Product Code | CME Clearing House Product Code | productCode"17" | Required | string | ||
Product Type | Name of the product type | productType"FUT" | Required | string | Acceptable values are FUT, OOF, OOP, OOC, FWD | |
Contract Period Code | Maturity Date of Product | periodCode"201809" | Required | string | Example values are: YYYYMM, YYYYMMDD, YYYYMMW1, YYYYMMW2, YYYYMMW3, YYYYMMW4, | |
Put/Call Indicator | Whether the option trade is a PUT or CALL | putCallInd"C" | Conditional | string | Required if ProductType = OOF, OOC, OOP | |
Strike | Strike Price for options | strike"80.00" | Conditional | decimal | Required if ProductType = OOF, OOC, OOP | |
Underlying Period Code | Maturity Date of underlying product | UnderlyingPeriodCode"201809" | Optional | string | Used if ProductType = OOF, OOC, OOP |
ERD Request Data Model
Portfolio Request Use cases
A single user generated portfolio ID will correspond to a margin requirement. The requirement may contain entity information (which the user has provided) and will reflect omnibus and position in delivery as outlined below.
Scenario | Input Comments | Output Comments |
|---|---|---|
Simplest structure | Portfolio contains required fields only | User maps requirement to correspond with portfolio ID |
Undisclosed Omnibus | Portfolio contains portfolio ID and user has option to populate entity information | Response contains portfolio ID and entity information if populated. |
Disclosed Omnibus | Parent Portfolio contains Portfolio ID and Omnibus flag. Positions are optional in the parent. If there are positions, they must be expressed as Naked Long and Naked Short | Results for the Parent Portfolio will be reflected through the Portfolio ID of the Parent and will equal the sum of all child portfolio requirements linked to the parent plus the margin requirement of the parent portfolio positions. |
Positions in Delivery | Can occur under any of the other portfolio request scenarios and positions in deliver must be specified as naked long and naked short quantities | Margin Results will include Positions in Delivery. |
Outputs
This section contains the initial draft for reporting results for Futures and Options portfolios.
The Margin Results Message will be organized at various levels (portfolio, pod, product group) and each level will contain further details for Margin Requirements, valuations, and sensitivities further broken down by currency when applicable. This structure will support results for Futures and Options products margined through SPAN and SPAN 2 risk models.
Currency, Margin, and Valuation requirements may reflect aggregation of the levels below. Sensitivities will not reflect aggregation and will generally be level specific. All requirements at the portfolio level will represent results that combine requirements across risk models. As the requirements are further decomposed to the Pod level, the results will become model specific. Each Pod has a margin method to describe the type of results. At the product group level, results are detailed in margin component amounts which will be conditionally populated based on whether the product group result details are derived from the SPAN or SPAN 2 margin model. The Results Data Overview provides further details around how margin requirements map to specific risk models.
Overview of the Margin Result Structure
Margin Result Structure Explained
Point in time specifies:
- Business date
- Cycle code
- Run number
- Time
Point in time contains an array of portfolios
Each portfolio may contain:
- Entity attributes: – firm ID, account ID, seg (the things that make the account unique), omnibus or not
- Result Details
- An array of currency breakdowns
- An array of CCP's (new generic term for exchange complex)
Each CCP contains:
- Result Details
- An array of currency breakdowns
- An array of pods
Each pod may contain:
- Result Details
- An array of currency breakdowns
- An array of product Groups
Product Group – is always in a currency (new generic term for combined commodity)
Result Details:
- The margin requirement amounts
- The valuation amounts
- Sensitivity Amounts
Margin Results Data Model
Category | Attribute | Description | json field names & examples | Presence; if optional see Data Rules | Data Type | Data Rules |
|---|---|---|---|---|---|---|
Header | RequestID | User generated Request Id from the margin request message | requestId | Pass-Thru | string | |
Version | Version of risk API | version"1.0" | Pass-Thru | string | ||
Sent Time | User generated system create time for message | sentTime"2018-03-01T17:43:10.513Z" | Pass-Thru | dateTime | ||
Point In Time | Business Date | Business date of margin run | businessDt | Pass-Thru | date | Date format expressed as YYYY-MM-DD |
Cycle Code | User defined description to distinguish between different point in time | cycleCode | Pass-Thru | string | Acceptable values are: AM, EARLY, ITD, or EOD | |
Run Number | Run Number field will increment if used multiple times within a specific CycleCode | runNumber | Pass-Thru | integer | ||
Time | Populated with the current timestamp when the market data file gets created | time | Pass-Thru | time | ||
Portfolio | Id | User defined Portfolio Id from the margin request message. Margin results at portfolio level will correspond to this ID | id"PORTFOLIO_1" | Pass-Thru | string | One margin result will be generated per portfolio ID |
Currency | Different currencies can be given for overall portfolio requirements and for each product's performance bond requirements. In this case, portfolio currency | currency"USD" | Pass-Thru | string | See Appendix for complete list of acceptable currencies | |
Customer Account Type | Account Type Considerations | customerAccountType"HEDGE" | Pass-Thru | string | Acceptable values are MEMBER, HEDGE, SPECULATOR, HEIGHTENED*, NON_HEIGHTENED* Omnibus accounts can only be HEDGE, SPEC, HEIGHTENED*, or NON_HEIGHTENED*. *(Note: Values Heightened and Non_Heightened are not yet supported. The values SPECULATOR and HEDGE are implied as HEIGHTENED and NON_HEIGHTENED , respectively.) | |
Omnibus Indicator | Omnibus Indicator - (YES /NO) | omnibusInd"NO" | Pass-Thru | string | ||
Parent Portfolio ID | ID of the parent portfolio | parentPortfolioId"NULL" | Pass-Thru | string | ||
Memo | Free form field used by the user to pass through information | memo | Pass-Thru | string | Used to pass additional portfolio referential data between the margin request and margin response | |
Transaction Count | Represents the number of position records that were successfully processed | transactionCnt | Required | integer | ||
Entities | Clearing Firm Id | User defined Clearing firm alphanumeric Id | firmId "001" | Pass-Thru | string | For cross margining, this field represents the exchange complex id |
Account ID | User defined account alphanumeric ID | accountId"Account1" | Pass-Thru | string | ||
Account Name | User defined name for account | accountName"John Doe" | Pass-Thru | string | ||
Origin Type | Used to designate the manner in which transactions, positions, and funds are segregated as required by regulators | originType"CUSTOMER" | Pass-Thru | string | Values in the response will be populated as either: HOUSE or CUSTOMER | |
Fund Segregation Type | Fund Segregation Type | segregationType"CSEG" | Pass-Thru | string | Result will display the following values: CSEG, CNSEG, COTC, NSEG, SECURED | |
CCP | Clearing Organization Id | CCP abbreviation (CME) | clearingOrganizationId | Required | string | |
| Exchange Rate | Exchange rate grouping of related products for margin reporting | exchangeRt | Optional | string | SPAN margin method: This will not be populated | |
Pod | Pod | Risk based grouping of related products for margin reporting | podId"Ags", "Crude", "Nat Gas", "POD-SPAN" | Required | string | For SPAN products, we will group the requirement into one Pod called POD-SPAN |
| Product Description | Description of Pod Id | productDescription "One-Month SOFR Futures" | Optional | string | SPAN margin method: This will be populated with the description of the product code in the POD Id. SPAN 2 margin method: This will be duplicative of the podId field. | |
Margin Method | Description of which margin method was used for margin calculations | marginMethod | Required | string | Acceptable values are SPAN and SPAN2 | |
Customer Account Type | Account Type considerations impacting the margin ratio | customerAccountType"HEDGE" | Pass-Thru | string | This field indicates how initial margin is calculated for this POD. Acceptable values are MEMBER, HEDGE, SPECULATOR, HEIGHTENED*, NON_HEIGHTENED*. Omnibus accounts can only be HEDGE, SPEC, HEIGHTENED*, or NON_HEIGHTENED*. *(Note: Values Heightened and Non_Heightened are not yet supported. The values SPECULATOR and HEDGE are implied as HEIGHTENED and NON_HEIGHTENED , respectively.) See note in Inputs section regarding account over-ride. | |
Product Group | Product Group ID | Lowest level details of margin results and is contained under pod level | productGroupId "CrudOil_Americas_WTI""ED" | Required | string | This will only show up for SPAN 2 margin mefhod. |
Product Type | Description of the product type | productType"OPT""FUT" | Optional | string | This will only show up at Product Group level. | |
Product Description | Description of the Product Group | productDescription"One-Month SOFR Futures" | Optional | string | This will only show up for SPAN 2 margin mefhod. | |
Currency Amounts | Currency | Currency defined | currency | Required | string | See Appendix for complete list of acceptable currencies |
Requirement Amounts | Risk Maintenance Requirement | Risk maintenance requirement (includes Scan Risk + all Spread credits/charges and SOM) | riskMaintenanceRequirement"1.0" | Required | decimal | At the Product Group level, SOM will not be included in the calculation. |
Futures Options Offset | Risk offset amount between futures and options | futuresOptionsOffset"1.0" | Optional | decimal | This will only show up at Product Group level. | |
Risk Initial Requirement | Risk requirement initial level margin (includes Scan Risk + all Spread credits/charges and SOM) | riskInitialRequirement"1.0" | Optional | decimal | This will not show up at the Product Group level. | |
Total Maintenance Requirement | Risk Maintenance Requirement – ANOV | totalMaintenanceMargin | Optional | decimal | This will not show up at the POD or Product Group level. | |
Total Initial Requirement | Risk Initial Requirement – ANOV | totalInitialMargin | Optional | decimal | This will not show up at the POD or Product Group level. | |
Available Net Option Value | Available Long Option Value – Short Option Value | availableNetOptionValue"1.0" | Optional | decimal | This will not show up at the Product Group level. | |
Cross Model Offset | Cross Model Offset | crossModelOffset | Optional | decimal | This value will only show up at the CCP level - currency Amounts. | |
Valuation Amounts | Option Value Long Equity Style | Option value for long equity style options positions | optionValueLongEquityStyle"1.0" | Optional | decimal | This value will not show up at the Product Group level. |
Option Value Short Equity Style | Option value for short equity style options positions | optionValueShortEquityStyle"1.0" | Optional | decimal | This value will not show up at the Product Group level. | |
Option Value Long Futures Style | Option value for long futures style options positions | optionValueLongFuturesStyle"1.0" | Optional | decimal | This value will not show up at the Product Group level. | |
Optional Value Short Futures Style | Option value for short futures style options positions | optionValueShortFuturesStyle"1.0" | Optional | decimal | This value will not show up at the Product Group level. | |
Non Option Value Long | Value for long non-options positions | nonOptionValueLong"1.0" | Optional | decimal | This value will not show up at the Product Group level. | |
Non Option Value Short | Value for short non-options positions | nonOptionValueShort"1.0" | Optional | decimal | This value will not show up at the Product Group level. | |
Net Present Value | Value for other products like OTC FX and IRS | netPresentValue"1.0" | Optional | decimal | This field is not present for F&O | |
Component Amounts | Liquidity Component | Liquidity risk amount | liquidityComponent"1.0" | Optional | decimal | SPAN 2 component, only present when MarginMethod=SPAN2 |
Concentration Component | Concentration risk amount | concentrationComponent"1.0" | Optional | decimal | SPAN 2 component, only present when MarginMethod=SPAN2 | |
Stress Component | Stress risk amount | stressComponent"1.0" | Optional | decimal | SPAN 2 component, only present when MarginMethod=SPAN2 | |
HVaR Component | HVaR risk amount | "hvarComponent"1.0" | Optional | decimal | SPAN 2 component, only present when MarginMethod=SPAN2 | |
Naked Long Component | Naked long positions risk amount | nakedLongComponent"1.0" | Optional | decimal | SPAN/SPAN 2 component | |
Naked Short Component | Naked short positions risk amount | nakedShortComponent"1.0" | Optional | decimal | SPAN/SPAN 2 component | |
Short Option Minimum | To cover the risks associated with deep-out-of-the-money short options positions. Each margin model assesses a minimum portfolio requirement based on the corresponding short options contained in the portfolio. The performance bond requirement cannot fall below this floor level | shortOptionMinimum | Optional | decimal | SPAN/SPAN 2 component | |
Implied Offset | Computed benefit of portfolio margining at given reporting level | impliedOffset | Optional | decimal | SPAN 2 component, only present when MarginMethod=SPAN2 This field is populated only in Pod level reporting. | |
Scan Risk | The requirement derived by Span which reflects the hypothetical single-day exposure given the Exchange or Clearing Organization's | scanRisk"1.0" | Optional | decimal | SPAN component, only present when MarginMethod=SPAN | |
Intracommodity Spread Charge | Intracommodity Charge: Additional charge that covers the calendar basis risk that may exist for portfolios containing futures and options with different expirations | intraCmdtySpreadCharge"1.0" | Optional | decimal | SPAN component, only present when MarginMethod=SPAN | |
Intercommodity Spread Credit | Intercommodity credit: Performance Bond reduction resulting from offsetting positions in related instruments | interCmdtySpreadCredit"1.0" | Optional | decimal | SPAN component, only present when MarginMethod=SPAN | |
InterExchange Spread Credit | Interexchange credits for spread positions at different exchanges | interExchSpreadCredit | Optional | decimal | SPAN component, only present when MarginMethod=SPAN | |
Spot Charge | Spot Charge: Additional charge that covers the risk of products nearing expiration | spotCharge"1.0" | Optional | decimal | SPAN component, only present when MarginMethod=SPAN | |
Intercommodity Volatility Credit | Intercommodity Volatility Credit | interCmdtyVolatilityCredit"1.0" | Optional | decimal | SPAN component, only present when MarginMethod=SPAN | |
Full Value Component | Additional delivery margin charge based on the full contract value | fullValueComponent | Optional | decimal | SPAN/SPAN 2 component |
ERD/Data Model
List of Currencies
- AUD
- BRL
- GBP
- CAD
- CHF
- CHP
- CLP
- COP
- CNH
- CNY
- CZK
- DKK
- EUR
- HKD
- HUF
- IDR
- ILS
- INR
- JPY
- KRW
- MXN
- MYR
- NZD
- NOK
- PEN
- PHP
- PLN
- RUB
- SEK
- SGD
- THB
- TRY
- TWD
- USD
- ZAR
Changes to Input and Output Data Model
Input
Attribute | Change |
|---|---|
version | Updated to optional field |
cycleCode | Updated to optional field |
Time | New attribute added to PointInTime |
customerAccountType | Updated to required field; added new Heightened and non-heightened values |
clearingOrganizationId | Attribute removed from the Entities block and relocated to the Instrument Block; updated to a required field |
firmId | Updated to a required field |
originType | Updated to a required field |
ledgerBalance openTradeEquity securityOnDeposit | Removed attributes from the structure |
exchangeId | Updated to an required field |
putCallInd | Attribute renamed to ‘putCallInd’ from ‘optionType’; acceptable values updated to only ‘P’ and ‘C’ |
underlyingPeriodCode | Attribute renamed to ‘underlyingPeriodCode’ from ‘undlyPeriodCode’ |
Output
Attribute | Change |
|---|---|
Time | New attribute added to PointInTime |
transactionCnt | New attribute added, representing the number of requests |
pod | New Level “Pod” is introduced between CCP and Product Group replacing the level once referred to as “Product Group” |
podId | New attribute added which groups based on risk of related products for margin reporting |
clearingOrganizationId | Moved this attribute from the Entities block to the CCPs level of the margin response; attribute renamed from ‘ccpId’ to ‘clearingOrganizationId’ |
marginMthd | Moved this attribute from the Product Group level to the Pod level; attribute name changed from ‘MarginMethod’ to ‘marginMthd’ |
Sub Portfolio level | Removed sub-portfolio block from the structure |
accountType | Attribute renamed from ‘AccountType’ to ‘CustomerAccountType’ and to the Portfolio level, ProductGroup level, and Pod Level |
CurrencyAmts | Attribute added under Portfolio level, CCP level, and Pod level |
exchangeRt | Attribute added at CCP level (previously removed) |
requiremntAmts | This attribute has been added at the Portfolio level, CCP level, Pod level, and Product Group level |
riskMaintenanceRequirement | Renamed MaintenanceMargin to riskMaintenanceRequirement |
riskInitialRequirement | Renamed IntialMargin to riskInitialRequirement Updated to be optional field |
liquidityComponent | Attribute added to new componentAmts section of the margin response |
concentrationComponent | Attribute added to new componentAmts section of the margin response |
stressComponent | Attribute added to new componentAmts section of the margin response |
hvarComponent | Attribute added to new componentAmts section of the margin response |
crossModelOffset | Added CrossModelOffset to currentAmounts at the CCP level Added details in data rules |
componentAmts | Added 'ComponentAmounts' as a sub-section to RequirementAmounts at the Pod and Product Group levels; Contains model-specific amount details Added SPAN v SPAN 2 components to data rules Notes on component amounts not applicable for SPAN POD Updated to be optional fields |
shortOptionMin | Changed ShortOptionMinimumCharge toShortOptionMinimum at the Pod and Product Group levels |
vumComponent | Removed vumComponent from componentAmts |
customerAccountType | Added customerAccountType to CCP level |
impliedOffset | Added to new componentAmounts |
valuationAmts | Amounts details section added at the Portfolio level, CCP level, Pod level, and Product Group level |
sensitivityAmts | Removed - these are future state only |
| requirementAmts | updated to be optional amounts, other than riskMaintenanceRequirement, which is required |