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

# Account Events

Receive notifications for account-related events, including:
- Account restrictions and status changes
- Virtual Account (VA) BCAN code approval status changes
- Account closure processing

## Account Update Event

This event is triggered when an Omni-level account's restrictions or status changes.

<Tabs>
<TabItem value="account_update" label="Account Update" default>

### Event Structure

```json
{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "ACCOUNT",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200Z",
    "payload": {
        "account_id": "036UUF6TQA8CD0KHJPEC000000",
        "account_number": "5KT05001",
        "account_type": "CASH",
        "restrictions": [
            "HK_STOCK_NO_TRADE",
            "HK_STOCK_LIQUIDATE_ONLY",
            "US_STOCK_NO_TRADE",
            "US_STOCK_LIQUIDATE_ONLY",
            "CN_STOCK_LIQUIDATE_ONLY",
            "CN_STOCK_NO_TRADE"
        ],
        "update_time": "2025-03-29T07:02:33.200Z",
        "biz_type": "ACCOUNT_UPDATE"
    }
}
```

### 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 `ACCOUNT` |
| `timestamp` | string | Event timestamp in ISO 8601 format |
| `payload` | object | Event payload data |

### Payload Fields

| Field            | Type | Description                                           |
|------------------|------|-------------------------------------------------------|
| `account_id`     | string | Account id                                            |
| `account_number` | string | Account number                                        |
| `account_type`   | string | Account type: `CASH` / `MARGIN`                       |
| `restrictions`   | array | Array of current account restrictions (full snapshot) |
| `update_time`    | string | Update timestamp in ISO 8601 format                   |
| `biz_type`       | string | Business type, fixed as `ACCOUNT_UPDATE`              |

### Restriction Types

The `restrictions` array contains current account restrictions. Each push provides a complete snapshot of all active restrictions:

| Restriction Code | Description |
|------------------|-------------|
| `HK_STOCK_NO_TRADE` | Hong Kong stocks - No trading allowed |
| `HK_STOCK_LIQUIDATE_ONLY` | Hong Kong stocks - Liquidate only (can only close positions) |
| `US_STOCK_NO_TRADE` | US stocks - No trading allowed |
| `US_STOCK_LIQUIDATE_ONLY` | US stocks - Liquidate only (can only close positions) |
| `CN_STOCK_NO_TRADE` | China A-shares - No trading allowed |
| `CN_STOCK_LIQUIDATE_ONLY` | China A-shares - Liquidate only (can only close positions) |

:::info
- Each event push contains a **full snapshot** of current restrictions, not incremental changes
- An empty `restrictions` array means no restrictions are currently active on the account
:::

</TabItem>
</Tabs>

## Virtual Account BCAN Update Event

This event is triggered when a Virtual Account's (VA) BCAN code approval status changes at the exchange.

<Tabs>
<TabItem value="bcan_success" label="BCAN Approved" default>

### Event Structure - Approval Success

When the exchange approves the BCAN code, the corresponding category trading permission is granted for the VA account.

```json
{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "ACCOUNT",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200Z",
    "payload": {
       "account_id": "O3I8NNB882S2BK7MF1ACJ5UTK9",
       "account_number": "VA0000001",
        "account_type": "MARGIN",
        "type": "CN",
        "status": "SUCCESS",
        "update_time": "2025-03-29T07:02:33.200Z",
        "biz_type": "VIRTUAL_ACCOUNT_BCAN_UPDATE"
    }
}
```

### 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 `ACCOUNT` |
| `timestamp` | string | Event timestamp in ISO 8601 format |
| `payload` | object | Event payload data |

### Payload Fields

| Field            | Type | Description                                                 |
|------------------|------|-------------------------------------------------------------|
| `account_id`     | string | Virtual Account id                                          |
| `account_number` | string | Virtual Account number                                      |
| `account_type`   | string | Account type: `CASH` / `MARGIN`                             |
| `type`           | string | BCAN type, currently only `CN` (China A-share) is supported |
| `status`         | string | BCAN status: `SUCCESS` / `FAILED`                           |
| `update_time`    | string | Update timestamp in ISO 8601 format                         |
| `biz_type`       | string | Business type, fixed as `VIRTUAL_ACCOUNT_BCAN_UPDATE`       |

### BCAN Status Values

| Status | Description |
|--------|-------------|
| `SUCCESS` | BCAN code approved by exchange - Trading permission granted |
| `FAILED` | BCAN code rejected by exchange - Trading permission denied |

</TabItem>

<TabItem value="bcan_failed" label="BCAN Rejected">

### Event Structure - Approval Failed

When the exchange rejects the BCAN code, the corresponding category trading permission is denied for the VA account.

```json
{
    "id": "event_c4b2c210-ce32-41d4-a9a1-cfad4fdf191c",
    "event_type": "ACCOUNT",
    "position": "CJO1fxACGAAgADAB",
    "timestamp": "2025-03-29T07:02:33.200Z",
    "payload": {
        "account_id": "O3I8NNB882S2BK7MF1ACJ5UTK9",
        "account_number": "VA0000001",
        "account_type": "MARGIN",
        "type": "CN",
        "status": "FAILED",
        "update_time": "2025-03-29T07:02:33.200Z",
        "biz_type": "VIRTUAL_ACCOUNT_BCAN_UPDATE"
    }
}
```

The field structure is identical to the approval success case, with `status` set to `FAILED`.

</TabItem>
</Tabs>

### Use Cases

Listening to these events can be used for:

1. **Account Status Monitoring**: Track real-time account restriction changes and update UI/access controls accordingly
2. **Trading Permission Management**: Automatically enable or disable trading features based on account restrictions
3. **BCAN Status Tracking**: Monitor Virtual Account BCAN approval status for China A-share trading
4. **Risk Management**: Adjust risk controls and position management when liquidate-only restrictions are applied
5. **Client Notification**: Alert clients about account status changes requiring attention or action
6. **Compliance Monitoring**: Track account restrictions for regulatory and compliance purposes