开始入门

操作指引

SDK

数据文档

常见问题

量化工具

其他

文江博客开发文档掘金量化帮助文档文章详情

文章来源于网络收集而来，版权归原创者所有，如有侵权请及时联系！

文件单

发布于 2024-06-22 12:53:28 字数 54277 浏览 0 评论 0 收藏 0

功能简介

掘金终端提供了一种委托指令的处理方式，让用户的委托指令，能够以文件的形式，提交给掘金终端进行报单处理，并通过文件的形式，获得相关交易数据的结果反馈。

什么是文件单？

文件单是记录用户的委托指令的数据文件，目前掘金终端支持 dbf (opens new window) 和 csv (opens new window) 这2种数据文件格式的文件单。
每个文件单中，包含1~n条记录，每条记录代表一笔委托指令
文件单中的字段来描述每笔委托指令的参数，具体的字段请参考下文的接入规范

文件单处理流程

流程如下图所示：

快速上手

下文的示例中，我们将创建一个仿真的交易账户，进行相应的配置，开启文件单功能。

准备交易账户

在 账户管理 下 仿真账户 界面下，添加仿真账户。我们新建一个账户，名称为 王富贵

交易账户

在 账户管理 下 仿真账户 界面下，为刚创建的仿真账户转入资金，以便进行测试。

配置文件单功能

进入配置界面

在 交易工具 界面下，选择 文件单，进入文件单配置界面，如下图所示：手工交易

文件单输入配置

新增一个文件单配置，名称为 王富贵的文件单
设置文件单的输入目录的路径为： C:\test\scan_order

文件单输入配置

文件单输出配置

如果我们的下单的策略需要获取委托执行后的反馈数据，则需要开启对应交易账户的文件单输出
文件单输出的数据项分成6类，每类数据对应一个数据文件

文件单输出配置

文件单输出目录结构说明

以上图的配置为例，在文件单的输出目录 C:\test\push ，会为每个启动了文件单输出的交易账户，创建一个以交易账户ID为名称的子目录，在该子目录下输出相应的数据项文件。例如：王富贵的账户ID为：1395dc4f-3601-11eb-bda5-001018b67b94，C:\test\push目录下结构如下所示：

C:\test\push
├── 1395dc4f-3601-11eb-bda5-001018b67b94
│   ├── cash.csv
│   ├── execution_report.csv
│   ├── func_response.csv
│   ├── order_status.csv
│   ├── order_status_change.csv
│   └── position.csv
└── readme.txt

数据项与文件名的对应关系，请看下表：

csv格式文件名	dbf格式文件名	数据项
cash.csv	cash.dbf	交易账户资金数据
position.csv	position.dbf	交易账户持仓数据
order_status.csv	order_status.dbf	日内委托数据
execution_report.csv	execution_report.dbf	委托执行回报数据
order_status_change.csv	order_status_change.dbf	委托状态变更流水记录
func_response.csv	func_response.dbf	功能号执行结果数据

启动文件单输入

准备下单前，请检查使用文件单输入配置是 启动状态
勾选自动启动，可以自动启动重启终端时未停止的文件单

启动文件单输出

准备下单前，请检查使用的交易账户的文件单输出是 启动状态
如果您的策略程序不需要用到文件单输出的数据，则可以不开启

检查交易账户的连接状态

准备下单前，请检查使用的交易账户当前处于 已连接 状态

执行策略程序下发文件单

策略程序请参考示例策略，内含示例策略使用说明。下载地址：示例策略 (opens new window)

策略程序接入文件单服务注意事项

启动文件单服务后, 策略程序就可以向文件单的输入目录下写委托文件了. 在此处, 我们特别补充说明一下文件单服务, 扫描文件单目录的工作机制, 并给出在进行策略程序编写时应该注意的事项.

文件单目录委托文件扫描的工作流程和机制

文件单服务启动后, 就会监控目录, 当有对应的委托文件(后缀 .csv 或者 .dbf)新增(或者已经存在的), 开始对委托文件进行扫描, 检测文件内容变化.
策略程序此时可以在文件单目录中创建委托文件, 向委托文件中追加委托指令.
文件单服务扫描到委托文件内容发生变化, 读取新增的委托指令进行处理(执行报单)

注意事项

关于启动顺序

建议: 先启动文件单输入, 再启动文件单输出, 检查交易账户的连接状态, 最后再启动用户的策略程序
建议: 启动文件单输入之前, 请先检查文件单目录是否为空. 如果不为空, 请手动删除, 让目录为空.

文件单的下单使用场景

场景1: 向同一个委托文件中不断追加新的委托指令
场景2: 分批次下达委托指令, 每一批委托指令使用一个委托文件.
场景3: 在其他目录通过手工或者其他程序创建好一个委托文件, 然后把这个委托文件复制到文件单的目录下, 等待文件单服务检测到该委托文件, 读取并执行委托指令.

委托文件的自动清理

我们提供了一种称之为 .fin 标志文件 的机制, 用来通知文件单服务, 对应的委托文件已经不会再追加新的委托指令了. 等处理完文件中的委托指令后, 可以由文件单服务进行清理操作.

.fin 是 finished 的简称, 表示该文件已经使用完毕, 策略程序不会再追加新的委托指令到文件了.

.fin 标志文件 的用法具体如下文描述:

.fin 标志文件机制

下面以 csv 格式的委托文件为例进行说明. dbf 文件与之类似, 只是把文件名中的 csv 换成 dbf.

下达委托交易的 csv 委托文件, 文件名为: 2020-10-15_10:48:09.072.order.csv
所有委托已经追加完毕, 不会再向此文件追加委托指令了. 我们的策略程序需要按照流程做如下几件事情:
1. 关闭委托文件. 此例中, 是策略程序需要关闭 2020-10-15_10:48:09.072.order.csv 文件.
2. 在文件单输入目录下, 创建对应的 .fin 标志文件. 文件名是在委托文件的文件名后, 添加 .fin 后缀, 在此例中, 委托文件对应的 .fin 文件的文件名为: 2020-10-15_10:48:09.072.order.csv.fin
3. 确保策略程序没有打开对应 .fin 标志文件. 在此例中, 策略程序需要保证没有打开 2020-10-15_10:48:09.072.order.csv.fin 文件.
执行了以上3步后, 文件单服务在执行完委托文件中的委托指令后, 会自动清除委托文件和对应的 .fin 标志文件.

为什么要有 .fin 文件机制呢?
没有 .fin 标志文件, 文件单服务无法判断这个委托文件是否已经使用完毕, 不会再追加新的委托指令了. 这样文件单服务在运行期间,就会持续扫描该委托文件. 随着不断的新增委托文件, 需要扫描的文件数量就会增加, 这样就会无谓增加cpu消耗, 增大硬盘的IO操作负荷, 反而会降低文件单的执行效率.
委托文件是否还会追加新的委托指令, 这个只有策略程序才知道, 所以得由策略程序通过 .fin 标志文件的机制, 通知文件单服务, 对应的委托文件已经不会再更新了, 可以交由文件单服务清理了.
为什么要确保文件关闭, 没有打开呢?
在windows系统下, 如果策略程序没有关闭委托文件, 没有关闭 .fin 标志文件, 文件单服务在尝试清理委托文件的时候, 会遇到文件被其他进程占用的问题,从而导致清理操作失败.

策略程序开发中的注意事项和最佳实践

在策略程序中, 向委托文件追加完委托指令的操作后, 因多数情况下, 我们使用的都是带缓冲的文件, 所以请执行诸如类似 flush() 的操作, 确保数据尽快刷新写入到磁盘的文件中, 这样文件单服务才能在第一时间内扫描到新增的委托指令, 提高下单速度.
- python 语言的请参考: https://docs.python.org/zh-cn/3/library/io.html?highlight=flush (opens new window)
- java 语言的请参考: https://tool.oschina.net/uploads/apidocs/jdk-zh/java/io/Flushable.html (opens new window)
其他语言略...
不要每笔委托就产生一个委托文件,这样会产生大量的委托文件,从而引起性能问题. 可以采用向同一个委托文件追加委托指令的方式.
避免不停创建新的委托文件, 而没有对应的 .fin 标志文件. 这样会引起cpu和磁盘负荷不断增加, 从而导致掘金终端性能问题.
建议: 每天交易结束后, 按照上文描述的步骤, 创建对应的 .fin 文件, 通知文件单服务清理委托文件.
建议: 使用文件单服务, 请同时开启 数据归档 功能.

扫单性能

运行环境

掘金仿真柜台
操作系统：Windows 10，64位，SSD 固态硬盘
掘金版本：3.12.0
硬件配置：4核8G

委托场景

场景1：委托10笔，每次一笔，收到已报确认后委托下一笔
场景2：委托100笔，每次一笔，收到已报确认后委托下一笔
场景3：委托1000笔，每次一笔，收到已报确认后委托下一笔

存量委托对文件单性能影响可忽略不计

测试结果

各测试场景下委托耗时，时间单位为毫秒.

CSV扫单性能数据结果

场景	最小值	中位数	平均值
场景1	10.9706	10.9206	11.0704
场景2	10.9701	10.9706	11.7486
场景3	10.9611	11.0560	11.7765

DBF扫单性能数据结果

场景	最小值	中位数	平均值
场景1	8.9960	13.0940	17.9999
场景2	7.9960	14.0015	18.5304
场景3	6.9980	14.0075	21.7687

测试脚本

测试所用脚本，包含在扫单示例策略 (opens new window)源码中。

注意事项

文件单的输入目录和输出目录所在磁盘，最好使用SSD磁盘，能够有效降低磁盘读写操作而引起的延时，进一步提高报单速度。
请勿使用如网络位置的硬盘、WSL（windows虚拟的linux环境）等较为小众环境，在一定情况下会因磁盘读写不稳定造成数据丢失。
因为受 dbf 文件格式规范的限制，字符串字段的内容最大长度不能超过 254 个 ANSI 字符。所以，如果使用功能号 func_args 字段的值，或者返回结果的 data 字段的值得长度超出了限制，请改用 csv 格式的文件单。
推荐开启 数据归档 功能。开启后，会将交易过程中产生的交易数据进行归档保存。方便进行盘后数据分析，并提供了报单速度统计，异常合约检测功能。
扫单功能是通过刷新文件来传递数据由于公网复杂环境以及磁盘IO导致的延迟可能会出现回推数据变更不及时，使用时如出现不同回推文件出现信息不一致的情况，可以等待一段时间后反复查询以确保一致
DBF文件定义字段长度超过实际字符长度会默认用空格来填充剩余长度。取数据凡是字符串类型的数据需要去掉空格。
DBF格式扫回推信息会存在中文，解析是需要指定utf编码格式。在python中使用dbf库可以在创建table时指定codepage：dbf.Table(dbf_file, codepage='utf8')
order_status_change 是流水表，如果交易途中没有开启下行，没有收到的数据会丢失。

开启数据归档

请按下图所示，开启数据归档功能。

接入规范

文件单的输入和输出，现在支持 dbf 和 csv 这2种格式

dbf 文件单

用户策略通过文件的形式向终端提交委托指令，同时也是通过文件的形式，获取相关的交易数据反馈。本规范分别对作为输入的文件单和作为输出的数据文件的格式规范进行描述。

输入文件单规范

文件单是用户委托指令的载体，目前掘金终端支持 dbf 和 csv 2 种文件格式。本文是描述 dbf 格式的接入规范。
用户的指令分成 3 类，分别是：委托交易，撤销委托， 功能号指令。掘金终端，通过文件名称后缀来区分文件格式和指令种类。具体请参考下表所示：

示例	后缀部分	文件格式	指令种类
2020-10-15_10:48:09.072.order.dbf	.order.dbf	dbf	委托交易
2020-10-15_10:48:09.072.cancel_order.dbf	.cancel_order.dbf	dbf	撤销委托
2020-10-15_10:48:09.072.func_request.dbf	.func_request.dbf	dbf	功能号指令

dbf 格式

dbf 文件因文件格式规范要求，对字段名称的长度有限制，不能超过 11 个字节。所以字段名称适当做了简写处理。
注意： 11 个字节，因字符 '\0' 作为字符串的终止符，因此字段名称最多只能是 10 个ANSI字符

指令：委托交易

文件单命名规范

后缀名命名方式: *.order.dbf

字段定义说明

字段参数名	类型	必填	说明
sid	string	是	用户策略定义的交易指令 ID, 唯一性, 不可重复使用
account_id	string	是	掘金交易账号 ID
symbol	string	是	标的代码, 格式: 市场.代码例如:平安银行 SZSE.000001 浦发银行 SHSE.600000
volume	number	是	委托量
order_type	string	是	委托类型, 请参考下面的数据字典定义参见
order_business(order_biz)	string	是	委托业务类型, 请参考下面的数据字典定义 `注：参数名必须带括号里面的字段` 参见
price	number	否	限价委托的委托价格. 市价委托的保护价, 沪市市价必填
comment	string	否	备注说明, 不需要时可给空字符串.最大 254 个ANSI字符

指令：撤销委托

文件单命名规范

后缀名命名方式: *.cancel_order.dbf

字段定义说明

字段参数名	类型	必填	说明
sid	string	是	需要撤销的交易指令 ID, 对应委托指令中的 sid 参数
comment	string	否	备注说明, 不需要时可给空字符串.最大 254 个ANSI字符

指令：功能号请求

文件单命名规范

后缀名命名方式: *.func_request.dbf

字段定义说明

字段参数名	类型	必填	说明
rid	string	是	用户策略定义的功能号请求 ID, 唯一性, 不可重复使用
account_id	string	是	掘金交易账号 ID
func_id	string	是	功能号 ID
func_args	string	否	功能号参数, 单行 json 字符串，形如`{"param1": "value1", "param2"："value2"}`
comment	string	否	备注说明, 不需要时可给空字符串.最大 254 个ANSI字符

指令: 算法交易委托

关于 算法交易, 请参考文档: 算法交易

文件单命名规范

后缀命名方式: *.algo_order.dbf

字段定义说明

字段参数名	类型	必填	说明
sid	string	是	用户策略定义的交易指令 ID, 唯一性, 不可重复使用. 在算法交易里, 为算法交易母单的 sid
account_id	string	是	掘金交易账号 ID
symbol	string	是	标的代码, 格式: 市场.代码例如:平安银行 SZSE.000001 浦发银行 SHSE.600000
algo_name	string	是	算法名称: TWAP, VWAP, ATS-SMART,ZC-POV
algo_param	string	是	算法参数. 不同算法有不同的参数, 具体写法请参考下文的算法及其算法参数说明.
order_type	string	是	委托类型, 请参考下面的数据字典定义参见
order_business(order_biz)	string	是	委托业务类型, 请参考下面的数据字典定义 `注：参数名必须带括号里面的字段` 参见
volume	number	是	委托量, 整数
price	number	否	委托价格. 当委托类型为限价单时, 必填
comment	string	否	备注说明, 不需要时可给空字符串.最大 254 个ANSI字符

算法及其算法参数说明

ATS-SMART 算法

ATS-SMART 算法：根据用户委托交易特征，通过对市场高频数据的实时分析和处理，利用程序化分析动态选择最优算法执行用户委托。具有高完成度，高稳定性，高隐蔽性，低敞口等特点，在不同持仓风格场景下，中长期均体现出稳定超越 TWAP/VWAP 基准的效果

ATS-SMART 的算法参数

start_time : 开始时间, 策略开始执行的时间（剔除非交易时间段）。如果开始时间早于策略下达时间点时，则使用下达时间作为开始时间. 时间格式: HH:MM:SS, 例如: 13:50:00 下午 1 点 50 分
end_time_referred : 结束参考时间, 和结束时间一致. (不能超过 14:55:00) 时间格式同上
end_time : 结束时间, 策略停止执行的时间（剔除非交易时间段）。过了结束时间还未完成的数量，将会自动释放到指令。算法执行的区间段，时间越短，任务执行强度（委托频率和单笔委托量）越高. (不能超过 14:55:00) 时间格式同上
end_time_valid : 结束时间是否有效, 算法在结束时间是否有效,如设为无效，则以收盘时间为结束时间. 1 为有效， 0 为无效
stop_sell_when_dl : 涨停时是否停止卖出, 标的在涨停时是否需要停止卖出. 1 为是，0 为否
cancel_when_pl : 跌停时是否撤单, 标的在跌停时是否需要撤单. 1 为是，0 为否
min_trade_amount : 控制子单单笔委托的最小金额, 该参数只适用于股票。A 股单位为元

ZC-POV 算法

ZC-POV 算法：根据用户委托交易特征，通过追踪目标股票流动性，按照市场参与度完成用户委托交易。算法针对性解决股票交易中大金额委托造成的交易冲击、目的暴露、完成率低等问题，更加贴近客户的真实委托意愿

ZC-POV 的算法参数

参与率：市场参与率，即每日委托总量占市场真实交易额的比例（上交易日参考标准），默认 30%，最高委托量比例限制为 45%
基准价格：算法模型的参考基准价格，这里指限价。卖出时，当市场价格低于此价格就停止交易，再次高于此价格就恢复交易，并且补回前面应停止交易而少交易的量；买入时，当市场价格高于此价格就停止交易，再次低于此价格就恢复交易，并且补回前面应停止交易而少交易的量。当填入价格为 0 时，则不设置基准价。

`algo_param` 字段格式

格式规范 arg_name=arg_value, 之间采用 & 号隔开
参考示例:
- ATS-SMART 算法参数示例: start_time=13:00:00&end_time_referred=14:50:00&end_time=14:00:00&end_time_valid=1&stop_sell_when_dl=1&cancel_when_pl=1&min_trade_amount=0
- ZC-POV 算法参数示例: participation_rate=15

指令: 算法交易控制

文件单命名规范

后缀命名方式: *.handle_algo_order.dbf

字段定义说明

字段参数名	类型	必填	说明
sid	string	是	为算法交易母单的 sid
type	number	是	算法交易控制指令类型: 1 - 重启 2 - 暂停 3 -暂停并撤子单 4 - 撤销母单委托
comment	string	否	备注说明, 不需要时可给空字符串.最大 254 个ANSI字符

注意： ATS-SMART 算法仅支持 4 - 撤销母单委托 参数

数据字典定义

dbf order_type 委托类型

order_type 取值	含义
1	限价
10	限价, 即时成交剩余撤销 (fill and kill)
11	限价, 即时全额成交或撤销 (fill or kill)
2	市价
20	市价, 对方最优价格 (best of counterparty)
21	市价, 己方最优价格 (best of party)
22	市价, 即时成交剩余撤销 (fill and kill)
23	市价, 即时全额成交或撤销 (fill or kill)
24	市价, 最优五档剩余撤销 (best 5 then cancel)
25	市价, 最优五档剩余转限价(best 5 then limit)
4	盘后定价交易 (after hour trading)

`order_type` 参数设置说明

市场	参数名	可选值	含义
深圳市场	order_type	1	限价
		2	市价
		20	市价, 对方最优价格 (best of counterparty)
		21	市价, 己方最优价格 (best of party)
		22	市价, 即时成交剩余撤销 (fill and kill)
		23	市价, 即时全额成交或撤销 (fill or kill)
		24	市价, 最优五档剩余撤销 (best 5 then cancel)
上海市场	order_type	1	限价
		2	市价
		20	市价, 对方最优价格 (best of counterparty)
		21	市价, 己方最优价格 (best of party)
		24	市价, 最优五档剩余撤销 (best 5 then cancel)
		25	市价, 最优五档剩余转限价(best 5 then limit)
大商所	order_type	1	限价
		10	限价, 即时成交剩余撤销 (fill and kill)
		11	限价, 即时全额成交或撤销 (fill or kill)
		2	市价
		22	市价, 即时成交剩余撤销 (fill and kill)
		23	市价, 即时全额成交或撤销 (fill or kill)
郑商所	order_type	1	限价
		2	市价
		22	市价, 即时成交剩余撤销 (fill and kill)
上期所	order_type	1	限价
		10	限价, 即时成交剩余撤销 (fill and kill)
		11	限价, 即时全额成交或撤销 (fill or kill)
中金所	order_type	1	限价
		10	限价, 即时成交剩余撤销 (fill and kill)
		11	限价, 即时全额成交或撤销 (fill or kill)
		24	市价，五档市价（远期合约不支持）
		25	市价, 五档市价 FAK (fill and kill)（远期合约不支持）
广期所	order_type	1	限价
		10	限价, 即时成交剩余撤销 (fill and kill)
		11	限价, 即时全额成交或撤销 (fill or kill)
		2	市价
		22	市价, 即时成交剩余撤销 (fill and kill)
		23	市价, 即时全额成交或撤销 (fill or kill)

dbf order_biz 委托业务类型

业务范围	order_biz 取值	含义
股票	1	股票, 买入
	2	股票, 卖出
期货	10	期货, 买入开仓
	11	期货, 卖出平仓
	12	期货, 卖出平仓, 平今仓 (上海商品期货交易所 only)
	13	期货, 卖出平仓, 平昨仓 (上海商品期货交易所 only)
	14	期货, 卖出开仓
	15	期货, 买入平仓
	16	期货, 买入平仓，平今仓 (上海商品期货交易所 only)
	17	期货, 买入平仓, 平昨仓 (上海商品期货交易所 only)
新股申购	100	新股申购
融资融券	200	融资买入 (buying on margin)
	201	融券卖出 (short selling)
	202	买券还券 (repay share by buying share)
	203	卖券还款 (repay cash by selling share)
	204	直接还券 (directly repay share)
	207	担保品买入 (buying on collateral)
	208	担保品卖出 (selling on collateral)
	209	担保品转入 (collateral in)
	210	担保品转出 (collateral out)
	212	专项融资买入 (buying on margin for vip)
	213	专项融券卖出 (short selling for vip)
逆回购	400	逆回购
可转债	402	可转债转股
	403	可转债回售
	404	可转债回售撤销

补充说明

逆回购 如何获取 symbol 字段对应的标的代码. 下面以逆回购 R-007 为例:
- 在 交易工具 页面里, 在任意一个交易监控面板页面, 通过按键精灵功能,输入需要进行逆回购的代码, 本例中为: r-007 (不区分大小写)
- 点击找到的标的记录后, 即可查看到该逆回购标的在掘金系统里的证券代码.
- 如上图所示, 逆回购 R-007 时, symbol 字段填写应为对应的掘金系统证券代码: SZSE.131801

注意事项

205、206 为券商发起的强制平仓业务，用户不能操作
400 (逆回购) 时, volume (委托量) 字段的取值说明:
- 上海市场, voluem 应设置为 10 的整数倍
- 深圳市场, volume 应设置为 10 的整数倍
100 (新股申购) 时, 新股是volume (委托量) 字段应为 100 的整数倍, price (委托价格) 字段应大于 0, 推荐填写新股发行价

输出数据文件规范

在文件单输出配置里面，配置并开启了指定交易账户的文件单输出后，会在文件单的输出目录下，已指定交易账户的 ID 为名称创建子目录，在此子目录下输出需要的交易反馈数据。文件名称与数据类别对应关系请看下表，文件格式和规范参考下文。

dbf 格式文件名	说明
cash.dbf	交易账户资金数据
position.dbf	交易账户持仓数据
order_status.dbf	日内委托数据
execution_report.dbf	委托执行回报数据
order_status_change.dbf	委托状态变更流水记录
func_response.dbf	功能号执行结果数据

dbf 格式

交易账户资金数据

文件名称：cash.dbf
刷新方式：整文件刷新

字段参数名	类型	说明
account_id	string	掘金交易账号 ID
market_val	number	持仓市值
nav	number	总资产
pnl	number	累计收益（实盘不支持）
fpnl	number	浮动盈亏
frozen	number	持仓占用资金（期货）
available	number	可用资金
balance	number	资金余额
created_at	datetime	资金初始时间
updated_at	datetime	资金变更时间
recv_at	datetime	终端接收时间
ord_frozen	number	冻结资金

交易账户持仓数据

文件名称：position.dbf
刷新方式：整文件刷新

字段参数名	类型	说明
account_id	string	掘金交易账号 ID
symbol	string	标的代码, 格式: 市场.代码例如:平安银行 SZSE.000001 浦发银行 SHSE.600000
side	number	持仓方向多方向持仓为 1，空方向持仓为 2
volume	number	总持仓量; 昨持仓量(volume-vol_today)
vol_today	number	今日持仓量
vwap	number	持仓均价
vwap_dild	number	摊薄持仓均价
market_val	number	持仓市值
price	number	当前行情价格
fpnl	number	持仓浮动盈亏
cost	number	持仓成本
avl_now	number	当前可平仓位(根据标的的 T+N 属性计算)
created_at	datetime	建仓时间
updated_at	datetime	仓位变更时间
recv_at	datetime	终端接收时间

日内委托数据

文件名称：order_status.dbf
刷新方式：整文件刷新

字段名	类型	说明
account_id	string	掘金交易账号 ID
sid	string	如果该委托时由扫单服务产生的, 对应委托指令的 sid 参数. 如果该委托不是由扫单服务产生的,则为空
scan_name	string	表明该委托对应的扫单名称
cl_ord_id	string	委托客户端 ID
order_id	string	委托柜台 ID
symbol	string	标的代码, 格式: 市场.代码例如:平安银行 SZSE.000001 浦发银行 SHSE.600000
order_type	number	委托类型参见
order_business(order_biz)	number	委托业务属性参见
status	number	委托状态已报为 1，部成为 2，全成为 3，已撤为 5，拒绝为 8，待报为 10
rej_reason	number	委托拒绝原因
rej_detail	string	委托拒绝原因描述
price	number	委托价格
volume	number	委托量
filled_vol	number	已成量
created_at	datetime	委托创建时间
updated_at	datetime	委托更新时间
sent_at	datetime	委托(终端)发送时间
recv_at	datetime	委托(终端)确认(状态变为已报)时间
filledvwap	number	已成均价
filled_amt	number	已成金额

委托执行回报数据

文件名称：execution_report.dbf
刷新方式：启动同步账户成交数据，新数据在文件末尾追加

字段名	类型	说明
account_id	string	掘金交易账号 ID
sid	string	如果该委托时由扫单服务产生的, 对应委托指令的 sid 参数. 如果该委托不是由扫单服务产生的,则为空
scan_name	string	表明该委托对应的扫单名称
cl_ord_id	string	委托客户端 ID
order_id	string	委托柜台 ID
exec_id	string	委托回报 ID
symbol	string	证券代码(市场.代码)如:SZSE.000001
order_business(order_biz)	number	委托业务属性参见
rej_reason	number	委托拒绝原因
rej_detail	string	委托拒绝原因描述
exec_type	number	执行回报类型成交为 15，撤单拒绝为 19
price	number	委托成交价格
volume	number	委托成交量
created_at	datetime	回报创建时间
recv_at	datetime	终端接收时间
amount	number	委托成交金额

委托状态变更流水记录

文件名称：order_status_change.dbf
刷新方式：文件末尾追加

字段名	类型	说明
account_id	string	掘金交易账号 ID
sid	string	如果该委托时由扫单服务产生的, 对应委托指令的 sid 参数. 如果该委托不是由扫单服务产生的,则为空
scan_name	string	表明该委托对应的扫单名称
cl_ord_id	string	委托客户端 ID
order_id	string	委托柜台 ID
symbol	string	证券代码(市场.代码)如:SZSE.000001
order_type	number	委托类型参见
order_business(order_biz)	number	委托业务属性参见
status	number	委托状态已报为 1，部成为 2，全成为 3，已撤为 5，拒绝为 8，待报为 10
rej_reason	number	委托拒绝原因
rej_detail	string	委托拒绝原因描述
price	number	委托价格
volume	number	委托量
filled_vol	number	已成量
created_at	datetime	委托创建时间
updated_at	datetime	委托更新时间
sent_at	datetime	委托(终端)发送时间
recv_at	datetime	委托(终端)确认(状态变为已报)时间
filledvwap	number	已成均价
filled_amt	number	已成金额

功能号执行结果数据

文件名称：func_response.dbf
刷新方式：文件末尾追加

字段名	类型	说明
rid	string	功能号请求 ID，与功能号交易指令中的 rid 参数对应
account_id	string	掘金交易账号 ID
data	string	功能号扫单结果，单行 json 字符串
error_code	string	错误编码
error_info	string	错误信息
recv_at	datetime	终端接收时间

csv 文件单

输入文件单规范

文件单是用户委托指令的载体，目前掘金终端支持 dbf 和 csv 2 种文件格式。本文是描述 csv 格式的接入规范。
用户的指令分成 3 类，分别是：委托交易，撤销委托， 功能号指令。掘金终端，通过文件名称后缀来区分文件格式和指令种类。具体请参考下表所示：

示例	后缀部分	文件格式	指令种类
2020-10-15_10:48:09.072.order.csv	.order.csv	csv	委托交易
2020-10-15_10:48:09.072.cancel_order.csv	.cancel_order.csv	csv	撤销委托
2020-10-15_10:48:09.072.func_request.csv	.func_request.csv	csv	功能号指令

csv 格式

因 dbf 因格式规范限制，字段名称不能超过 10 个 ansi 字符。而我们的 SDK 文档里，字段都是使用的全称。为了方便对应，在 csv 文件里，对于那些在 dbf 里被进行了简写的字段，csv 文件中，字段的命名方式为： 全称(简称), 例子如下：
dbf 中，order_biz 是简写后的字段名称，在 csv 中，对应的字段名称为：order_business(order_biz)

指令：委托交易

文件单命名规范

后缀名命名方式: *.order.csv

字段定义说明

字段参数名	类型	必填	说明
sid	string	是	用户策略定义的交易指令 ID, 唯一性, 不可重复使用
account_id	string	是	掘金交易账号 ID
symbol	string	是	标的代码, 格式: 市场.代码例如:平安银行 SZSE.000001 浦发银行 SHSE.600000
volume	number	是	委托量, 整数
order_type	string	是	委托类型, 请参考下面的数据字典定义参见
order_business(order_biz)	string	是	委托业务类型, 请参考下面的数据字典定义 `注：参数名必须带括号里面的字段` 参见
price	number	否	限价委托的委托价格. 市价委托的保护价, 沪市市价必填
comment	string	否	备注说明, 不需要时可给空字符串.

指令：撤销委托

文件单命名规范

后缀名命名方式: *.cancel_order.csv

字段定义说明

字段参数名	类型	必填	说明
sid	string	是	需要撤销的交易指令 ID, 对应委托指令中的 sid 参数
comment	string	否	备注说明, 不需要时可给空字符串.

指令：功能号请求

文件单命名规范

后缀名命名方式: *.func_request.csv

字段定义说明

字段参数名	类型	必填	说明
rid	string	是	用户策略定义的功能号请求 ID, 唯一性, 不可重复使用
account_id	string	是	掘金交易账号 ID
func_id	string	是	功能号 ID
func_args	string	否	功能号参数, 单行 json 字符串，形如`{"param1": "value1", "param2"："value2"}`
comment	string	否	备注说明, 不需要时可给空字符串.

指令: 算法交易委托

关于 算法交易, 请参考文档: 算法交易

文件单命名规范

后缀命名方式: *.algo_order.csv

字段定义说明

字段参数名	类型	必填	说明
sid	string	是	用户策略定义的交易指令 ID, 唯一性, 不可重复使用. 在算法交易里, 为算法交易母单的 sid
account_id	string	是	掘金交易账号 ID
symbol	string	是	标的代码, 格式: 市场.代码例如:平安银行 SZSE.000001 浦发银行 SHSE.600000
algo_name	string	是	算法名称: TWAP, VWAP, ATS-SMART, ZC-POV
algo_param	string	是	算法参数. 不同算法有不同的参数, 具体写法请参考下文的算法及其算法参数说明.
order_type	string	是	委托类型, 请参考下面的数据字典定义参见
order_business(order_biz)	string	是	委托业务类型, 请参考下面的数据字典定义 `注：参数名必须带括号里面的字段` 参见
volume	number	是	委托量, 整数
price	number	否	委托价格. 当委托类型为限价单时, 必填
comment	string	否	备注说明, 不需要时可给空字符串.

算法及其算法参数说明

ATS-SMART 算法

ATS-SMART 算法：根据用户委托交易特征，通过对市场高频数据的实时分析和处理，利用程序化分析动态选择最优算法执行用户委托。具有高完成度，高稳定性，高隐蔽性，低敞口等特点，在不同持仓风格场景下，中长期均体现出稳定超越 TWAP/VWAP 基准的效果

ATS-SMART 的算法参数

start_time : 开始时间, 策略开始执行的时间（剔除非交易时间段）。如果开始时间早于策略下达时间点时，则使用下达时间作为开始时间. 时间格式: HH:MM:SS, 例如: 13:50:00 下午 1 点 50 分
end_time_referred : 结束参考时间, 和结束时间一致. (不能超过 14:55:00) 时间格式同上
end_time : 结束时间, 策略停止执行的时间（剔除非交易时间段）。过了结束时间还未完成的数量，将会自动释放到指令。算法执行的区间段，时间越短，任务执行强度（委托频率和单笔委托量）越高. (不能超过 14:55:00) 时间格式同上
end_time_valid : 结束时间是否有效, 算法在结束时间是否有效,如设为无效，则以收盘时间为结束时间. 1 为有效， 0 为无效
stop_sell_when_dl : 涨停时是否停止卖出, 标的在涨停时是否需要停止卖出. 1 为是，0 为否
cancel_when_pl : 跌停时是否撤单, 标的在跌停时是否需要撤单. 1 为是，0 为否
min_trade_amount : 控制子单单笔委托的最小金额, 该参数只适用于股票。A 股单位为元

ZC-POV 算法

ZC-POV 算法：根据用户委托交易特征，通过追踪目标股票流动性，按照市场参与度完成用户委托交易。算法针对性解决股票交易中大金额委托造成的交易冲击、目的暴露、完成率低等问题，更加贴近客户的真实委托意愿

ZC-POV 的算法参数

参与率：市场参与率，即每日委托总量占市场真实交易额的比例（上交易日参考标准），默认 30%，最高委托量比例限制为 45%
基准价格：算法模型的参考基准价格，这里指限价。卖出时，当市场价格低于此价格就停止交易，再次高于此价格就恢复交易，并且补回前面应停止交易而少交易的量；买入时，当市场价格高于此价格就停止交易，再次低于此价格就恢复交易，并且补回前面应停止交易而少交易的量。当填入价格为 0 时，则不设置基准价。

`algo_param` 字段格式

格式规范 arg_name=arg_value, 之间采用 & 号隔开
参考示例:
- ATS-SMART 算法参数示例: start_time=13:00:00&end_time_referred=14:50:00&end_time=14:00:00&end_time_valid=1&stop_sell_when_dl=1&cancel_when_pl=1&min_trade_amount=0
- ZC-POV 算法参数示例: participation_rate=15

指令: 算法交易控制

文件单命名规范

后缀命名方式: *.handle_algo_order.csv

字段定义说明

字段参数名	类型	必填	说明
sid	string	是	为算法交易母单的 sid
type	number	是	算法交易控制指令类型: 1 - 重启 2 - 暂停 3 -暂停并撤子单 4 - 撤销母单委托
comment	string	否	备注说明, 不需要时可给空字符串.

注意： ATS-SMART 算法仅支持 4 - 撤销母单委托 参数

数据字典定义

csv order_type 委托类型

order_type 取值	含义
1	限价
10	限价, 即时成交剩余撤销 (fill and kill)
11	限价, 即时全额成交或撤销 (fill or kill)
2	市价
20	市价, 对方最优价格 (best of counterparty)
21	市价, 己方最优价格 (best of party)
22	市价, 即时成交剩余撤销 (fill and kill)
23	市价, 即时全额成交或撤销 (fill or kill)
24	市价, 最优五档剩余撤销 (best 5 then cancel)
25	市价, 最优五档剩余转限价(best 5 then limit)
4	盘后定价交易 (after hour trading)

`order_type` 参数设置说明

市场	参数名	可选值	含义
深圳市场	order_type	1	限价
		2	市价
		20	市价, 对方最优价格 (best of counterparty)
		21	市价, 己方最优价格 (best of party)
		22	市价, 即时成交剩余撤销 (fill and kill)
		23	市价, 即时全额成交或撤销 (fill or kill)
		24	市价, 最优五档剩余撤销 (best 5 then cancel)
上海市场	order_type	1	限价
		2	市价
		20	市价, 对方最优价格 (best of counterparty)
		21	市价, 己方最优价格 (best of party)
		24	市价, 最优五档剩余撤销 (best 5 then cancel)
		25	市价, 最优五档剩余转限价(best 5 then limit)
大商所	order_type	1	限价
		10	限价, 即时成交剩余撤销 (fill and kill)
		11	限价, 即时全额成交或撤销 (fill or kill)
		2	市价
		22	市价, 即时成交剩余撤销 (fill and kill)
		23	市价, 即时全额成交或撤销 (fill or kill)
郑商所	order_type	1	限价
		2	市价
		22	市价, 即时成交剩余撤销 (fill and kill)
上期所	order_type	1	限价
		10	限价, 即时成交剩余撤销 (fill and kill)
		11	限价, 即时全额成交或撤销 (fill or kill)
中金所	order_type	1	限价
		10	限价, 即时成交剩余撤销 (fill and kill)
		11	限价, 即时全额成交或撤销 (fill or kill)
		24	市价，五档市价（远期合约不支持）
		25	市价, 五档市价 FAK (fill and kill)（远期合约不支持）
广期所	order_type	1	限价
		10	限价, 即时成交剩余撤销 (fill and kill)
		11	限价, 即时全额成交或撤销 (fill or kill)
		2	市价
		22	市价, 即时成交剩余撤销 (fill and kill)
		23	市价, 即时全额成交或撤销 (fill or kill)

csv order_biz 委托业务类型

业务范围	order_biz 取值	含义
股票	1	股票, 买入
	2	股票, 卖出
期货	10	期货, 买入开仓
	11	期货, 卖出平仓
	12	期货, 卖出平仓, 平今仓 (上海商品期货交易所 only)
	13	期货, 卖出平仓, 平昨仓 (上海商品期货交易所 only)
	14	期货, 卖出开仓
	15	期货, 买入平仓
	16	期货, 买入平仓，平今仓 (上海商品期货交易所 only)
	17	期货, 买入平仓, 平昨仓 (上海商品期货交易所 only)
新股申购	100	新股申购
融资融券	200	融资买入 (buying on margin)
	201	融券卖出 (short selling)
	202	买券还券 (repay share by buying share)
	203	卖券还款 (repay cash by selling share)
	204	直接还券 (directly repay share)
	207	担保品买入 (buying on collateral)
	208	担保品卖出 (selling on collateral)
	209	担保品转入 (collateral in)
	210	担保品转出 (collateral out)
	212	专项融资买入 (buying on margin for vip)
	213	专项融券卖出 (short selling for vip)
逆回购	400	逆回购
可转债	402	可转债转股
	403	可转债回售
	404	可转债回售撤销

补充说明

逆回购 如何获取 symbol 字段对应的标的代码. 下面以逆回购 R-007 为例:
- 在 交易工具 页面里, 在任意一个交易监控面板页面, 通过按键精灵功能,输入需要进行逆回购的代码, 本例中为: r-007 (不区分大小写)
- 点击找到的标的记录后, 即可查看到该逆回购标的在掘金系统里的证券代码.
- 如上图所示, 逆回购 R-007 时, symbol 字段填写应为对应的掘金系统证券代码: SZSE.131801

注意事项

205、206 为券商发起的强制平仓业务，用户不能操作
400 (逆回购) 时, volume (委托量) 字段的取值说明:
- 上海市场, voluem 应设置为 10 的整数倍
- 深圳市场, volume 应设置为 10 的整数倍
- order_type (委托类型) 字段应为 1限价
100 (新股申购) 时, volume (委托量) 字段应为 100 的整数倍, price (委托价格) 字段应填写新股发行价，order_type (委托类型) 字段应为 1限价

输出数据文件规范

csv 格式文件名	说明
cash.csv	交易账户资金数据
position.csv	交易账户持仓数据
order_status.csv	日内委托数据
execution_report.csv	委托执行回报数据
order_status_change.csv	委托状态变更流水记录
func_response.csv	功能号执行结果数据

csv 格式

交易账户资金数据

文件名称：cash.csv
刷新方式：整文件刷新

字段参数名	类型	说明
account_id	string	掘金交易账号 ID
market_value(market_val)	number	持仓市值
nav	number	总资产
pnl	number	累计收益（实盘不支持）
fpnl	number	浮动盈亏
frozen	number	持仓占用资金（期货适用）
available	number	可用资金
balance	number	资金余额
created_at	datetime	资金初始时间
updated_at	datetime	资金变更时间
recv_at	datetime	终端接收时间
order_frozen(ord_frozen)	number	冻结资金

交易账户持仓数据

文件名称：position.csv
刷新方式：整文件刷新

字段参数名	类型	说明
account_id	string	掘金交易账号 ID
symbol	string	标的代码, 格式: 市场.代码例如:平安银行 SZSE.000001 浦发银行 SHSE.600000
side	number	持仓方向多方向持仓为 1，空方向持仓为 2
volume	number	总持仓量;
volume_today(vol_today)	number	今日持仓量
vwap	number	持仓均价
vwap_diluted(vwap_dild)	number	摊薄持仓均价
market_value(market_val)	number	持仓市值
price	number	当前行情价格
fpnl	number	持仓浮动盈亏
cost	number	持仓成本
available_now(avl_now)	number	当前可平仓位(根据标的的 T+N 属性计算)
created_at	datetime	建仓时间
updated_at	datetime	仓位变更时间
recv_at	datetime	终端接收时间

日内委托数据

文件名称：order_status.csv
刷新方式：整文件刷新

字段名	类型	说明
account_id	string	掘金交易账号 ID
sid	string	如果该委托时由扫单服务产生的, 对应委托指令的 sid 参数. 如果该委托不是由扫单服务产生的,则为空
scan_name	string	表明该委托对应的扫单名称
cl_ord_id	string	委托客户端 ID
order_id	string	委托柜台 ID
symbol	string	标的代码, 格式: 市场.代码例如:平安银行 SZSE.000001 浦发银行 SHSE.600000
order_type	number	委托类型参见
order_business(order_biz)	number	委托业务属性参见
status	number	委托状态已报为 1，部成为 2，全成为 3，已撤为 5，拒绝为 8，待报为 10
ord_rej_reason(rej_reason)	number	委托拒绝原因
ord_rej_reason_detail(rej_detail)	string	委托拒绝原因描述
price	number	委托价格
volume	number	委托量
filled_volume(filled_vol)	number	已成量
created_at	datetime	委托创建时间
updated_at	datetime	委托更新时间
sent_at	datetime	委托(终端)发送时间
recv_at	datetime	委托(终端)确认(状态变为已报)时间
filled_vwap(filledvwap)	number	已成交均价
filled_amount(filled_amt)	number	已成交金额

委托执行回报数据

文件名称：execution_report.csv
刷新方式：文件末尾追加

字段名	类型	说明
account_id	string	掘金交易账号 ID
sid	string	如果该委托时由扫单服务产生的, 对应委托指令的 sid 参数. 如果该委托不是由扫单服务产生的,则为空
scan_name	string	表明该委托对应的扫单名称
cl_ord_id	string	委托客户端 ID
order_id	string	委托柜台 ID
exec_id	string	委托回报 ID
symbol	string	证券代码(市场.代码)如:SZSE.000001
order_business(order_biz)	number	委托业务属性参见
ord_rej_reason(rej_reason)	number	委托拒绝原因
ord_rej_reason_detail(rej_detail)	string	委托拒绝原因描述
exec_type	number	执行回报类型成交为 15，撤单拒绝为 19
price	number	委托成交价格
volume	number	委托成交量
created_at	datetime	回报创建时间
recv_at	datetime	终端接收时间
amount	number	委托成交金额

委托状态变更流水记录

文件名称：order_status_change.csv
刷新方式：文件末尾追加

字段名	类型	说明
account_id	string	掘金交易账号 ID
sid	string	如果该委托时由扫单服务产生的, 对应委托指令的 sid 参数. 如果该委托不是由扫单服务产生的,则为空
scan_name	string	表明该委托对应的扫单名称
cl_ord_id	string	委托客户端 ID
order_id	string	委托柜台 ID
symbol	string	证券代码(市场.代码)如:SZSE.000001
order_type	number	委托类型参见
order_business(order_biz)	number	委托业务属性参见
status	number	委托状态已报为 1，部成为 2，全成为 3，已撤为 5，拒绝为 8，待报为 10
ord_rej_reason(rej_reason)	number	委托拒绝原因
ord_rej_reason_detail(rej_detail)	string	委托拒绝原因描述
price	number	委托价格
volume	number	委托量
filled_volume(filled_vol)	number	已成量
created_at	datetime	委托创建时间
updated_at	datetime	委托更新时间
sent_at	datetime	委托(终端)发送时间
recv_at	datetime	委托(终端)确认(状态变为已报)时间
filled_vwap(filledvwap)	number	已成交均价
filled_amount(filled_amt)	number	已成交金额

功能号执行结果数据

文件名称：func_response.csv
刷新方式：文件末尾追加

字段名	类型	说明
rid	string	功能号请求 ID，与功能号交易指令中的 rid 参数对应
account_id	string	掘金交易账号 ID
data	string	功能号扫单结果，单行 json 字符串
error_code	string	错误编码
error_info	string	错误信息
recv_at	datetime	终端接收时间

文件单示例（Python）

策略文件结构

.
├── README.md
├── common.py
├── dbf.py
├── requirements.txt
├── scan_by_csv.py
├── scan_by_dbf.py
├── test_spend_time_by_csv.py
└── test_spend_time_by_dbf.py

README.md 使用说明
common.py 扫单公共脚本
dbf.py pip install dbf下载安装的 dbf 库，修改注释了第3070行
requirements.txt Python 示例策略依赖
scan_by_csv.py CSV 扫单示例策略
scan_by_dbf.py DBF 扫单示例策略
test_spend_time_by_csv.py CSV 扫单性能测试
test_spend_time_by_dbf.py DBF 扫单性能测试

使用教程

当前示例策略，依赖于 Python 3.6 及以上环境

安装依赖

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

修改参数

打开scan_by_csv.py或scan_by_dbf.py文件，修改 if __name__ == '__main__'下的参数：

# 文件单结果输入路径：登录掘金3终端 -> 手工交易 -> 文件单 -> 文件单输入 -> 新增扫单的扫单路径
int_path = r''

# 文件单结果输出路径：登录掘金3终端 -> 手工交易 -> 文件单 -> 文件单输出-> 输出路径
out_path = r''

# 仿真/实盘的账户ID
account_id = ''

运行扫单脚本

python scan_by_csv.py // 或 python scan_by_dbf.py

策略下载

下载示例策略

注意事项

由于dbf文件规范本身字段值长度(254 个字符长度)的限制，功能号文件单不适合使用dbf文件单进行扫单，建议使用csv.
dbf文件扫单，读写dbf文件时，请指定codepage参数为utf8，以避免出现中文乱码
文件单支持流式写入委托信号，可以减少频繁开关文件影响报单性能
示例程序仅供参考，请勿用于实盘交易

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

列表为空，暂无数据

开始入门

操作指引

SDK

数据文档

常见问题

量化工具

其他

其他

文件单

功能简介

什么是文件单？

文件单处理流程

快速上手

准备交易账户

配置文件单功能

进入配置界面

文件单输入配置

文件单输出配置

文件单输出目录结构说明

启动文件单输入

启动文件单输出

检查交易账户的连接状态

执行策略程序下发文件单

策略程序接入文件单服务注意事项

文件单目录委托文件扫描的工作流程和机制

注意事项

关于启动顺序

文件单的下单使用场景

委托文件的自动清理

.fin 标志文件 机制

策略程序开发中的注意事项和最佳实践

扫单性能

运行环境

委托场景

测试结果

CSV扫单性能数据结果

DBF扫单性能数据结果

测试脚本

注意事项

开启数据归档

接入规范

dbf 文件单

输入文件单规范

dbf 格式

指令：委托交易

文件单命名规范

字段定义说明

指令：撤销委托

文件单命名规范

字段定义说明

指令：功能号请求

文件单命名规范

字段定义说明

指令: 算法交易委托

文件单命名规范

字段定义说明

算法及其算法参数说明

ATS-SMART 算法

ATS-SMART 的算法参数

ZC-POV 算法

ZC-POV 的算法参数

algo_param 字段格式

指令: 算法交易控制

文件单命名规范

字段定义说明

数据字典定义

dbf order_type 委托类型

order_type 参数设置说明

dbf order_biz 委托业务类型

补充说明

注意事项

输出数据文件规范

dbf 格式

交易账户资金数据

交易账户持仓数据

日内委托数据

委托执行回报数据

委托状态变更流水记录

功能号执行结果数据

csv 文件单

.fin 标志文件机制

`algo_param` 字段格式

`order_type` 参数设置说明

`algo_param` 字段格式

`order_type` 参数设置说明

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。