This topic lists Risk API specifications relevant to:
- Futures and Options (F&O) trade/position and portfolio definition
- Outputs relevant to F&O Futures and Options for SPAN
- CME Group's new F&O Futures and Options Margin Model, SPAN 2
Contents
...
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 a futures and options 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.
...
Category | Attribute | Description | json field names & examplesand 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 |
...
Category | Attribute | Description | json field names & and 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&Ofutures and options | |
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 |
...