| 參數 |
類型 |
説明 |
| notify_type |
[SysNotifyType](./common.md#9783) |
通知類型 |
| sub_type |
[ProgramStatusType](./common.md#3971) |
子類型。當 notify_type == SysNotifyType.PROGRAM_STATUS 時，sub_type 返回程式狀態類型 |
| [GtwEventType](./common.md#4243) |
子類型。當 notify_type == SysNotifyType.GTW_EVENT 時，sub_type 返回 OpenD 事件通知類型 |
| 0 |
當 notify_type != SysNotifyType.PROGRAM_STATUS 且 notify_type != SysNotifyType.GTW_EVENT 時，sub_type 返回 0 |
| msg |
dict |
事件資訊。當 notify_type == SysNotifyType.CONN_STATUS 時，msg 返回 連接狀態事件資訊 字典 |
| 事件資訊。當 notify_type == SysNotifyType.QOT_RIGHT 時，msg 返回 行情權限事件資訊 字典 |
* **連接狀態事件資訊** 字典結構如下（連接狀態類型為 bool，True 表示連接正常，False 表示連接斷開）:
```protobuf
{
'qot_logined': bool1,
'trd_logined': bool2,
}
```
* **行情權限事件資訊** 字典結構如下（點擊瞭解 [行情權限](../quote/quote.md#5731)）:
```protobuf
{
'hk_qot_right': value1,
'hk_option_qot_right': value2,
'hk_future_qot_right': value3,
'us_qot_right': value4,
'us_option_qot_right': value5,
'us_future_qot_right': value6, // 已廢棄
'cn_qot_right': value7,
'us_index_qot_right': value8,
'us_otc_qot_right': value9,
'sg_future_qot_right': value10,
'jp_future_qot_right': value11,
'us_future_qot_right_cme': value12,
'us_future_qot_right_cbot': value13,
'us_future_qot_right_nymex': value14,
'us_future_qot_right_comex': value15,
'us_future_qot_right_cboe': value16,
}
```
* **Example**
```python
import time
from futu import *
class SysNotifyTest(SysNotifyHandlerBase):
def on_recv_rsp(self, rsp_str):
ret_code, data = super(SysNotifyTest, self).on_recv_rsp(rsp_str)
notify_type, sub_type, msg = data
if ret_code != RET_OK:
logger.debug("SysNotifyTest: error, msg: {}".format(msg))
return RET_ERROR, data
if notify_type == SysNotifyType.GTW_EVENT: # OpenD 事件通知
print("GTW_EVENT, type: {} msg: {}".format(sub_type, msg))
elif notify_type == SysNotifyType.PROGRAM_STATUS: # 程序狀態變化通知
print("PROGRAM_STATUS, type: {} msg: {}".format(sub_type, msg))
elif notify_type == SysNotifyType.CONN_STATUS: ## 連接狀態變化通知
print("CONN_STATUS, qot: {}".format(msg['qot_logined']))
print("CONN_STATUS, trd: {}".format(msg['trd_logined']))
elif notify_type == SysNotifyType.QOT_RIGHT: # 行情權限變化通知
print("QOT_RIGHT, hk: {}".format(msg['hk_qot_right']))
print("QOT_RIGHT, hk_option: {}".format(msg['hk_option_qot_right']))
print("QOT_RIGHT, hk_future: {}".format(msg['hk_future_qot_right']))
print("QOT_RIGHT, us: {}".format(msg['us_qot_right']))
print("QOT_RIGHT, us_option: {}".format(msg['us_option_qot_right']))
print("QOT_RIGHT, cn: {}".format(msg['cn_qot_right']))
print("QOT_RIGHT, us_index: {}".format(msg['us_index_qot_right']))
print("QOT_RIGHT, us_otc: {}".format(msg['us_otc_qot_right']))
print("QOT_RIGHT, sg_future: {}".format(msg['sg_future_qot_right']))
print("QOT_RIGHT, jp_future: {}".format(msg['jp_future_qot_right']))
print("QOT_RIGHT, us_future_cme: {}".format(msg['us_future_qot_right_cme']))
print("QOT_RIGHT, us_future_cbot: {}".format(msg['us_future_qot_right_cbot']))
print("QOT_RIGHT, us_future_nymex: {}".format(msg['us_future_qot_right_nymex']))
print("QOT_RIGHT, us_future_comex: {}".format(msg['us_future_qot_right_comex']))
print("QOT_RIGHT, us_future_cboe: {}".format(msg['us_future_qot_right_cboe']))
return RET_OK, data
quote_ctx = OpenQuoteContext(host='127.0.0.1', port=11111)
handler = SysNotifyTest()
quote_ctx.set_handler(handler) # 設置回調
time.sleep(15) # 設置腳本接收 OpenD 的推送持續時間為15秒
quote_ctx.close() # 結束後記得關閉當條連接，防止連接條數用盡`
```
---
---
# 通用定義
## API 調用結果
> **RET_CODE**
* `RET_OK`
成功
* `RET_ERROR`
失敗
## 協議格式
> **ProtoFMT**
* `Protobuf`
Google Protobuf 格式
* `Json`
Json 格式
## 封包加密演算法
## 程式狀態類型
> **ProgramStatusType**
* `NONE`
未知
* `LOADED`
已完成必要模塊加載
* `LOGING`
登錄中
* `NEED_PIC_VERIFY_CODE`
需要圖形驗證碼
* `NEED_PHONE_VERIFY_CODE`
需要手機驗證碼
* `LOGIN_FAILED`
登錄失敗
* `FORCE_UPDATE`
客端戶版本過舊
* `NESSARY_DATA_PREPARING`
正在獲取必要資訊
* `NESSARY_DATA_MISSING`
缺少必要資訊
* `UN_AGREE_DISCLAIMER`
未同意免責聲明
* `READY`
正常可用狀態
* `FORCE_LOGOUT`
OpenD 登入後被強制登出
## 網關事件通知類型
> **GtwEventType**
* `LocalCfgLoadFailed`
本地設定檔載入失敗
* `APISvrRunFailed`
網關監聽服務運行失敗
* `ForceUpdate`
強制更新網關
* `LoginFailed`
登入富途伺服器失敗
* `UnAgreeDisclaimer`
未同意免責聲明，無法執行
* `LOGIN_FAILED`
登錄失敗
* `NetCfgMissing`
缺少網絡連線設定
* `KickedOut`
帳戶被強制下線
* `LoginPwdChanged`
登入密碼已更改
* `BanLogin`
牛牛後台不允許此帳戶登入
* `NeedPicVerifyCode`
登錄需要輸入圖形驗證碼
* `NeedPhoneVerifyCode`
登錄需要輸入手機驗證碼
* `AppDataNotExist`
程式封包資料遺失
* `NessaryDataMissing`
必要資料同步失敗
* `TradePwdChanged`
交易密碼變更通知
* `EnableDeviceLock`
需啟用裝置鎖
## 系統通知類型
> **SysNotifyType**
* `GTW_EVENT`
網關事件
* `PROGRAM_STATUS`
程式狀態變化
* `CONN_STATUS`
與後台伺服器的連線狀態變化
* `QOT_RIGHT`
行情權限變化
## 封包唯一識別碼
**PacketID**
```protobuf
message PacketID
{
required uint64 connID = 1; //當前 TCP 連接的連接 ID，一條連接的唯一標識，InitConnect 協議會返回
required uint32 serialNo = 2; //自增序列號
}
```
## 程式狀態
**ProgramStatus**
```protobuf
message ProgramStatus
{
required ProgramStatusType type = 1; //當前狀態
optional string strExtDesc = 2; // 額外描述
}
```
---
---
# 底層協議介紹
Futu API 是富途為主流的程式語言（Python、Java、C#、C++、JavaScript）封裝的 API SDK，以方便您調用，降低策略開發難度。
這部分主要介紹策略腳本與 OpenD 服務之間通訊的底層協議，適用於非上述 5 種程式語言用戶，自行對接實現底層裸協議。
:::tip 提示
* 如果您使用的程式語言在上述的 5 種主流程式語言之內，可以直接跳過這部分內容。
:::
## 協議請求流程
* 建立連接
* 初始化連接
* 請求數據或接收推送數據
* 定時發送 KeepAlive 保持連接
## 協議設計
協議數據包括協議頭以及協議體，協議頭固定欄位，協議體根據具體協議決定。
### 協議頭
```
struct APIProtoHeader
{
u8_t szHeaderFlag[2];
u32_t nProtoID;
u8_t nProtoFmtType;
u8_t nProtoVer;
u32_t nSerialNo;
u32_t nBodyLen;
u8_t arrBodySHA1[20];
u8_t arrReserved[8];
};
```
欄位|説明
:-|:-
szHeaderFlag|包頭起始標誌，固定為“FT”
nProtoID|協議 ID
nProtoFmtType|協議格式類型，0 為 Protobuf 格式，1 為 Json 格式
nProtoVer|協議版本，用於迭代兼容，目前填 0
nSerialNo|包序列號，用於對應請求包和回傳封包 / 回傳資料，要求遞增
nBodyLen|包體長度
arrBodySHA1|包體原始數據(解密後)的 SHA1 雜湊值 (Hash)
arrReserved|保留 8 位元組 (Byte)擴展
::: tip 提示
* u8_t 表示 8 位無符號整數，u32_t 表示 32 位無符號整數
* OpenD 內部處理使用 Protobuf，因此協議格式建議使用 Protobuf，減少 Json 轉換開銷
* nProtoFmtType 欄位指定了包體的數據類型，回傳封包 / 回傳資料會回對應類型的數據；推送協議數據類型由 OpenD 配置檔案指定
* **arrBodySHA1 用於驗證請求數據在網絡傳輸前後的一致性，必須正確填入**
* **協議頭的二進制流使用的是小端位元組 (Byte)序，即一般不需要使用 ntohl 等相關函數轉換數據**
:::
### 協議體
#### Protobuf 協議請求包體結構
```
message C2S
{
required int64 req = 1;
}
message Request
{
required C2S c2s = 1;
}
```
#### Protobuf 協議回應包體結構
```
message S2C
{
required int64 data = 1;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType，返回結果
optional string retMsg = 2;
optional int32 errCode = 3;
optional S2C s2c = 4;
}
```
欄位|説明
:-|:-
c2s|請求參數結構
req|請求參數，實際根據協議定義
retType|請求結果
retMsg|若請求失敗，説明失敗原因
errCode|若請求失敗對應錯誤碼
s2c|回應數據結構，部分協議不返回數據則無該欄位
data|回應數據，實際根據協議定義
::: tip 提示
* 包體格式類型請求包由協議頭 nProtoFmtType 指定，OpenD 主動推送格式在 [InitConnect](../ftapi/init.md#1061) 設置。
* 原始協議檔案格式是以 Protobuf 格式定義，若需要 json 格式傳輸，建議使用 protobuf3 的介面 / API直接轉換成 json。
* 枚舉值欄位定義使用有符號整形，註解指明對應枚舉，枚舉一般定義於 Common.proto，Qot_Common.proto，Trd_Common.proto 檔案中。
* 協議中價格、百分比等數據用浮點類型來傳輸，直接使用會有精度問題，需要根據精度（如協議中未指明，預設小數點後三位）做四捨五入之後再使用。
:::
## 心跳保活
```protobuf
syntax = "proto2";
package KeepAlive;
option java_package = "com.futu.openapi.pb";
option go_package = "github.com/futuopen/ftapi4go/pb/keepalive";
import "Common.proto";
message C2S
{
required int64 time = 1; //客户端發包時的格林威治時間戳，單位秒
}
message S2C
{
required int64 time = 1; //伺服器回傳封包 / 回傳資料時的格林威治時間戳，單位秒
}
message Request
{
required C2S c2s = 1;
}
message Response
{
required int32 retType = 1 [default = -400]; //RetType,返回結果
optional string retMsg = 2;
optional int32 errCode = 3;
optional S2C s2c = 4;
}
```
* **介紹**
心跳保活
* **協議 ID**
1004
* **使用**
根據[初始化連結](./init.md#1061)返回的心跳保活間隔時間，向 OpenD 發送保活協議
## 加密通訊流程
* 若 OpenD 配置了加密，[InitConnect](../ftapi/init.md#1061) 初始化連接協議必須使用 [RSA](../qa/other.md#9747) 公鑰加密，後續其他協議使用 InitConnect 返回的隨機密鑰進行 AES 加密通訊。
* OpenD 的加密流程借鑑了 SSL 協議，但考慮到一般是本地部署服務和應用，簡化了相關流程，OpenD 與接入 Client 共用了同一個 [RSA](../qa/other.md#9747) 私鑰檔案，請妥善保存和分發私鑰檔案。
* 可到這個 [網址](http://web.chacuo.net/netrsakeypair) 在線生成隨機 [RSA](../qa/other.md#9747) 密鑰對，密鑰格式必須為 PCKS#1，密鑰長度 512，1024 都可以，不要設置密碼，將生成的私鑰複製保存到檔案中，然後將私鑰檔案路徑配置到 [OpenD 配置](../opend/opend-cmd.md#1028) 約定的 **rsa_private_key** 配置項中。
* **建議有實盤交易的用戶配置加密，避免賬户和交易資訊泄露。**
## RSA 加解密
* [OpenD 配置](../opend/opend-cmd.md#1028) 約定 **rsa_private_key** 為私鑰檔案路徑
* OpenD 與接入客户端共用相同的私鑰檔案
* RSA 加解密僅用於 InitConnect 請求，用於安全獲取其它請求協議的對稱加密 Key
* OpenD 的 [RSA](../qa/other.md#9747) 密鑰為 1024 位，填充方式 PKCS1，公鑰加密，私鑰解密，公鑰可通過私鑰生成
* Python API 參考實現：[RsaCrypt](https://github.com/FutunnOpen/py-futu-api/tree/master/futu/common/sys_config.py) 類的 encrypt / decrypt 介面 / API
### 發送數據加密
* RSA 加密規則:若密鑰位數是 key_size，單次加密串的最大長度為 (key_size)/8 - 11，目前位數 1024，一次加密長度可定為 100。
* 將明文數據分成一個或數個最長 100 位元組 (Byte)的小段進行加密，拼接分段加密數據即為最終的 Body 加密數據。
### 接收數據解密
* RSA 解密同樣遵循分段規則，對於 1024 位密鑰，每小段待解密數據長度為 128 位元組 (Byte)。
* 將密文數據分成一個或數個 128 位元組 (Byte)長的小段進行解密，拼接分段解密數據即為最終的 Body 解密數據。
## AES 加解密
* 加密 key 由 InitConnect 協議返回
* 預設使用的是 AES 的 ecb 加密模式。
* Python API 參考實現: [ConnMng](https://github.com/FutunnOpen/py-futu-api/tree/master/futu/common/conn_mng.py) 類的 encrypt_conn_data / decrypt_conn_data 介面 / API
### 發送數據加密
* AES 加密要求源數據長度必須是 16 的整數倍，故需補‘0’對齊後再加密，記錄 mod_len 為源數據長度與 16 取模值。
* 因加密前有可能對源數據作修改，故需在加密後的數據尾再增加一個 16 位元組 (Byte)的填充數據塊，其最後一個位元組 (Byte)賦值 mod_len，其餘位元組 (Byte)賦值‘0’，將加密數據和額外的填充數據塊拼接作為最終要發送協議的 body 數據。
### 接收數據解密
* 協議 body 數據，先將最後一個位元組 (Byte)取出，記為 mod_len，然後將 body 截掉尾部 16 位元組 (Byte)填充數據塊後再解密（與加密填充額外數據塊邏輯對應）。
* mod_len 為 0 時，上述解密後的數據即為協議返回的 body 數據，否則需截掉尾部(16 - mod_len)長度的用於填充對齊的數據。
---
---
# OpenD 相關
## Q1：OpenD 因未完成“問卷評估及協議確認”自動退出
A: 您需要進行相關問卷評估及協議確認，才可以使用 OpenD，請先 [前往完成](https://www.futunn.com/about/api-disclaimer?lang=zh-CN)。
## Q2：OpenD 因”程式內置數據不存在“退出
A: 一般因權限問題導致自帶數據拷貝失敗，可以嘗試將程式目錄下
| 市場 |
品類 |
市場狀態 |
時間段（當地時間） |
| 香港市場 |
證券類產品（含股票、ETFs、窩輪、牛熊、界內證） |
* NONE：無交易 |
CST 08:55 - 09:00 |
| * AUCTION：盤前競價 |
CST 09:00 - 09:20 |
| * WAITING_OPEN：等待開市 |
CST 09:20 - 09:30 |
| * MORNING：早盤 |
CST 09:30 - 12:00 |
| * REST: 午間休市 |
CST 12:00 - 13:00 |
| * AFTERNOON：午盤 |
CST 13:00 - 16:00 |
| * HK_CAS：港股盤後競價（港股市場增加 CAS 機制對應的市場狀態） |
CST 16:00 - 16:08 |
| * CLOSED：收市 |
CST 16:08 - 08:55（T+1） |
| 期權、期貨（僅日市） |
* NONE：期權待開市 |
CST 08:55 - 09:30 |
| * MORNING：早盤 |
CST 09:30 - 12:00 |
| * REST: 午間休市 |
CST 12:00 - 13:00 |
| * AFTERNOON：午盤 |
CST 13:00 - 16:00 |
| * CLOSED：收市 |
CST 16:00 - 08:55（T+1） |
| 期貨（日夜市） |
* FUTURE_DAY_WAIT_FOR_OPEN：期貨待開市 |
不同品種交易時間不同 |
| * NIGHT_OPEN: 夜市交易時段 |
| * NIGHT_END：夜市收市 |
| * FUTURE_DAY_WAIT_FOR_OPEN：期貨待開市 |
| * FUTURE_DAY_OPEN：日市交易時段 |
| * FUTURE_DAY_CLOSE：日市收市 |
| 美國市場 |
證券類產品（含股票、ETFs） |
* PRE_MARKET_BEGIN：美股盤前交易時段 |
EST 04:00 - 09:30 |
| * AFTERNOON：美股持續交易時段 |
EST 09:30 - 16:00 |
| * AFTER_HOURS_BEGIN：美股盤後交易時段 |
EST 16:00 - 20:00 |
| * AFTER_HOURS_END：美股盤後收市 |
EST 20:00 - 04:00（T+1） |
| * OVERNIGHT：美股夜盤交易時段 |
EST 20:00 - 04:00（T+1） |
| 期權 |
* NONE：期權待開市 |
不同品種交易時間不同 |
| * REST：美指期權午間休市 |
| * AFTERNOON：美股持續交易時段 |
| * TRADE_AT_LAST：美指期權盤尾交易時段 |
| * NIGHT：美指期權夜市交易時段 |
| * CLOSED：收市 |
| 期貨 |
* FUTURE_SWITCH_DATE：美期待開市 |
不同品種交易時間不同 |
| * FUTURE_OPEN：美期交易時段 |
| * FUTURE_BREAK：美期中盤休息 |
| * FUTRUE_BREAK_OVER：美期休息後交易時段 |
| * FUTURE_CLOSE：美期收市 |
| A股市場 |
證券類產品（含股票、ETFs） |
* NONE：無交易 |
CST 08:55 - 09:15 |
| * Auction：盤前競價 |
CST 09:15 - 09:25 |
| * WAITING_OPEN：等待開市 |
CST 09:25 - 09:30 |
| * MORNING：早盤 |
CST 09:30 - 11:30 |
| * REST：午間休市 |
CST 11:30 - 13:00 |
| * AFTERNOON：午盤 |
CST 13:00 - 15:00 |
| * CLOSED：收市 |
CST 15:00 - 08:55（T+1） |
| 新加坡市場 |
期貨 |
* FUTURE_DAY_WAIT_FOR_OPEN：期貨待開市 |
不同品種交易時間不同 |
| * NIGHT_OPEN：夜市交易時段 |
| * NIGHT_END：夜市收市 |
| * FUTURE_DAY_OPEN：日市交易時段 |
| * FUTURE_DAY_CLOSE：日市收市 |
| 日本市場 |
期貨 |
* FUTURE_DAY_WAIT_FOR_OPEN：期貨待開市 |
JST 16:25（T-1）- 16:30（T-1） |
| * NIGHT_OPEN：夜市交易時段 |
JST 16:30（T-1） - 05:30 |
| * NIGHT_END：夜市收市 |
JST 05:30 - 08:45 |
| * FUTURE_DAY_OPEN：日市交易時段 |
JST 08:45 - 15:15 |
| * FUTURE_DAY_CLOSE：日市收市 |
JST 15:15 - 16:25 |
\* CST, EST, JST 分別表示中國時間，美東時間，日本時間
## Q15：接口參數股票代碼的格式
A：
* 使用不同程式語言的用戶，需要的股票代碼的格式不同：
* **Python 用戶**
標的代碼code 使用`exchange_market.symbol`格式,`exchange_market`表示交易所市場，`symbol`表示標的代碼。支援訂閱的標的如下：
| 市場 |
標的類別 |
exchange_market |
example |
| 香港市場 |
證券類產品（含股票、ETFs、窩輪、牛熊、界內證） |
HK |
騰訊控股：HK.00700 |
| 指數 |
HK |
恒生指數：HK.800000 |
| 期貨 |
HK |
恒指期貨2606：HK.HSI2606 |
| 期權 |
HK |
* 股票期權 騰訊 260330 450.00購：HK.TCH260330C450000
* 指數期权 恒指 260330 24000.00購：HK.HSI260330C24000000 |
| 板塊 (建議使用[get_plate_list](../quote/get-plate-list.html) 先取得板塊列表) |
HK |
AI應用股：HK.LIST24037 |
| 美國市場 |
證券類產品（含紐交所、美交所、納斯達克上市的股票、ETFs） |
US |
英偉達：US.NVDA |
| 期權 |
US |
* 股票期權 NVDA 260330 160.00C：US.NVDA260330C160000
* 指數期權 SPXW 260330 6330.00C: US..SPXW260330C6330000 |
| 期貨 |
US |
標普500指數期貨2606：US.ES2606 |
| 板塊 (建議使用[get_plate_list](../quote/get-plate-list.html) 先取得板塊列表) |
US |
半導體精選：US.LIST20077 |
| 指數（暫不支援取得） |
US |
標普500指數：US..SPX |
| A 股市場 |
證券類產品（含股票、ETFs） |
SH/SZ |
貴州茅台：SH.600519 |
| 指數 |
SH/SZ |
上證指數：SH.000001 |
| 板塊 (建議使用[get_plate_list](../quote/get-plate-list.html) 先取得板塊列表) |
SH/SZ |
汽車電子概念：SH.LIST0301 |
| 新加坡市場（暫不支援取得） |
期貨 |
SG |
A50指數期貨2606：SG.CN2606 |
| 日本市場（暫不支援取得） |
期貨 |
JP |
大阪日經指數期貨2606：JP.NK2252606 |
* **非 Python 用戶**
股票結構參見 [Security](../quote/quote.html#3103)。
例如：騰訊控股，參數 market 傳入 QotMarket_HK_Security，參數 code 傳入'00700'。
* 查詢方式：
通過 APP 查看代碼和行情市場：行情 > 自選 > 全部。
行情市場定義，請參考 [這裏](../quote/quote.html#8744)。
## Q16：復權因子相關
A：
### 概述
所謂 [復權](../quote/get-rehab.html#4123) 就是對股價和成交量進行權息修復，按照股票的實際漲跌繪製股價走勢圖，並把成交量調整為相同的股本口徑。
公司行動（如：拆股、合股、送股、轉增股、配股、增發股、分紅）均可能對股價產生影響，而復權計算可對量價進行調整，剔除公司行動的影響，保持股價走勢的連續性。
### 名詞解釋
- 公司行動：上市公司進行一些股權、股票等影響公司股價和股東持倉變化的行為。
- 前復權：保持現有的股價不變，以當前的股價為基準，對以前的股價進行復權計算。
- 後復權：保持先前的股價不變，以過去的股價為基準，對以後的股價進行復權計算。
- 復權因子：即權息修複比例，用於計算復權後的價格及持倉數量。
- 除權除息日：即股權登記日下一個交易日。在股票的除權除息日，證券交易所都要計算出股票的除權除息價，以作為股民在除權除息日開市的參考。其意義是股票股利分配給股東的日期。
### 復權方法
主流的復權計算方法分為兩種：事件法和連乘法；而 Futu API 針對不同市場使用不同的計算方法。
- 事件復權法：通過還原除權除息的各類事件進行復權；存在兩個復權因子（復權因子 A 和 復權因子 B），復權因子 B 主要調整現金分紅對股價的影響，而復權因子 A 調整其他公司行動對股價的影響。
- 連乘復權法：通過復權因子連乘的方式進行復權，只保留 復權因子 A（或將 復權因子 B 置為0），復權因子 A 為 除權除息日前收市價/該日經權息調整後的前收市價。
::: tip 提示
* API 對美股前復權使用連乘法，即將 復權因子 B 置為0。
* API 對除美股以外的標的（A股、港股、新加坡股票等）及美股後復權使用事件法。
:::
### 計算公式
#### 單次復權
- 前復權：
前復權價格 = 不復權價格 × 前復權因子 A + 前復權因子 B
- 後復權：
後復權價格 = 不復權價格 × 後復權因子 A + 後復權因子 B
#### 多次復權
- 前復權：按照時間順序，篩選出大於計算日期的復權因子，優先使用時間較早的復權因子進行復權計算。以兩次復權為例：
- 後復權：按照時間倒序，篩選出小於等於計算日期的復權因子，優先使用時間較晚的復權因子進行復權計算。以兩次復權為例：
### 示例
#### 單次前復權示例
以牧原股份為例：
- 篩選復權因子如下：
除權除息日|股票代碼|方案説明|前復權因子 A |前復權因子 B
:-|:-|:-|:-|:-
2021/06/03|SZ.002714|10轉4.0股派14.61元（含税）|0.71429|-1.04357
- 不復權數據如下：
日期|股票代碼|不復權收市價
:-|:-|:-
2021/06/02|SZ.002714|93.11
2021/06/03|SZ.002714|66.25
- 前復權數據如下：
日期|股票代碼|前復權收市價
:-|:-|:-
2021/06/02|SZ.002714|65.4639719
2021/06/03|SZ.002714|66.25
- 前復權數據計算方法：
牧原股份在 2021/06/03 進行拆股及現金分紅行動（10轉4.0股派14.61元），根據前復權計算公式對 2021/06/02 的收市價進行調整計算，則：前復權價格（65.4639719） = 不復權價格（93.11） × 前復權因子 A（0.71429） + 前復權因子 B（-1.04357）
#### 多次後復權示例
接上一個例子，計算牧原股份在 2021/06/02 的後復權價格：
- 篩選復權因子如下：
除權除息日|股票代碼|方案説明|後復權因子 A |後復權因子 B
:-|:-|:-|:-|:-|
2014/07/04|SZ.002714|10派2.34元（含税）|1|0.234
2015-06-10|SZ.002714|10轉10.0股派0.61元（含税）|2|0.061
2016-07-08|SZ.002714|10轉10.0股派3.53元（含税）|2|0.353
2017-07-11|SZ.002714|10轉8.0股派6.9元（含税）|1.8|0.69
2018-07-03|SZ.002714|10派6.91元（含税）|1|0.691
2019-07-04|SZ.002714|10派0.5元（含税）|1|0.05
2020-06-04|SZ.002714|10轉7.0股派5.5元（含税）|1.7|0.55
- 不復權數據如下：
日期|股票代碼|不復權收市價
:-|:-|:-
2021/06/02|SZ.002714|93.11
- 後復權數據如下：
日期|股票代碼|後復權收市價
:-|:-|:-
2021/06/02|SZ.002714|1152.7226
- 後復權數據計算方法：
為了計算牧原股份在 2021/06/02 的後復權價格，需要將早於 2021/06/02 的復權事件進行一一復權，得到最後的後復權價格，具體計算如下：
---
---
# 交易相關
## Q1：模擬交易相關
A:
### 概述
模擬交易是在真實的市場環境中，用虛擬資金做交易，不會對您的真實帳戶的資產造成影響。
#### 交易時間
模擬交易僅支持在常規交易時段交易，支持美股盤中交易時段、美股盤前盤後時段，不支持美股夜盤、全時段交易和A股港股盤前盤後競價時段交易。詳情可點擊 [模擬交易規則](https://support.futunn.com/topic692)。
#### 支持品類
Futu API 支持模擬交易的品類請參考 [這裏](../intro/intro.md#1396)。
#### 解鎖
與真實交易不同，模擬交易無需對帳戶進行解鎖，即可下單或修改訂單取消訂單。
#### 訂單
1. 訂單類型：限價單和市價單。
2. 修改訂單操作類型：模擬交易不支持使生效、使失效、刪除，僅支持修改訂單、 取消訂單。
3. 成交：模擬交易不支持成交相關操作，包括 [查詢今日成交](../trade/get-order-fill-list.md#7660)、[查詢歷史成交](../trade/get-history-order-fill-list.md#2782)、[響應成交推送回調](../trade/update-order-fill.md#7852)。
4. 有效期限：模擬交易有效期限僅支持當日有效。
5. 賣空：期權和期貨支持賣空。股票僅美股支持賣空。
6. 模擬交易帳戶不支持查詢訂單費用。
7. 模擬交易帳戶不支持查詢現金流水。
8. 在組合期權訂單場景下，支持持倉查詢，暫不支持組合訂單查詢。
#### 操作平台
1. 手機版：我的 — 模擬交易
2. 桌面版：左側模擬 tab
3. 網頁版：[模擬交易界面](https://m-match.futunn.com/simulate/)
4. Futu API：在調用接口時，設置參數交易環境為模擬環境即可。詳見 [如何使用 Futu API 進行模擬交易](../qa/trade.md#3142)。
::: tip 提示
* 以上四種方式只是操作平台不同，四種方式操作的模擬帳戶是共通的。
:::
### 如何使用 Futu API 進行模擬交易？
#### 創建連接
先根據交易品種 [創建相應的連接](../trade/base.md#9291) 。當交易品種是股票或期權時，請使用 `OpenSecTradeContext`。當交易品種是期貨時，請使用 `OpenFutureTradeContext`。
#### 獲取交易業務帳戶列表
使用 [獲取交易業務帳戶列表](../trade/get-acc-list.md#4991) 查看交易帳戶（包括模擬帳戶、真實帳戶）。以 Python 為例：返回欄位交易環境 `trd_env` 為 `SIMULATE`，表示模擬帳戶。
獲取港股模擬交易帳戶，需要指定 filter_trdmarket 爲 TrdMarket.HK，此時會返回2個模擬交易賬號。其中 sim_acc_type = STOCK 爲港股模擬帳戶，sim_acc_type = OPTION 爲港股期權模擬帳戶，sim_acc_type = FUTURES 爲港股期貨模擬帳戶。
獲取美股模擬交易帳戶，需要指定 filter_trdmarket 爲 TrdMarket.US，sim_acc_type = STOCK_AND_OPTION 代表美股融資融券模擬帳戶，可以模擬交易股票和期權。sim_acc_type = FUTURES 爲美國期貨模擬帳戶。
* **Example：Stocks and Options**
```python
from futu import *
trd_ctx = OpenSecTradeContext(filter_trdmarket=TrdMarket.HK, host='127.0.0.1', port=11111, security_firm=SecurityFirm.FUTUSECURITIES)
#trd_ctx = OpenFutureTradeContext(host='127.0.0.1', port=11111, is_encrypt=None, security_firm=SecurityFirm.FUTUSECURITIES)
ret, data = trd_ctx.get_acc_list()
if ret == RET_OK:
print(data)
print(data['acc_id'][0]) # get the first account id
print(data['acc_id'].values.tolist()) # convert to list format
else:
print('get_acc_list error: ', data)
trd_ctx.close()
```
* **Output**
```python
acc_id trd_env acc_type card_num security_firm \
0 281756480572583411 REAL MARGIN 1001318721909873 FUTUSECURITIES
1 9053218 SIMULATE CASH N/A N/A
2 9048221 SIMULATE MARGIN N/A N/A
sim_acc_type trdmarket_auth
0 N/A [HK, US, HKCC]
1 STOCK [HK]
2 OPTION [HK]
```
::: tip 提示
* 模擬交易中，區分股票帳戶和期權帳戶，股票帳戶只能交易股票，期權帳戶只能交易期權；以 Python 為例：返回欄位中模擬帳戶類型 `sim_acc_type` 為 `STOCK`，表示股票帳戶；為`OPTION`，表示期權帳戶。
:::
* **Example: Futures**
```python
from futu import *
#trd_ctx = OpenSecTradeContext(filter_trdmarket=TrdMarket.HK, host='127.0.0.1', port=11111, security_firm=SecurityFirm.FUTUSECURITIES)
trd_ctx = OpenFutureTradeContext(host='127.0.0.1', port=11111, is_encrypt=None, security_firm=SecurityFirm.FUTUSECURITIES)
ret, data = trd_ctx.get_acc_list()
if ret == RET_OK:
print(data)
print(data['acc_id'][0]) # get the first account id
print(data['acc_id'].values.tolist()) # convert to list format
else:
print('get_acc_list error: ', data)
trd_ctx.close()
```
* **Output**
```python
acc_id trd_env acc_type card_num security_firm sim_acc_type \
0 9497808 SIMULATE MARGIN N/A N/A FUTURES
1 9497809 SIMULATE MARGIN N/A N/A FUTURES
2 9497810 SIMULATE MARGIN N/A N/A FUTURES
3 9497811 SIMULATE MARGIN N/A N/A FUTURES
trdmarket_auth
0 [FUTURES_SIMULATE_HK]
1 [FUTURES_SIMULATE_US]
2 [FUTURES_SIMULATE_SG]
3 [FUTURES_SIMULATE_JP]
```
#### 下單
使用 [下單接口](../trade/place-order.md) 時，設置交易環境為模擬環境即可。以 Python 為例：`trd_env = TrdEnv.SIMULATE`。
* **Example**
```python
from futu import *
trd_ctx = OpenSecTradeContext(filter_trdmarket=TrdMarket.HK, host='127.0.0.1', port=11111, security_firm=SecurityFirm.FUTUSECURITIES)
ret, data = trd_ctx.place_order(price=510.0, qty=100, code="HK.00700", trd_side=TrdSide.BUY, trd_env=TrdEnv.SIMULATE)
if ret == RET_OK:
print(data)
else:
print('place_order error: ', data)
trd_ctx.close()
```
* **Output**
```python
code stock_name trd_side order_type order_status order_id qty price create_time updated_time dealt_qty dealt_avg_price last_err_msg remark time_in_force fill_outside_rth
0 HK.00700 騰訊控股 BUY NORMAL SUBMITTING 4642000476506964749 100.0 510.0 2021-10-09 11:34:54 2021-10-09 11:34:54 0.0 0.0 DAY N/A
```
#### 取消訂單修改訂單
使用 [取消訂單接口](../trade/modify-order.md) 時，設置交易環境為模擬環境即可。以 Python 為例： `trd_env = TrdEnv.SIMULATE`。
* **Example**
```python
from futu import *
trd_ctx = OpenSecTradeContext(filter_trdmarket=TrdMarket.HK, host='127.0.0.1', port=11111, security_firm=SecurityFirm.FUTUSECURITIES)
order_id = "4642000476506964749"
ret, data = trd_ctx.modify_order(ModifyOrderOp.CANCEL, order_id, 0, 0, trd_env=TrdEnv.SIMULATE)
if ret == RET_OK:
print(data)
else:
print('modify_order error: ', data)
trd_ctx.close()
```
* **Output**
```python
trd_env order_id
0 SIMULATE 4642000476506964749
```
#### 查詢歷史訂單
使用 [查詢歷史訂單接口](../trade/get-history-order-list.md) 時，設置交易環境為模擬環境即可。以 Python 為例：`trd_env = TrdEnv.SIMULATE`。
* **Example**
```python
from futu import *
trd_ctx = OpenSecTradeContext(filter_trdmarket=TrdMarket.HK, host='127.0.0.1', port=11111, security_firm=SecurityFirm.FUTUSECURITIES)
ret, data = trd_ctx.history_order_list_query(trd_env=TrdEnv.SIMULATE)
if ret == RET_OK:
print(data)
else:
print('history_order_list_query error: ', data)
trd_ctx.close()
```
* **Output**
```python
code stock_name trd_side order_type order_status order_id qty price create_time updated_time dealt_qty dealt_avg_price last_err_msg remark time_in_force fill_outside_rth
0 HK.00700 騰訊控股 BUY ABSOLUTE_LIMIT CANCELLED_ALL 4642000476506964749 100.0 510.0 2021-10-09 11:34:54 2021-10-09 11:37:08 0.0 0.0 DAY N/A
```
### 如何重置模擬帳戶？
目前 Futu API 不支持重置模擬帳戶，您可在手機版使用復活卡重置指定模擬帳戶，重置後帳戶資金將恢復至初始值，歷史訂單將會被清空。
#### 具體操作
手機版：我的 — 模擬交易 — 我的頭像 — 我的道具 — 復活卡。
## Q2：是否支持 A 股交易？
A: 模擬交易支持 A 股交易。但真實交易僅可通過 A 股通交易部分 A 股，具體詳見 [A 股通名單](https://www.hkex.com.hk/Mutual-Market/Stock-Connect/Eligible-Stocks/View-All-Eligible-Securities?sc_lang=zh-HK)。
## Q3：各市場支持的交易方向
A: 除了期貨，其他股票都只支持傳入 BUY 和 SELL 兩個交易方向。在空倉情況下傳入 SELL，產生的訂單交易方向是賣空。
## Q4：真實交易中，各市場支持的訂單類型
A: