交易及银期转账¶
交易账户结构¶
用户(USER)¶
一个用户由一个唯一的 USER_ID 标识. 每个用户的账户信息互相独立.
在任一时刻, 一个用户的交易账户可以由以下信息完整描述
- 1-N个资金账户(ACCOUNT)
- 0-N个持仓记录(POSITION)
- 0-N个委托单(ORDER)
这些信息完整的描述了用户交易账户的[当前状态]. 需要注意的是, 用户过往的交易记录, 转账记录等并不在其中, 那些信息对于用户的交易动作没有任何影响.
资金账户(ACCOUNT)¶
每个资金账户由一个 ACCOUNT_ID 标识. 一个USER可以同时拥有多个ACCOUNT. 每个 ACCOUNT 中的各字段都使用同一币种.
下面是一个ACCOUNT的内容示例:
"CNY": {
//账号及币种
"user_id": "423423", //用户ID
"currency": "CNY", //币种
//本交易日开盘前状态
"pre_balance": 12345, //上一交易日结算时的账户权益
//本交易日内出入金事件的影响
"deposit": 42344, //本交易日内的入金金额
"withdraw": 42344, //本交易日内的出金金额
"static_balance": 124895, //静态权益 = pre_balance + deposit - withdraw
//本交易日内已完成交易的影响
"close_profit": 12345, //本交易日内的平仓盈亏
"commission": 123, //本交易日内交纳的手续费
"premium": 123, //本交易日内交纳的期权权利金
//当前持仓盈亏
"position_profit": 12345, //当前持仓盈亏
"float_profit": 8910.2, //当前浮动盈亏
//当前权益
"balance": 9963216.55, //账户权益 = static_balance + close_profit - commission - premium + position_profit
//保证金占用, 冻结及风险度
"margin": 11232.23, //持仓占用保证金
"frozen_margin": 12345, //挂单冻结保证金
"frozen_commission": 123, //挂单冻结手续费
"frozen_premium": 123, //挂单冻结权利金
"available": 9480176.150000002, //可用资金 = balance - margin - frozen_margin - frozen_commission - frozen_premium
"risk_ratio": 0.048482375, //风险度 = 1 - available / balance
}
持仓(POSITION)¶
每个持仓项描述一个合约的当前持仓情况. 通常以相应的合约代码(SYMBOL)作为KEY
下面是一个 POSITION 的内容示例:
"SHFE.cu1801":{ //position_key=symbol
//交易所和合约代码
"user_id": "423423", //用户ID
"exchange_id": "SHFE", //交易所
"instrument_id": "cu1801", //合约在交易所内的代码
//持仓手数与冻结手数
"volume_long_today": 5, //多头今仓持仓手数
"volume_long_his": 5, //多头老仓持仓手数
"volume_long": 10, //多头持仓手数
"volume_long_frozen_today": 1, //多头今仓冻结手数
"volume_long_frozen_his": 2, //多头老仓冻结手数
"volume_short_today": 5, //空头今仓持仓手数
"volume_short_his": 5, //空头老仓持仓手数
"volume_short": 10, //空头持仓手数
"volume_short_frozen_today": 1, //空头今仓冻结手数
"volume_short_frozen_his": 2, //空头老仓冻结手数
//成本, 现价与盈亏
"open_price_long": 3203.5, //多头开仓均价
"open_price_short": 3100.5, //空头开仓均价
"open_cost_long": 3203.5, //多头开仓成本
"open_cost_short": 3100.5, //空头开仓成本
"position_price_long": 32324.4, //多头持仓均价
"position_price_short": 32324.4, //空头持仓均价
"position_cost_long": 32324.4, //多头持仓成本
"position_cost_short": 32324.4, //空头持仓成本
"last_price": 12345.6, //最新价
"float_profit_long": 32324.4, //多头浮动盈亏
"float_profit_short": 32324.4, //空头浮动盈亏
"float_profit": 12345.6, //浮动盈亏 = float_profit_long + float_profit_short
"position_profit_long": 32324.4, //多头持仓盈亏
"position_profit_short": 32324.4, //空头持仓盈亏
"position_profit": 12345.6, //持仓盈亏 = position_profit_long + position_profit_short
//保证金占用
"margin_long": 32324.4, //多头持仓占用保证金
"margin_short": 32324.4, //空头持仓占用保证金
"margin": 32123.5, //持仓占用保证金 = margin_long + margin_short
}
委托单(ORDER)¶
委托单的单号:
- 每个委托单都必须有一个单号, 单号可以是不超过128个字节长的任意中英文字符和数字组合.
- 单号由发出下单指令的终端负责设定. 它必须保证, 对于同一个USER, 每个单号都是不重复的.
委托单状态:
- 任何一个委托单的状态只会是这两种之一: FINISHED 或 ALIVE
- FINISHED: 已经可以确定, 这个委托单以后不会再产生任何新的成交
- ALIVE: 除上一种情况外的其它任何情况, 委托单状态都标记为 ALIVE, 即这个委托单还有可能产生新的成交
下面是一个 ORDER 的内容示例:
"123": { //order_id, 用于唯一标识一个委托单. 对于一个USER, order_id 是永远不重复的
//委托单初始属性(由下单者在下单前确定, 不再改变)
"user_id": "423423", //用户ID
"order_id": "123", //委托单ID, 对于一个USER, order_id 是永远不重复的
"exchange_id": "SHFE", //交易所
"instrument_id": "cu1801", //在交易所中的合约代码
"direction": "BUY", //下单方向
"offset": "OPEN", //开平标志
"volume_orign": 6, //总报单手数
"price_type": "LIMIT", //指令类型
"limit_price": 45000, //委托价格, 仅当 price_type = LIMIT 时有效
"time_condition": "GTD", //时间条件
"volume_condition": "ANY", //数量条件
//下单后获得的信息(由期货公司返回, 不会改变)
"insert_date_time": 1517544321432, //下单时间, epoch nano
"exchange_order_id": "434214", //交易所单号
//委托单当前状态
"status": "ALIVE", //委托单状态, ALIVE=有效, FINISHED=已完
"volume_left": 3, //未成交手数
"frozen_margin": 343234, //冻结保证金
"last_msg": "", //提示信息
//内部序号
"seqno": 4324,
}
成交记录(TRADE)¶
下面是一个 TRADE 的内容示例:
"123": { //trade_key, 用于唯一标识一条成交记录. 对于一个USER, trade_key 是永远不重复的
"user_id": "423423", //用户ID
"order_id": "434214", //交易所单号
"trade_id": "123", //委托单ID, 对于一个USER, trade_id 是永远不重复的
"exchange_id": "SHFE", //交易所
"instrument_id": "cu1801", //在交易所中的合约代码
"exchange_trade_id": "434214", //交易所单号
"direction": "BUY", //下单方向
"offset": "OPEN", //开平标志
"volume": 6, //成交手数
"price": 45000, //成交价格
"trade_date_time": 15175442131, //成交时间, epoch nano
"commission": "434214", //成交手续费
"seqno": 4324,
}
交易账户信息同步¶
交易账户信息通过 rtn_data 包的 trade 字段进行差分发送, 如下所示:
{
"aid": "rtn_data", //数据推送
"data": [ //diff数据数组, 一次推送中可能含有多个数据包
{
"trade": { //交易相关数据
"user1": { //登录用户名
"user_id": "user1", //登录用户名
"accounts": { //账户资金信息
"CNY": { //account_key, 通常为币种代码
//核心字段
"account_id": "423423", //账号
"currency": "CNY", //币种
"balance": 9963216.550000003, //账户权益
"available": 9480176.150000002, //可用资金
//参考字段
"pre_balance": 12345, //上一交易日结算时的账户权益
"deposit": 42344, //本交易日内的入金金额
"withdraw": 42344, //本交易日内的出金金额
"commission": 123, //本交易日内交纳的手续费
"preminum": 123, //本交易日内交纳的权利金
"static_balance": 124895, //静态权益
"position_profit": 12345, //持仓盈亏
"float_profit": 8910.231, //浮动盈亏
"risk_ratio": 0.048482375, //风险度
"margin": 11232.23, //占用资金
"frozen_margin": 12345, //冻结保证金
"frozen_commission": 123, //冻结手续费
"frozen_premium": 123, //冻结权利金
"close_profit": 12345, //本交易日内平仓盈亏
"position_profit": 12345, //当前持仓盈亏
}
},
"positions": { //持仓
"SHFE.cu1801": { //合约代码
//核心字段
"exchange_id": "SHFE", //交易所
"instrument_id": "cu1801", //合约代码
//参考字段
"hedge_flag": "SPEC", //套保标记
"open_price_long": 3203.5, //多头开仓均价
"open_price_short": 3100.5, //空头开仓均价
"open_cost_long": 3203.5, //多头开仓成本
"open_cost_short": 3100.5, //空头开仓成本
"float_profit_long": 32324.4, //多头浮动盈亏
"float_profit_short": 32324.4, //空头浮动盈亏
"position_cost_long": 32324.4, //多头持仓成本
"position_cost_short": 32324.4, //空头持仓成本
"position_profit_long": 32324.4, //多头浮动盈亏
"position_profit_long": 32324.4, //空头浮动盈亏
"volume_long_today": 5, //多头今仓持仓手数
"volume_long_his": 5, //多头老仓持仓手数
"volume_short_today": 5, //空头今仓持仓手数
"volume_short_his": 5, //空头老仓持仓手数
"margin_long": 32324.4, //多头持仓占用保证金
"margin_short": 32324.4, //空头持仓占用保证金
"order_volume_buy_open": 1, //买开仓挂单手数
"order_volume_buy_close": 1, //买平仓挂单手数
"order_volume_sell_open": 1, //卖开仓挂单手数
"order_volume_sell_close": 1, //卖平仓挂单手数
}
},
"orders": { //委托单
"123": { //order_id, 用于唯一标识一个委托单. 对于一个USER, order_id 是永远不重复的
//核心字段
"order_id": "123", //委托单ID, 对于一个USER, order_id 是永远不重复的
"order_type": "TRADE", //指令类型
"exchange_id": "SHFE", //交易所
"instrument_id": "cu1801", //在交易所中的合约代码
"direction": "BUY", //下单方向, BUY=
"offset": "OPEN", //开平标志
"volume_orign": 6, //总报单手数
"volume_left": 3, //未成交手数
"trade_type": "TAKEPROFIT", //指令类型
"price_type": "LIMIT", //指令类型
"limit_price": 45000, //委托价格, 仅当 price_type = LIMIT 时有效
"time_condition": "GTD", //时间条件
"volume_condition": "ANY", //数量条件
"min_volume": 0,
"hedge_flag": "SPECULATION", //保值标志
"status": "ALIVE", //委托单状态, ALIVE=有效, FINISHED=已完
//参考字段
"last_msg": "", //最后操作信息
"insert_date_time": 1928374000000000, //下单时间
"exchange_order_id": "434214", //交易所单号
}
},
"trades": { //成交记录
"123|1": { //trade_key, 用于唯一标识一个成交项
"order_id": "123",
"exchange_id": "SHFE", //交易所
"instrument_id": "cu1801", //交易所内的合约代码
"exchange_trade_id": "1243", //交易所成交号
"direction": "BUY", //成交方向
"offset": "OPEN", //开平标志
"volume": 6, //成交手数
"price": 1234.5, //成交价格
"trade_date_time": 1928374000000000 //成交时间
}
},
},
},
]
}
}
终端登录鉴权¶
我们使用 aid = “req_login” 的包作为登录请求包. 此包的结构由具体的实现定义. 以 Open Trade Gateway 项目为例, req_login 包结构如下:
{
"aid": "req_login",
"bid": "aaa",
"user_name": "43214",
"password": "abcd123",
}
登录成功或失败的信息, 通过 notify 发送
交易指令¶
下单¶
终端通过发送 insert_order 包实现下单
{
"aid": "insert_order", //必填, 下单请求
"user_id": "user1", //必填, 需要与登录用户名一致, 或为登录用户的子账户(例如登录用户为user1, 则报单 user_id 应当为 user1 或 user1.some_unit)
"order_id": "SomeStrategy.Instance1.001", //必填, 委托单号, 需确保在一个账号中不重复, 限长512字节
"exchange_id": "SHFE", //必填, 下单到哪个交易所
"instrument_id": "cu1803", //必填, 下单合约代码
"direction": "BUY", //必填, 下单买卖方向
"offset": "OPEN", //必填, 下单开平方向, 仅当指令相关对象不支持开平机制(例如股票)时可不填写此字段
"volume": 1, //必填, 下单手数
"price_type": "LIMIT", //必填, 报单价格类型
"limit_price": 30502, //当 price_type == LIMIT 时需要填写此字段, 报单价格
"volume_condition": "ANY",
"time_condition": "GFD",
}
撤单¶
终端通过发送 cancel_order 包实现撤单
{
"aid": "cancel_order", //必填, 撤单请求
"user_id": "abcd" //必填, 下单时的 user_id
"order_id": "0001", //必填, 委托单的 order_id
}
银期转账¶
签约银行和转账记录¶
签约银行和转账记录信息由 rtn_data 包中 trade 部分的 banks 和 transfers 发送, 如下所示
{
"aid": "rtn_data", //数据推送
"data": [ //diff数据数组, 一次推送中可能含有多个数据包
{
"trade": { //交易相关数据
"user1": { //登录用户名
"banks": { //用户相关银行
"4324": {
"id": "4324",
"name": "工行",
}
},
"transfers": { //账户转账记录
"0001": {
"datetime": 433241234123 //转账时间, epoch nano
"currency": "CNY", //币种
"amount": 3243, //涉及金额
"error_id": 0, //转账结果代码
"error_msg": "成功", //转账结果代码
}
},
},
},
]
}
}
请求银期转账¶
{
"aid": "req_transfer", //必填, 转账请求
"future_account": "0001", //必填, 期货账户
"future_password": "0001", //必填, 期货账户密码
"bank_id": "0001", //必填, 银行ID
"bank_password": "0001", //必填, 银行账户密码
"currency": "CNY", //必填, 币种代码
"amount": 135.4 //必填, 转账金额, >0 表示转入期货账户, <0 表示转出期货账户
}
转账操作的结果, 将由转账记录同步的方式提供给终端
字段常量表¶
order_type¶
| Name | Value/Description |
|---|---|
| TRADE | 交易指令 |
| SWAP | 互换交易指令 |
| EXECUTE | 期权行权指令 |
| QUOTE | 期权询价指令 |
trade_type¶
| Name | Value/Description |
|---|---|
| STOPLOSS | 止损 |
| TAKEPROFIT | 止盈 |
price_type¶
| Name | Value/Description |
|---|---|
| ANY | 任意价 |
| LIMIT | 限价 |
| BEST | 最优价 |
| FIVELEVEL | 五档价 |
volume_condition¶
| Name | Value/Description |
|---|---|
| ANY | 任何数量 |
| MIN | 最小数量 |
| ALL | 全部数量 |
time_condition¶
| Name | Value/Description |
|---|---|
| IOC | 立即完成，否则撤销 |
| GFS | 本节有效 |
| GFD | 当日有效 |
| GTD | 指定日期前有效 |
| GTC | 撤销前有效 |
| GFA | 集合竞价有效 |
force_close¶
| Name | Value/Description |
|---|---|
| NOT | 非强平 |
| LACK_DEPOSIT | 资金不足 |
| CLIENT_POSITION_LIMIT | 客户超仓 |
| MEMBER_POSITION_LIMIT | 会员超仓 |
| POSITION_MULTIPLE | 持仓非整数倍 |
| VIOLATION | 违规 |
| OTHER | 其他 |
| PERSONAL_DELIV | 自然人临近交割 |
| HEDGE_POSITION_LIMIT | 客户套保超仓 |
协议实现¶
DIFF Collection 中列出了一些本协议的开源实现