API 参考：行情接口 (Market Data)¶

CThostFtdcMdApi — 行情 API¶

行情 API 用于连接 CTP 行情前置，订阅和接收实时行情数据。

方法	参数	返回值	说明
`CreateFtdcMdApi(flowPath, bIsUsingUdp=False, bIsMulticast=False)`	`flowPath`: str — 流文件存储路径（须以 `/` 或 `\\` 结尾）	`CThostFtdcMdApi`	静态工厂方法，创建 MdApi 实例
`GetApiVersion()`	无	str	静态方法，返回 API 版本号，如 `"v6.7.7_..."`
`Init()`	无	None	初始化并启动连接（异步，立即返回）
`Join()`	无	int	阻塞等待 API 线程退出，返回退出代码
`Release()`	无	None	释放 API 资源，调用后不可再使用该实例
`GetTradingDay()`	无	str	获取当前交易日（格式 `"YYYYMMDD"`），需登录后调用

方法	参数	说明
`RegisterSpi(pSpi)`	`pSpi`: `CThostFtdcMdSpi` 子类实例或 `None`	注册回调处理器，`None` 取消注册
`RegisterFront(pszFrontAddress)`	`pszFrontAddress`: str — 如 `"tcp://182.254.243.31:30011"`	注册行情前置地址，可多次调用注册多个地址
`RegisterNameServer(pszNsAddress)`	`pszNsAddress`: str	注册名字服务器地址
`RegisterFensUserInfo(pFensUserInfo)`	`pFensUserInfo`: `CThostFtdcFensUserInfoField`	注册 FENS 用户信息

所有 Req* 方法返回 int：0 表示成功发送，-1 表示网络连接失败，-2 表示未处理请求过多，-3 表示每秒发送请求数超限。

方法	参数	说明
`ReqUserLogin(pReqUserLoginField, nRequestID)`	`pReqUserLoginField`: `CThostFtdcReqUserLoginField`; `nRequestID`: int	登录请求
`ReqUserLogout(pUserLogout, nRequestID)`	`pUserLogout`: `CThostFtdcUserLogoutField`; `nRequestID`: int	登出请求

方法	参数	返回值	说明
`SubscribeMarketData(ppInstrumentID)`	`ppInstrumentID`: `list[str]` — 合约代码列表	int	订阅行情，如 `["IF2603", "SA605"]`
`UnSubscribeMarketData(ppInstrumentID)`	`ppInstrumentID`: `list[str]`	int	退订行情
`SubscribeForQuoteRsp(ppInstrumentID)`	`ppInstrumentID`: `list[str]`	int	订阅询价应答
`UnSubscribeForQuoteRsp(ppInstrumentID)`	`ppInstrumentID`: `list[str]`	int	退订询价应答
`ReqQryMulticastInstrument(pQryMulticastInstrument, nRequestID)`	查询字段 + 请求ID	int	查询组播合约

合约代码格式：CZCE（郑商所）使用 3 位格式不带世纪位（如 SA605），其他交易所用 4 位（如 IF2603、rb2605）。

继承此类并重写回调方法以处理行情事件。所有回调方法均在 CTP 内部线程中调用。

方法	参数	触发时机
`OnFrontConnected()`	无	与行情前置建立连接后。此时应发起登录请求
`OnFrontDisconnected(nReason)`	`nReason`: int — 断开原因代码	连接断开时。API 会自动重连，无需手动处理
`OnHeartBeatWarning(nTimeLapse)`	`nTimeLapse`: int — 距上次心跳的秒数	心跳超时警告

断开原因代码： - 0x1001 — 网络读失败 - 0x1002 — 网络写失败 - 0x2001 — 接收心跳超时 - 0x2002 — 发送心跳超时 - 0x2003 — 收到错误报文

方法	参数	说明
`OnRspUserLogin(pRspUserLogin, pRspInfo, nRequestID, bIsLast)`	`pRspUserLogin`: `CThostFtdcRspUserLoginField`; `pRspInfo`: `CThostFtdcRspInfoField`; `nRequestID`: int; `bIsLast`: bool	登录应答。`pRspInfo.ErrorID == 0` 表示成功
`OnRspUserLogout(pUserLogout, pRspInfo, nRequestID, bIsLast)`	同上模式	登出应答
`OnRspError(pRspInfo, nRequestID, bIsLast)`	`pRspInfo`: `CThostFtdcRspInfoField`	错误应答

方法	参数	说明
`OnRspSubMarketData(pSpecificInstrument, pRspInfo, nRequestID, bIsLast)`	`pSpecificInstrument`: `CThostFtdcSpecificInstrumentField`	订阅行情应答。`ErrorID==0` 不代表合约存在，只代表请求被接受
`OnRspUnSubMarketData(pSpecificInstrument, pRspInfo, nRequestID, bIsLast)`	同上	退订行情应答
`OnRtnDepthMarketData(pDepthMarketData)`	`pDepthMarketData`: `CThostFtdcDepthMarketDataField`	核心回调：收到深度行情数据。每个 tick 触发一次
`OnRspSubForQuoteRsp(pSpecificInstrument, pRspInfo, nRequestID, bIsLast)`	同上模式	订阅询价应答
`OnRspUnSubForQuoteRsp(pSpecificInstrument, pRspInfo, nRequestID, bIsLast)`	同上模式	退订询价应答
`OnRtnForQuoteRsp(pForQuoteRsp)`	`pForQuoteRsp`: `CThostFtdcForQuoteRspField`	询价通知

方法	参数	说明
`pyError(type, value, traceback)`	Python 异常信息	回调方法内部异常时自动调用。默认打印到 stderr

重要：OnRtnDepthMarketData 中的 pDepthMarketData 对象在回调返回后会被 CTP 释放。如需保存数据，必须在回调内复制所需字段。

OnRtnDepthMarketData 回调推送的行情快照，包含以下字段：

注意：未成交或无效的价格字段值为 float_info.max（约 1.7976e+308），Python 端显示为 None。

注意：SimNow 环境仅提供一档行情（Bid/Ask 1），二至五档均为 0/None。实盘取决于交易所和期货公司配置。

所有 OnRsp* 回调都包含此字段：

字段	类型	说明
`ErrorID`	int	错误代码。`0` = 成功
`ErrorMsg`	str	错误信息（UTF-8，由 ctp-python 自动从 GBK 转换）