Instrument Events

Receive notifications for instrument property changes, including:

• Trading permission changes (Tradable/Liquidate only/Non-Tradable)
• Shortable status changes (Shortable/Non-Shortable)
• Marginable status changes
• ETF properties changes (crypto ETF, leveraged ETF, etc.)

Trading Property Change Event

This event is triggered when an instrument's trading-related properties are updated.

Event Structure

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "INSTRUMENT",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "instrument_id": "10152734329",
        "status": "NT",
        "shortable": "true",
        "marginable": "true",
        "biz_type": "PROPERTY_CHANGE"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
position	string	Cursor for event replay; re-pushes subsequent events within the current business type.
event_type	string	Event type, fixed as INSTRUMENT
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
instrument_id	string	Unique instrument identifier
status	string	Trading status: - OC: Tradable - CO: Liquidate only - NT: Non-Tradable
shortable	string	Whether shortable: true / false
marginable	string	Whether margin trading supported: true / false
biz_type	string	Business type, fixed as PROPERTY_CHANGE

Status Values

Trading status (status) values:

Value	Description
OC	Tradable - Instrument can be bought and sold normally
CO	Liquidate only - Can only sell existing positions, cannot open new positions
NT	Non-Tradable - No trading operations allowed

Use Cases

Listening to this event can be used for:

1. Trading Permission Monitoring: Get real-time updates on instrument trading permission changes and update UI displays accordingly
2. Short Status Tracking: Monitor changes in shortable status and adjust trading strategies
3. Risk Management: Adjust positions and risk controls based on margin requirement changes

---

Basic Property Change Event

This event is triggered when an instrument's basic properties (such as ETF properties) are updated.

Event Structure

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "INSTRUMENT",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "instrument_id": "10152734329",
        "crypto_etf": "false",
        "etf_leveraged_flag": "YES",
        "etf_leveraged_factor": "-1.0",
        "single_stock_etf": "false",
        "inverse_etf": "false",
        "biz_type": "BASIC_PROPERTY_CHANGE"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
position	string	Cursor for event replay; re-pushes subsequent events within the current business type.
event_type	string	Event type, fixed as INSTRUMENT
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
instrument_id	string	Unique instrument identifier
crypto_etf	string	Whether crypto ETF: true / false. Empty if not ETF
etf_leveraged_flag	string	Whether leveraged ETF: YES / NO. Empty if not ETF
etf_leveraged_factor	string	ETF leverage factor. Empty if not ETF. Negative value for inverse ETF, positive value for regular leveraged ETF
single_stock_etf	string	Whether single stock ETF: true / false. Empty if not ETF
inverse_etf	string	Whether inverse ETF: true / false. Empty if not ETF
biz_type	string	Business type, fixed as BASIC_PROPERTY_CHANGE

Use Cases

Listening to this event can be used for:

1. ETF Product Monitoring: Track updates to ETF-specific properties
2. Risk Classification: Identify high-risk products like leveraged or inverse ETFs
3. Product Filtering: Filter instruments based on ETF characteristics (crypto ETF, single stock ETF, etc.)
4. Investment Strategy: Adjust strategies based on leverage factors and ETF types

---

New Event Contract Instrument Event

This event is triggered when a new event contract instrument is listed.

Event Structure

{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "INSTRUMENT",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200962333Z",
    "payload": {
        "series_symbol": "KXRATECUTCOUNT",
        "series_name": "Number of Rate Cuts",
        "instrument_id": "502257268",
        "symbol": "KXRATECUTCOUNT-25DEC31-T3",
        "name": "Will the Fed cut rates 3 times?",
        "yes_condition": "Exactly 3 cuts",
        "last_trading_date": "2025-12-31",
        "status": "LISTING",
        "tradable_status": "NT",
        "can_close_early": true,
        "expected_exp_date": "2025-12-31",
        "latest_exp_date": "2026-01-01",
        "payout_date": "2025-12-31",
        "biz_type": "NEW_EC_INSTRUMENT"
    }
}

Response Fields

Field	Type	Description
id	string	Unique event identifier
position	string	Cursor for event replay; pass this value to continue consuming from this point
event_type	string	Event type, fixed as INSTRUMENT
timestamp	string	Event timestamp in ISO 8601 format
payload	object	Event payload data

Payload Fields

Field	Type	Description
series_symbol	string	Event contract series symbol
series_name	string	Event contract series display name
instrument_id	string	Unique instrument identifier
symbol	string	Instrument symbol
name	string	Instrument display name
yes_condition	string	Settlement condition for Yes
last_trading_date	string	Last trading date (YYYY-MM-DD)
status	string	Instrument lifecycle status, e.g. LISTING
tradable_status	string	Trading permission status (OC/CO/NT)
can_close_early	boolean	Whether early close is supported
expected_exp_date	string	Expected expiry date (YYYY-MM-DD)
latest_exp_date	string	Latest possible expiry date (YYYY-MM-DD)
payout_date	string	Payout date (YYYY-MM-DD)
biz_type	string	Business type, fixed as NEW_EC_INSTRUMENT

Use Cases

Listening to this event can be used for:

1. New Listing Discovery: Receive newly listed event contract instruments in real time
2. Product Metadata Sync: Keep instrument master data (name, symbol, expiry, payout date) up to date
3. Trading Readiness: Determine whether the instrument is tradable and supports early close