SPAN 2 Risk Analysis Framework
- Space Sync for Confluence
This page lists Risk API specifications pertaining to inputs relevant to as futures and options trade/position and portfolio definition and outputs relevant to as Futures and Options for SPAN® and CME Group's new Futures and Options Margin Model, SPAN 2TM. The document also describes the reporting framework and margin results that are present across all outputs from our risk management services including the production parallel margin report, deployable margin software and CME CORE.
Contents
Inputs
Inputs for 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.
Portfolio Data Model
Category | Attribute | Description | json Field Name & Examples | Presence | Data Type | Data Rules |
|---|---|---|---|---|---|---|
Header | RequestID | User generated Request ID for margin request | requestId “INPUT_abc123456789” | Optional | string | |
Version | Version of risk API | Version “1.0” | Optional | decimal | Users should specify the version of the Risk API they are using | |
Sent Time | User generated system create time for message | sentTime | Optional | dateTime | ||
Point In Time | Business Date | Business date of margin run | businessDt | Required | date | Date format expressed as: YYYY-MM-DD |
Cycle Code | Defined description to distinguish between different point in time | cycleCode “EOD” | Optional | string | Acceptable values are: AM, EARLY, ITD, or EOD (Note: Values AM, EARLY, and ITD are not yet supported) | |
Run Number | Run Number field will increment if used multiple times within a specific CycleCode | runNumber | Optional | integer | ||
Time | Populated with the current timestamp when the market data file gets created | time “17:43:09” | Optional | time | ||
Portfolio | id | User-defined ID for the portfolio, margin results at portfolio level will correspond to this id | id | Conditional | string | Required for omnibus portfolios A unique key should be used to identify each portfolio in a request payload |
Currency | User Defined Portfolio Currency. | currency | Required | string | See Appendix for complete list of acceptable values | |
Customer Account Type | Account Type considerations impacting the margin ratio | customerAccountType | 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 | Optional | string | Acceptable values are YES or No; Defaults to NO YES: Customer Account is Omnibus, and would have children only if it’s Partially or Fully Disclosed NO: Customer Account is not Omnibus, and has no children | |
Parent Portfolio ID | ID of the parent portfolio | parentPortfolioId | Optional | string | Used for omnibus child portfolios This field is the linkage between parent and child omnibus relationship | |
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 | Required | string | |
Account ID | User defined account alphanumeric ID | accountId “Account1” | Required | string | ||
Account Name | User defined name for account | accountName | Optional | string | ||
Origin Type | Used to designate the manner in which transactions, positions, and funds are segregated as required by regulators | originType “CUST” | Required | string | Acceptable values are: HOUS, CUST, CUSTOMER, HOUSE Users can only supply one of the listed values; otherwise error message | |
Fund Segregation Type | Fund segregation type | segregationType | Optional | string | Acceptable values are CSEG, CNSEG, COTC, NSEG, SECURED | |
Positions | Customer Account Type | Account Type considerations impacting the margin ratio | customerAccountType | 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. Account 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 | Conditional | decimal (can be negative) | Required if portfolio AccountType is not Omnibus Acceptable values can only be integers | |
Naked Long Quantity | Buy quantity for naked margin treatment (see omnibus/PID notes) | nakedLongQty | Conditional | decimal (cannot be negative) | Only allowable for Omnibus account types, but never required Acceptable values can only be integers | |
Naked Short Quantity | Sell Quantity for naked margin treatment (See omnibus/PID notes) | nakedShortQty | Conditional | decimal (cannot be negative) | Only allowable for Omnibus account types, but never required Acceptable values can only be integers | |
Instrument | Clearing Organization Id | User defined clearing organization | clearingOrganizationId “CME” | Required | string | |
Exchange ID | Name of Exchange in which the contracts are listed | exchangeId | Required | string | For CME Group Exchanges, acceptable values are CME, CBT, NYMEX, COMEX, NYM, CMX | |
Product Code | CME Clearing House Product Code | productCode | Required | string | ||
Product Type | Name of the product type | productType | Required | string | Acceptable values are FUT, OOF, OOP, OOC, FWD | |
Contract Period Code | Maturity Date of Product | periodCode “20180920” “201809W1” | Required | string | Example values are: YYYYMM, YYYYMMDD, YYYYMMW1, YYYYMMW2, YYYYMMW3, YYYYMMW4, YYYYMMW5 | |
Put/Call Indicator | Whether the option trade is a PUT or CALL | putCallInd | Conditional | string | Required if ProductType = OOF, OOC, OOP Acceptable values are P or C | |
Strike | Strike Price for options | strike | Conditional | decimal | Required if ProductType = OOF, OOC, OOP | |
Underlying Period Code | Maturity Date of underlying product | UnderlyingPeriodCode “20180920” “201809W1” | Optional | string | Used if ProductType = OOF, OOC, OOP If an option’s values have multiple similarities (i.e. product code and period code), than this field is required |
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 Positions defined as net | User maps requirement to correspond with portfolio ID |
Undisclosed Omnibus | Portfolio contains portfolio ID and user has option to populate entity information Positions defined as Naked Long and Naked Short | Response contains portfolio ID and entity information if populated. |
Disclosed Omnibus or Partially 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 Child Portfolio contains unique portfolio ID and Entity information and references to Parent Portfolio ID. Positions are required Parent and Child Portfolios sharing a disclosed omnibus relationship must all be sent in the same margin request | 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. The Child Portfolios will contain requirements corresponding to the Child Portfolio ID. The Child Portfolio result will also contain a reference to the Parent Portfolio ID in the entities block for linking results back a particular margin request. |
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 for SPAN 2 will be organized at various levels (portfolio, pod, product group) and each level will contain further details for Margin Requirements and valuations 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. 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 for SPAN 2
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: (new generic term for combined commodity)
Result Details
An array of product Groups
A Currency
Product Group – is always in a currency
Result Details
Result Details are:
The margin requirement amounts
The valuation amounts
Report - Terminology for Key Fields:
Level:
Pod: With SPAN2 margin methodology, margin requirements are calculated at POD level. It is the atomic level where margin calculation occurs.
For SPAN, this is analogues to ‘Combined Commodity’
For SPAN2, this represent grouping of products that are going to be margined using new SPAN2 margin methodology. For Day 1 implementation i.e. Energy asset class, we have two PODs – (1) Crude & Refined products and (2) Natural Gas products
ProductGroup: Product groups level further breaks down the risk from one POD to different Product Groups. A POD can have one or more Product groups. Records with Level=ProductGroup are only going to be available for SPAN2 PODs
A separate report will be shared which would provide mapping of Pod/ProductGroups and associated products.
Portfolio: This represents Portfolio level Risk requirement, and Total requirements including Net Option Value.
For CGM based portfolios, this will represent margin requirement for each customer account id, for each of its performance bond account. If it is an Omnibus account, then at this level, we would show aggregated margin requirement which will be inclusive of its children if any.
For House based portfolios, this will represent margin requirement for each HOUS performance bond account.
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 “OUTPUT_123456789” | Pass-Thru | string | |
Version | Version of risk API | version | Pass-Thru | string | ||
Sent Time | User generated system create time for message | sentTime | Pass-Thru | dateTime | ||
Point In Time | Business Date | Business date of margin run | businessDt “2018-02-28” | Pass-Thru | date | Date format expressed as YYYY-MM-DD |
Cycle Code | User defined description to distinguish between different point in time | cycleCode “EOD” | Pass-Thru | string | Acceptable values are: AM, EARLY, ITD, or EOD (Note: Values AM, EARLY, and ITD are not yet supported) | |
Run Number | Run Number field will increment if used multiple times within a specific CycleCode | runNumber “1” | Pass-Thru | integer | ||
Portfolio | Id | User defined Portfolio Id from the margin request message. Margin results at portfolio level will correspond to this ID | id | 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 | Pass-Thru | string | See Appendix for complete list of acceptable currencies | |
Customer Account Type | Account Type Considerations | customerAccountType | 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 | Pass-Thru | string | ||
Parent Portfolio ID | ID of the parent portfolio | parentPortfolioId | 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 | Pass-Thru | string | For cross margining, this field represents the exchange complex id |
Account ID | User defined account alphanumeric ID | accountId | Pass-Thru | string | ||
Origin Type | Used to designate the manner in which transactions, positions, and funds are segregated as required by regulators | originType | Pass-Thru | string | Values in the response will be populated as either: HOUSE or CUSTOMER | |
CCP | Clearing Organization Id | CCP abbreviation (CME) | clearingOrganizationId “CME” | Required | string | |
Exchange Rate | Exchange rate from margin request currency to reported currency | exchangeRt | Optional | string | SPAN margin method: This will not be populated SPAN 2 margin method: This will be present for SPAN and SPAN 2 products when running for SPAN 2 market data | |
Pod
| Pod | Risk based grouping of related products for margin reporting | podId | Required | string | For SPAN products, each SPAN BFCC code will be it’s own POD Id. |
Product Description | Description of the Pod Id | productDescription | 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 “SPAN2” | Required | string | Acceptable values are SPAN and SPAN2 | |
Customer Account Type | Account Type considerations impacting the margin ratio. This field indicates how initial margin is calculated for this Pod. | customerAccountType | 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. | |
Currency | Currency defined | currency “USD” | Required | string | See Appendix for complete list of acceptable currencies | |
Product Group This level is only applicable if PODs that have SPAN 2 margin method. | Product Group ID | Lowest level details of margin results and is contained under pod level | productGroupId | Optional | string | This will only show up for SPAN 2 margin method. |
Product Type |
How was your Client Systems Wiki Experience? Submit Feedback
Copyright © 2024 CME Group Inc. All rights reserved.