Risk API

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 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
"EOD"

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
"17:43:09"

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
A unique key should be used to identify each portfolio in a request payload

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
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"001"

Required

string

Account ID

User defined account alphanumeric ID

accountId
"Account1"

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
"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"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
Acceptable values can only be integers

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
Acceptable values can only be integers

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
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"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"
"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"C"

Conditional

string

Required if ProductType = OOF, OOC, OOP
Acceptable values are P or C

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

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.

Header

RequestID

User generated Request Id from the margin request message

requestId
"OUTPUT_123456789"

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

Run Number

Run Number field will increment if used multiple times within a specific CycleCode

runNumber
"1"

Pass-Thru

integer

Time

Populated with the current timestamp when the market data file gets created

time
"17:43:09"

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
"CME"

Required

string

Exchange Rate

Exchange rate grouping of related products for margin reporting

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"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
"SPAN2"

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
In the absence of currency breakdown, values will be represented in the portfolio currency

Currency

Currency defined

currency
"USD"

Required

string

See Appendix for complete list of acceptable currencies

Requirement Amounts
Provide transparency into the decomposition of the margin requirement

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
"1.0"

Optional

decimal

This will not show up at the POD or Product Group level.

Total Initial Requirement

Risk Initial Requirement – ANOV

totalInitialMargin
"1.0"

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
"1.0"

Optional

decimal

This value will only show up at the CCP level - currency Amounts.

Valuation Amounts
Valuation amounts refer to price, npv, futures, and options values

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 futures and options

Component Amounts
Component amounts will not be visible for SPAN POD

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
This field is populated only if there is a qty in 'nakedLongQty' in the input portfolio

Naked Short Component

Naked short positions risk amount

nakedShortComponent"1.0"

Optional

decimal

SPAN/SPAN 2 component
This field is populated only if there is a qty in 'nakedShortQty' in the input portfolio

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
"1.0"

Optional

decimal

SPAN/SPAN 2 component
SPAN margin method:
SOM component will show up under the Product Group level for SPAN
SPAN 2 margin method:
SOM component will show up under the POD level for SPAN 2

Implied Offset

Computed benefit of portfolio margining at given reporting level

impliedOffset
"1.0"

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
This field is populated only if there is a qty in 'netQty' in the input portfolio

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
This field is populated only if there is a qty in 'netQty' in the input portfolio

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
This field is populated only if there is a qty in 'netQty' in the input portfolio

InterExchange Spread Credit

Interexchange credits for spread positions at different exchanges

interExchSpreadCredit
"1.0"

Optional

decimal

SPAN component, only present when MarginMethod=SPAN
This field is populated only if there is a qty in 'netQty' in the input portfolio

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
This field is populated only if there is a qty in 'netQty' in the input portfolio

Intercommodity Volatility Credit

Intercommodity Volatility Credit

interCmdtyVolatilityCredit"1.0"

Optional

decimal

SPAN component, only present when MarginMethod=SPAN
This field is populated only if there is a qty in 'netQty' in the input portfolio

Full Value Component

Additional delivery margin charge based on the full contract value

fullValueComponent
"1.0"

Optional

decimal

SPAN/SPAN 2 component

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’

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