import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

# 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

```json
{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "INSTRUMENT",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200Z",
    "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:<br/>- `OC`: Tradable<br/>- `CO`: Liquidate only<br/>- `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

```json
{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "INSTRUMENT",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200Z",
    "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