`ContextInfo.subscribe_quote` 是 QMT 内置 Python 中用于订阅实时行情数据的函数。订阅后，当指定证券的行情发生变化时，系统自动调用回调函数，将最新的 Tick 数据传递给策略进行处理。该函数适用于盘中实时监控、高频策略和条件触发等场景。

## QMT subscribe_quote 函数原型与适用环境

**【事实】** 函数原型：

```python
ContextInfo.subscribe_quote(stock_code, period, callback, ...)
```

**【事实】** 适用环境与权限要求：

| 环境 | 是否支持 | 说明 |
|------|----------|------|
| 回测环境 | 不适用 | 回测中行情由历史数据驱动，无需订阅 |
| 模拟信号环境 | 不适用 | 信号模式无实时行情 |
| 仿真交易环境 | 支持 | 订阅仿真行情推送 |
| 真实交易环境 | 支持 | 订阅实时行情推送 |
| 所需权限 | 行情权限 | 需在客户端中开通行情权限 |

**【解释】** `subscribe_quote` 主要在盘中实时运行环境中使用。回测环境中行情数据通过 `handlebar` 回调驱动，无需手动订阅。

## QMT subscribe_quote 参数详解

### stock_code — 证券代码

**【事实】** `stock_code` 为 `str` 类型，指定要订阅的证券代码，格式为 `代码.市场`，如 `'600000.SH'`。

### period — 周期

**【事实】** `period` 为 `str` 类型，指定订阅的行情周期。

| 值 | 含义 |
|----|------|
| `'tick'` | Tick 级行情（逐笔推送） |
| `'1d'` | 日线 |
| `'1m'` | 1 分钟线 |
| `'5m'` | 5 分钟线 |
| `'15m'` | 15 分钟线 |
| `'30m'` | 30 分钟线 |
| `'60m'` | 60 分钟线 |

**【建议】** 如需获取最快频率的行情更新，使用 `'tick'` 周期。如仅需分钟级数据，选择对应分钟周期以减少回调频率。

### callback — 回调函数

**【事实】** `callback` 为 `function` 类型，指定行情更新时的回调函数。回调函数接收一个参数，该参数为 Tick 数据字典（`dict` 类型）。

**【事实】** 回调函数签名：

```python
def callback_name(ContextInfo, tick_data):
    # tick_data 为 dict 类型，包含行情字段
    pass
```

**【解释】** 回调函数在行情更新时被异步调用。函数名可自定义，但参数列表需匹配上述签名。

### 可选参数

**【事实】** 函数可能支持额外的可选参数，具体参数以当前客户端版本为准。

## QMT subscribe_quote 回调函数说明

**【事实】** 回调函数接收的 `tick_data` 参数为 `dict` 类型，包含以下字段：

| 字段 | 类型 | 含义 |
|------|------|------|
| `last_price` | float | 最新价 |
| `open` | float | 开盘价 |
| `high` | float | 最高价 |
| `low` | float | 最低价 |
| `last_volume` | int | 最新成交量 |
| `amount` | float | 成交额 |
| `bid_price` | list | 买价列表（最多 10 档） |
| `ask_price` | list | 卖价列表（最多 10 档） |
| `bid_volume` | list | 买量列表（最多 10 档） |
| `ask_volume` | list | 卖量列表（最多 10 档） |
| `stock_code` | str | 证券代码 |
| `time` | int | 时间戳 |

**【解释】** Tick 数据字段的完整说明请参考 [get_full_tick 返回结构](/docs/qmt/builtin-python/api-reference/contextinfo-get-full-tick/)。

**【建议】** 回调函数中不宜执行耗时操作，以免阻塞行情推送。如需复杂计算，建议在回调中仅记录数据，在 `handlebar` 或定时任务中处理。

## QMT subscribe_quote 示例代码

### 订阅单个证券的 Tick 行情

```python
# -*- coding: utf-8 -*-

def init(ContextInfo):
    """策略初始化：订阅实时行情"""
    # 订阅 600000.SH 的 Tick 行情
    ContextInfo.subscribe_quote('600000.SH', 'tick', on_tick)
    print('已订阅 600000.SH 实时行情')

def on_tick(ContextInfo, tick_data):
    """Tick 行情回调函数"""
    stock = tick_data.get('stock_code', '')
    last_price = tick_data.get('last_price', 0)
    volume = tick_data.get('last_volume', 0)

    print(f'[{stock}] 最新价: {last_price}, 成交量: {volume}')

    # 获取五档买卖盘
    bid_price = tick_data.get('bid_price', [])
    ask_price = tick_data.get('ask_price', [])

    if bid_price and ask_price:
        print(f'  买一: {bid_price[0]}, 卖一: {ask_price[0]}')
        spread = ask_price[0] - bid_price[0]
        print(f'  买卖价差: {spread}')

def handlebar(ContextInfo):
    """K 线回调"""
    pass
```

### 订阅多个证券的行情

```python
def init(ContextInfo):
    """订阅多个证券"""
    stocks = ['600000.SH', '000001.SZ', '000002.SZ']
    for stock in stocks:
        ContextInfo.subscribe_quote(stock, 'tick', on_tick)
    print(f'已订阅 {len(stocks)} 只证券的实时行情')

def on_tick(ContextInfo, tick_data):
    """Tick 行情回调函数"""
    stock = tick_data.get('stock_code', '')
    last_price = tick_data.get('last_price', 0)

    # 记录最新价格
    print(f'{stock}: {last_price}')
```

### 条件触发下单示例

```python
def init(ContextInfo):
    """初始化：订阅行情并设置触发条件"""
    ContextInfo.accountid = 'YOUR_ACCOUNT_ID'
    ContextInfo.target_price = 10.50  # 目标买入价
    ContextInfo.triggered = False     # 防止重复下单
    ContextInfo.subscribe_quote('600000.SH', 'tick', on_tick)

def on_tick(ContextInfo, tick_data):
    """价格触发后下单"""
    if ContextInfo.triggered:
        return

    last_price = tick_data.get('last_price', 0)
    print(f'当前价格: {last_price}, 目标价格: {ContextInfo.target_price}')

    # 价格跌至目标价以下时买入
    if last_price > 0 and last_price <= ContextInfo.target_price:
        accountid = ContextInfo.accountid
        passorder(
            0,              # opType: 买入
            0,              # orderType: 股票
            accountid,      # accountid
            '600000.SH',    # orderCode
            0,              # prType: 限价
            last_price,     # price: 当前价
            100,            # volume: 100 股
            'tick_trigger', # strategyName
            2,              # quickTrade: 回调触发
            2001,           # userOrderId
            None
        )
        ContextInfo.triggered = True
        print(f'已触发买入: 600000.SH @ {last_price}')

def handlebar(ContextInfo):
    pass
```

## QMT unsubscribe_quote 取消订阅

**【事实】** 使用 `ContextInfo.unsubscribe_quote` 取消已订阅的行情。

函数原型：

```python
ContextInfo.unsubscribe_quote(stock_code)
```

**【事实】** 参数说明：

| 参数 | 类型 | 含义 |
|------|------|------|
| `stock_code` | str | 要取消订阅的证券代码 |

**【事实】** 示例代码：

```python
def handlebar(ContextInfo):
    if not ContextInfo.is_last_bar():
        return

    # 取消订阅
    ContextInfo.unsubscribe_quote('600000.SH')
    print('已取消订阅 600000.SH 实时行情')
```

**【建议】** 策略停止或不再需要某证券的实时行情时，应及时调用 `unsubscribe_quote` 取消订阅，以释放系统资源。

## QMT subscribe_quote 注意事项

**【事实】** 订阅行为受以下限制：

| 限制项 | 说明 |
|--------|------|
| 订阅数量 | 同一策略的订阅数量可能有限制，具体上限以当前客户端版本为准 |
| 行情权限 | 需开通对应市场的行情权限（如 Level-2 需单独开通） |
| 推送频率 | Tick 推送频率取决于交易所行情源和客户端配置 |
| 回调线程 | 回调函数在独立线程中执行，需注意线程安全 |

**【建议】**
1. 回调函数中不应进行耗时操作，避免阻塞行情推送
2. 回调函数中如需修改全局状态，需注意线程安全，避免数据竞争
3. 多个证券可共用一个回调函数，通过 `tick_data` 中的 `stock_code` 字段区分
4. 回测环境中 `subscribe_quote` 无效，行情由 `handlebar` 驱动
5. 重复订阅同一证券可能导致回调被多次触发，建议订阅前检查是否已订阅

## QMT subscribe_quote 相关函数

| 函数 | 说明 | 链接 |
|------|------|------|
| `ContextInfo.unsubscribe_quote` | 取消行情订阅 | 本页 |
| `ContextInfo.get_full_tick` | 获取全推 Tick 数据 | [get_full_tick](/docs/qmt/builtin-python/api-reference/contextinfo-get-full-tick/) |
| `ContextInfo.get_market_data_ex` | 获取历史 K 线数据 | [get_market_data_ex](/docs/qmt/builtin-python/api-reference/contextinfo-get-market-data-ex/) |
| `ContextInfo.get_last_price` | 获取最新价 | [行情与数据获取](/docs/qmt/builtin-python/api/market-data/) |
| `ContextInfo.get_bid_price` | 获取买盘价格 | [行情与数据获取](/docs/qmt/builtin-python/api/market-data/) |

## QMT subscribe_quote 来源与更新时间

**【事实】** 本页面内容基于 QMT 官方文档整理。

| 项目 | 值 |
|------|-----|
| 数据来源 | QMT 官方文档 |
| 更新时间 | 2026-08-04 |
| 验证时间 | 2026-08-04 |
| 适用版本 | 以当前客户端版本为准 |