简介：中信证券自动化交易平台(CATS) API参考文档，面向量化交易及程序化交易客户端开发者，系统介绍CATS API的全双工异步通信机制与应用级函数设计，帮助用户规避底层压缩加密细节，专注业务功能实现。压缩包内含单份PDF文档，大小约509KB，已有3300人学习下载。文档涵盖API初始化与退出清理、通信会话管理、连接交易及行情服务器、工具函数、本地内存数据库操作、账户管理、交易订阅与行情订阅等完整函数分类，并给出初始化、业务请求、订阅推送三类典型调用流程。借助这些接口，开发者可快速实现账户登录、资金持仓订阅、委托成交推送、行情订阅等功能，搭建个性化自动化交易策略系统，显著降低CATS平台接入复杂度。
1. CATS到底是个什么系统：它不是行情软件，是给程序化交易用的下单通道
做量化或者手动交易做到一定规模，你会发现用券商普通客户端下单根本不够用：速度慢、没法批量撤单、风控前置基本靠人工盯盘。这时候券商通常会提供一套机构级的自动化交易平台，中信证券这套系统的简称就是CATS（自动化交易系统），对外提供给私募、量化团队、企业客户做程序化接入。它的API参考文档解决的核心问题只有一个：让你把订单从自己的策略服务器安全、合规、高效地送进交易所，并把成交回报拿回来。本文不打算做词条式科普，而是按“这个API在交易链路里处于什么位置→怎么接入→核心接口怎么用→实盘有哪些坑”这条线讲透，让想接CATS API的人能像个有经验的人那样动手。
2. CATS的链路定位与API设计思路：先搞懂它和柜台、交易所的关系
2.1 券商交易系统通常有三层，CATS不是最底层
做程序化交易接入，很多人第一次看API参考文档会被里面的名词绕晕：报单、回报、分发、会话、前置机。这里先建立一个简单的三层模型。最底层是核心柜台系统，也就是券商用来做资金清算、持仓管理、交易编码管理的系统，类似恒生UF2.0或金证这类柜台。中间层是极速交易网关，它负责把订单以低延迟送到交易所，同时把交易所的回报推给上层。顶层才是CATS这类自动化交易平台，它把复杂的柜台交互封装成一套相对规整的API，替客户处理了会话管理、订单生命周期、风控前置、回报路由这些事情。
CATS API参考里大量接口参数，本质上都是在描述这三层之间的信息流转。理解这个关系的价值在于：当你查一个字段查不到含义时，思路会转向“这个字段到底是给柜台用的，还是给网关用的，还是给本系统路由用的”，而不是盲目去问运维。从我接触这类券商API的经验看，90%的字段定义矛盾，都出在对链路层级的误判上。
2.2 API按意图划分：交易类、查询类、管理类、回报类
打开CATS的API参考，接口数量不少，但按意图划分其实很清晰。交易类接口负责委托申报、撤单、改单，改单在有些系统里也做成“先撤后报”两个原语。查询类接口负责查资金、查持仓、查当日委托、查当日成交，这类接口通常是给策略启动时做状态同步用的。管理类接口做会话登录、心跳、密码修改、风控参数设置。回报类接口比较特殊，它不是主动请求，而是系统主动推送给客户端的消息，包括委托回报、成交回报、资金变动回报，一般通过长连接或者消息订阅的方式接收。
接入方需要特别注意的是，参考文档对每个接口标的“同步返回”和“异步回报”是两码事。比如你调了提交委托，API同步返回一个受理编号，只代表系统收到了，不代表交易所已经接受，真正确认订单状态要靠后续的异步回报。这是一个新手最容易理解错的地方：把受理当成交，把拒绝当撤单。把API参考当作一个“请求-响应”文档来读就会踩坑，它实际是一个“请求-同步响应+异步推送”的混合体。
2.3 为什么参考文档会强调“会话”概念
CATS的API参考里，“会话”（Session）是第一等公民。登录成功返回会话凭证，后续所有交易请求都绑定在会话上，超时后系统会主动断开，需要重连并重建会话。会话机制解决的现实问题是：券商系统必须知道“谁在发指令、这个指令来源是否合法、当前连接是否还活着”。尤其是量化策略开着多个进程时，每个进程如果各建各的会话，风控维度就会变成进程级而非策略级，听起来没什么，实际上会导致重复报单、权限混乱。
我一般建议接入方在系统设计阶段就明确会话分配策略：一个策略进程一个会话，还是多个进程共用一个会话。参考文档里通常有“最大连接数”“单会话并发请求数”这类字段，如果你们团队策略很多，需要提前规划。否则等到仿真环境里高频发单发现排队了，再回来看会话设计，已经晚了。
3. 接入前的准备：权限申请、运行环境与初始化的三个要点
3.1 机构客户的接入流程：从开通到拿到第一份测试参数
CATS这类系统只对机构客户开放，个人散户基本接触不到。作为团队的系统工程师，你要推动的事情包括：以公司名义向业务部门提交程序化交易接入申请，签订相关协议，完成合规与适当性流程，开通相应的交易编码与席位权限。流程走完后，券商会给你一份接入参数表，里面通常包含：服务器地址、端口号、通讯方式、用户名、初始密码、证书文件或动态口令方案。
拿到参数表后，不要急着连生产环境。正常流程是先连接测试环境，也就是仿真柜台，用测试资金跑通完整的委托-成交-回报链路。很多团队跳过仿真直接上生产，结果第一笔单子就在风控拒绝码上卡了一下午。仿真环境的价值不只是验证接口参数，还会暴露你策略代码里对回报时序的假设是否成立。另外，测试环境和生产环境的交易规则可能不同，比如仿真环境的涨跌停判断、最小变动价位可能偏宽松，真到生产环境会有一批订单被拒，这需要提前有心理预案。
3.2 运行环境选型：托管机房、虚拟机、普通办公网的区别
决定自动化交易系统能不能发挥性能的，往往不是API代码写得好不好，而是网络环境。同样一套CATS API，放在券商托管机房里跑，和放在公司办公室通过专线跑，订单延迟能差出几个数量级。参考文档会标注建议的网络连接方式，但不一定会告诉你具体延迟数字，因为这取决于基础设施。
常见的部署方式有三种：券商托管机房托管服务器，和柜台在同一机房甚至同一机柜，延迟最低；公司机房通过专线接入券商节点，延迟中等；普通办公网直连，适合策略调试，不适合追求成交速度的实盘。从我的经验看，做高频或者抢单型策略没有条件进托管的，至少也应该用专线，普通家用宽带的抖动会让你在行情剧烈时完全无法依赖回报。有一个容易被忽略的问题：很多API服务器地址在办公网环境下根本不通，需要先做连通性测试，不要等到上线那天才发现防火墙把端口拦了。
3.3 初始化流程：登录、确认业务日期、同步持仓与资金
跑通一个能用的接入程序，初始化部分至少包含四个步骤：加载本地配置、建立加密通道、登录获取会话凭证、做一次资金和持仓查询确认数据可用。这里有一个容易被轻视的点：当日初始化时CATS返回的持仓数据，和柜台上的持仓数据可能存在结算路径差异，尤其是经过昨晚清算后，可用持仓和冻结持仓的计算逻辑和盘中实时口径不一样。API参考里通常把持仓字段拆成“持仓数量、可用数量、冻结数量”，初始化时一定要把三个字段都拉下来比对，缺失任何一个字段都可能导致后面下单时报“可用数量不足”。
下面给一个简化的Python初始化框架，方便理解整个流程的先后依赖关系：
import time import hmac import hashlib import requests BASE_URL = "https://api.example.cats:8443" # 以实际接入参数为准 def login(user, password, cert_path): # 第一步：建立连接前先加载证书，很多环境要求双向TLS # 证书文件由券商分发，通常是pfx或pem格式 # 参数说明：user为交易用户名，password为初始口令 # cert_path指向证书文件路径，verify参数控制服务端证书校验 resp = requests.post( f"{BASE_URL}/session/login", json={"user": user, "password": password}, cert=(cert_path, cert_path), # 双向TLS场景下客户端也要出示证书 verify=True, timeout=5 ) if resp.status_code != 200: raise RuntimeError(f"login failed: {resp.status_code} {resp.text}") data = resp.json() # 返回体通常包含session_token和过期时间 # 拿到token后，后续所有请求头都要带Authorization字段 return data["session_token"] def query_position(session_token, account): # 初始化阶段拉全量持仓，注意这里是"全量"而不是"当日变动" # 参数说明：account是资金账号，字符串类型 # session_token放在请求头里，服务端用它判断会话是否有效 headers = {"Authorization": f"Bearer {session_token}"} resp = requests.get( f"{BASE_URL}/position/query", params={"account": account}, headers=headers, timeout=5 ) if resp.status_code == 401: # 会话过期是初始化阶段最常见的错误，处理办法是重新登录 raise PermissionError("session expired, need relogin") items = resp.json()["data"] for it in items: # 本地数据结构建议用字典，key用(证券代码, 市场)二元组 # 避免只看"持仓数量"，可用数量才是下单能用的最大量 print(it["symbol"], it["hold_qty"], it["avail_qty"], it["frozen_qty"]) return items这段代码想强调的是会话、证书、数据一致性三个初始化要素。登录用证书做双向认证，这在机构接口里很常见；拿到token后所有请求都要带上；初始化查询必须拉全量持仓而不是增量，因为程序刚启动时没有本地缓存可以做增量基准。很多团队在这段代码里偷懒，把持仓查询和当日成交查询放在同一个函数里，后来查问题时把两个数据源混在一起，浪费很多时间。建议从第一天起就把仓位快照查询和成交流水查询分开封装。
4. 核心交易接口实战：用最小代码跑通一次委托全流程
4.1 下单接口：字段虽多，真正必填的就那六个
CATS API参考里，交易委托接口往往列出一大串字段：证券代码、市场、买卖方向、委托类型、价格、数量、客户订单编号、交易单元、业务类型、风控类别、备注等等。一眼看去很唬人，实际真正每次下单必填的只有六个：证券代码、市场、方向、价格、数量、客户订单编号。其余字段要么有默认值，要么在账户初始化时已经绑定，要么是特定场景才用的。
客户订单编号（ClientOrderId）是全流程里最重要的字段。它由客户端自己生成，在整个交易日内必须唯一，服务端会拿它做幂等控制。什么意思呢？假设你提交了一笔委托，网络超时了，客户端不确定服务端到底收没收到，如果你重新生成一个新编号再报一次，就可能导致重复下单；但如果你沿用同一个编号重试，服务端就能识别出这是同一笔单子，返回已有的受理结果而不是再报一次。这就是幂等键的用法。实盘两年以上的团队，多多少少都经历过重复报单的事故，原因基本都是ClientOrderId唯一性没做好。
下面是一个发单函数，注意看幂等键的生成和返回结构的处理：
import uuid import requests def send_order(session_token, account, symbol, exchange, side, price, volume): # 客户订单编号用UUID，保证同一天内不重复 # 实际生产环境建议用"策略ID+日期+自增序号"拼接，方便追溯 client_order_id = f"STRAT_{int(time.time())}_{uuid.uuid4().hex[:8]}" payload = { "account": account, # 资金账号 "symbol": symbol, # 证券代码，如 "600519.SH" "exchange": exchange, # 交易所，SH/SZ "side": side, # "buy" 或 "sell" "ord_type": "limit", # 限价单 "price": str(price), # 价格字段用字符串传，避免浮点精度问题 "volume": volume, # 委托数量，股数 "client_order_id": client_order_id # 幂等键，必须全局唯一 } headers = {"Authorization": f"Bearer {session_token}"} # 注意：下单接口的响应只代表"受理"，不代表"成交" # 响应里的order_id是系统侧委托编号，后续查询都靠它 resp = requests.post( f"{BASE_URL}/order/submit", json=payload, headers=headers, timeout=3 # 超时设短，为的是让上层快速感知失败并决定后续策略 ) data = resp.json() if data.get("code") != 0: # 拒绝原因通常有结构化编码，参考文档会列一个错误码表 raise RuntimeError(f"order rejected: {data['code']} {data['msg']}") system_order_id = data["order_id"] return client_order_id, system_order_id这里有两个参数值得单独说。第一个是价格字段，必须用字符串而不是浮点数传，原因是浮点数在二进制转换时可能产生0.000000001级别的误差，在A股价格精度要求到分的情况下很容易触发边界的校验失败。第二个是超时参数，3秒看起来短，但高频场景下这个值要更小，宁可让请求超时后走撤单流程，也不要让委托在不确定状态里挂太久。如果你的策略是那种挂单后不主动撤的类型，超时时间可以放宽到10秒，逻辑完全不同。
4.2 撤单接口：它的复杂度比下单高，因为要处理“已在交易所队列”的状态
撤单接口看起来简单，无非是提交一笔撤单请求，带上要撤的订单号。但CATS这类系统真实链路里，撤单请求要经历：客户端→CATS前置风控→柜台→交易所，交易所确认后返回撤单成功回报，这个过程的延迟完全取决于订单当时的处理状态。如果订单已经全部成交了，撤单会被拒绝，拒绝原因通常写着“已成废单”之类的状态。
设计策略时，我建议把撤单当成一个“尽力而为”的操作：提交撤单请求后，不要立刻认为订单已经撤销，要等撤单回报。更稳妥的做法是，提交撤单后启动一个超时监控，如果撤单回报迟迟不来，再去查询该订单的最新状态，用“查询”来确认“到底撤没撤掉”。有的团队图省事，撤完单直接再下一笔反向单对冲，如果没撤成功就会变成双向持仓。撤单的另一种常见用法是“撤旧报新”：把旧单撤掉，同时下一笔新价格单，两笔操作之间没有原子性保证，需要考虑中间态的并发控制。
def cancel_order(session_token, account, system_order_id): # 唯一要传的核心参数是系统委托编号 # 这解释了为什么下单时要保存好返回的order_id resp = requests.post( f"{BASE_URL}/order/cancel", json={ "account": account, "order_id": system_order_id }, headers={"Authorization": f"Bearer {session_token}"}, timeout=3 ) data = resp.json() if data.get("code") != 0: # 撤单失败的常见原因：订单已全部成交、订单不存在、状态已终态 # 不要在这里抛异常终止程序，而是记录状态并走查询确认 return False, data.get("msg") # 注意！返回成功只代表撤单指令被接收，不代表撤销完成 # 真正的撤销确认要等status=6的回报（已撤） return True, "cancel accepted, wait for response"代码注释里有一个非常容易踩的坑：撤单接口返回“成功”的时候，系统只是接收了撤单指令。如果你立刻用这笔钱或持仓去下新单，有可能因为尚未真正撤掉而被风控拒单。专业做法是维护一个“订单状态机”，把每笔订单的状态变化记下来，只有状态切到“已撤销”或“已成废单”之后，才释放对应的资金和持仓额度。
4.3 查询接口：拉当日委托和成交时，注意分页与游标
查询接口在CATS API参考里通常不是一个而是一组：查委托、查成交、查持仓、查资金。写查询代码本身没什么难度，难在数据和本地缓存的同步策略。最典型的问题是：行情剧烈时成交回报可能积压，查询接口返回的成交记录和实际推送的成交回报有短暂时间差，这会导致本地统计和服务器统计不一致。
最直接的办法是：忽略本地统计，一切以服务器查询结果为准；如果策略需要实时性，则以回报推送为准，查询只用于补偿和对账。查询接口还要注意分页参数。有的系统默认一页返回几百条，如果当天委托多，必须用游标或者页码循环拉取，直到返回的列表为空。这里有一个隐藏的坑：某次循环拉数据时，如果你用页码而非游标，而新数据又源源不断进来，就会出现“下一页数据被新数据挤掉”的漏数据问题。所以尽量选择支持游标的查询接口形态，没有游标就只能做时间窗口快照。下面是一个用游标拉全量当日委托的代码模板：
def query_all_orders(session_token, account): all_orders = [] cursor = None while True: params = {"account": account, "size": 200} if cursor: params["cursor"] = cursor resp = requests.get( f"{BASE_URL}/orders/today", params=params, headers={"Authorization": f"Bearer {session_token}"}, timeout=5 ) data = resp.json() items = data["data"]["items"] if not items: break all_orders.extend(items) cursor = data["data"].get("next_cursor") if not cursor: break return all_orders这段代码的核心是把“下一页标记”保存下来，不管你中间有多少新数据进来，只要游标是服务端生成的，它总能保证当前页之后的数据是从服务端视角的“上一页末尾”开始的。注意循环终止条件有两个：一是当前页为空，二是服务端不再返回next_cursor，两者满足其一就应该结束。如果你不加游标，在小数据量场景没问题，一旦某天策略发单量暴涨，漏单查不出来的问题会非常痛苦。
4.4 回报推送：长连接的心跳、重连和消息去重
回报推送是CATS API里和普通HTTP请求差异最大的部分。它很少以HTTP轮询形式出现，通常是WebSocket、TCP长连接或者消息队列。参考文档里给出的连接地址、心跳间隔、重连策略，接入方必须严格当成一等公民对待。
回报处理的核心挑战有三个：乱序、重复、丢失。重复是推送系统的常见问题：服务端可能因为网络抖动重发回报，客户端必须自己维护一个最近收到的回报编号集合，重复的直接丢弃。乱序则需要谨慎处理：个别回报先来后到，比如一笔委托的“已成”回报先于“部成”回报到达本地，这种场景下如果策略收到“已成”就平掉所有状态，之后再收到“部成”就会出现状态回退，处理不好还会影响后续下单决策。丢失最危险：长连接断线一段时间，期间产生的成交回报就丢了，这需要用查询接口在重连后做补偿同步。
def on_order_report(report, recent_ids, order_book): # report: 回报消息字典 # recent_ids: 用于去重的编号集合，建议用固定容量的有序集合 # order_book: 本地订单状态字典, key是system_order_id report_id = report["report_id"] if report_id in recent_ids: # 重复回报直接丢弃，这是最基本的一层防护 return recent_ids.add(report_id) oid = report["order_id"] status = report["status"] # 例如 0:已报 1:部成 2:已成 6:已撤 old = order_book.get(oid) if old is not None: # 如果新回报状态级别低于旧状态，说明发生了乱序 # 此时以"更靠近终态"的状态为准，同时记录日志 if status_rank(status) < status_rank(old["status"]): print(f"warning: out-of-order report: {oid}") return order_book[oid] = report if status == "2": print(f"order {oid} fully filled at {report['price']}")这个回调函数虽然短，但把回报处理的三个核心全占了：去重、乱序防护、状态更新。实际生产环境里，建议不要在这个回调里做任何阻塞操作，比如写数据库、发网络请求之类的，应该先把消息放进队列，另起线程异步处理。否则行情一激烈，回调阻塞会导致TCP缓冲区溢出，连接被服务端断开，反而制造出更多的丢包重连问题。
5. 实盘接入的避坑记录：五条高频翻车经验，遇到能省一天
5.1 查询到的可用资金和持仓，和你以为的不一样
现象：程序查询可用资金是100万元，但下100万的单被拒，错误码提示资金不足。查来查去，柜台那边确实没这笔资金。
原因：可用资金在盘中是动态变化的，你查询的那一刻有100万，但之前的某个委托虽然没有成交，已经冻结了部分资金。冻结资金不在“可用”里体现，但在“可用+冻结”的合计里。同样的逻辑也适用于持仓：持仓数量里有部分被质押、被冻结、被待交收锁定，下单能用的只有“可用数量”。
解决：所有下单前置校验都不要只查可用资金，要同时拉资金快照和持仓快照，并且把“已申报未成交”的订单对应资金和持仓在本地做预估扣减。也就是说，你的本地风控要在系统风控之前先算一遍。宁可比系统风控算得更紧，也不能更松。
5.2 订单被拒，但错误码表里查不到这个码
现象：报单返回一个四位数的错误码，翻遍API参考文档的错误码表没找到对应解释。
原因：CATS API参考文档有些错误码是从底层柜台直接透传上来的，柜台词表不在CATS文档范围内。常见如“非交易时间”“废单”“价格超出范围”这类，在柜台的术语体系里叫法不同，直接透传时你会觉得陌生。
解决：对接初期先做一个“错误码收集期”，把所有实盘或仿真环境遇到的错误码记录下来，联系运营或技术支持确认含义，然后固化到本地代码的映射表里。不要觉得问一次就完事了，不同业务类型、不同证券品种可能透传不同码。这个本地映射表是团队的血泪资产，一定要沉淀成文档。
5.3 涨跌停附近的下单，会被拒得很“意外”
现象：价格设置刚好在涨停价，用限价单买入，直接收到“废单”或者“价格超出有效范围”。
原因：某些市场的有效委托价格范围不是直接取涨停价，而是取“最新价的一定百分比”或者“昨收价的一定范围”。涨停价只是个理论边界，有效报价范围可能比涨停价窄，比如科创板、创业板在临停期间有特殊的报价规则。CATS参考文档里即使写了规则，实际触发时的拒绝信息也未必直观。
解决：下单前不要拍脑袋计算价格，用系统提供的“证券状态与价格限制查询”接口拉最新有效价格区间。如果策略是抢涨停板，需要单独处理“非交易时段”和“临停时段”两类边销条件，不能用一个固定公式。
5.4 客户端进程重启后，本地订单状态全丢了
现象：行情剧烈或服务器重启，你的策略进程崩溃了，重启后本地订单字典是空的，完全不知道哪些单是活着的，哪些已成，哪些该撤。如果直接按“无持仓”状态去操作，可能下出重复单或者漏撤单。
原因：本地状态没有持久化。很多团队只在内存里维护订单状态，觉得重启后查一次全量当日委托就能恢复，但实际上从“进程启动”到“查询完成”这个时间窗口里，之前的委托状态是不可知的。如果此时程序自动发单，就可能造成重复委托。
解决：每次收到关键回报（已报、部成、已成、已撤、拒绝）后，除了更新内存，还要同步写入本地数据库或日志文件。启动流程里，先恢复本地状态，再拉服务器当日委托做补偿对账，对完账之前禁止自动交易。这个设计在参考文档里不会写，但实盘是铁律。
5.5 回报推送中断后，重连顺序错了会连环翻车
现象：长连接断开，按文档顺序重连后发现订单状态和服务器对不上，甚至重复收到一批回报导致数量翻倍处理。
原因：重连后服务端通常会把断线期间的回报重新推一遍，如果客户端没有在重连时清空“去重集合”或重新做对账，新一批回报会被当成新事件处理一遍。另一种情况是重连成功后没先查询状态，直接等在回报上，结果断线期间悄无声息成交的单子根本没触发任何本地动作。
解决：重连后的顺序必须是：建立连接→登录获取凭证→重新初始化对账（查询资金、持仓、当日委托、当日成交）→把本地状态和服务端状态做diff→清理去重集合→重新订阅回报。这个顺序写死在代码里，不要在压力测试时省略任何一步。
6. 用一个可落地的验证方案收尾：从连接建立到全链路追踪的心法
很多团队把“接口调通”误当成“接入完成”，其实接口通了只代表HTTP层没问题，真正的接入验收要看一个完整的业务闭环：登录→查资金→查持仓→下一笔最小手数委托→等回报→查当日成交→撤单→等撤单回报。在一个独立的仿真环境里把这条闭环跑通，并且每一步都留下日志，才算真正准备好了实盘。我的习惯是给每一步打结构化日志，包含：时间戳、请求类型、订单编号、响应码、关键字段。这套日志在日后的故障复盘里价值极高。
另一个值得投入的是订单状态机的可视化。用一行文本表示每笔订单的流转路径，比如“已报→部成→已成”，状态异常时在日志里打警告。这不需要复杂框架，一张内存表加一个状态更新函数就够。但就是这样一个简单的机制，能在早期暴露大部分问题。我见过不少团队跳过这一步，直接在收到回报时执行交易逻辑，一旦回报乱序，仓位控制就乱了。
最后说一个我在对接所有券商API时都会遵守的原则：一切以服务端响应和回报为准，本地任何计算都只做辅助校验。这个原则吃亏少，收益多。接CATS API，或者接任何同类交易API，把这条记住，能帮你少走很多弯路。希望帮到你。
本文还有配套的精品资源，点击获取
