OpenTradingCore Python SDK¶
快速开始¶
安装 Python SDK 及可选的实时订阅依赖:
python3 -m pip install "https://api.opentradingcore.com/sdk/opentradingcore-0.1.9-py3-none-any.whl"
python3 -m pip install "websocket-client>=1.7,<2"
在交易核心申请交易员 API Key,妥善保管 Secret。
from opentradingcore import OpenTradingCoreClient
api = OpenTradingCoreClient.public(
base_url="https://trade.opentradingcore.com", location="YOUR_TENANT")
print(api.products())
print(api.snapshot("BTCUSDT"))
print(api.ticker_24h("BTCUSDT"))
# Use the same OpenTradingCoreClient class for signed operations:
api = OpenTradingCoreClient.from_api_key(
base_url="https://trade.opentradingcore.com",
api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET",
location="YOUR_TENANT")
api.login()
print(api.balances())
print(api.funds_history())
实时行情订阅¶
api.connect_stream(channel="market")
try:
api.subscribe_ticker("BTCUSDT")
api.subscribe_order_book("BTCUSDT")
api.subscribe_recent_trades("BTCUSDT")
api.subscribe_candles("BTCUSDT", interval="5m")
for event in api.events(channel="market"):
print(event)
finally:
api.close_stream(channel="market")
登录后的账户订阅¶
# api.login() is required before private subscriptions.
api.connect_stream(channel="private")
try:
api.subscribe_balances()
api.subscribe_positions()
api.subscribe_order_status("BTCUSDT")
api.subscribe_executions("BTCUSDT")
for event in api.events(channel="private"):
print(event)
finally:
api.close_stream(channel="private")
验收范围: 已收到真实公开行情及按用户隔离的私有委托、成交、余额和持仓通知;持续稳定、断线重建与追平尚未完成验收。订阅成功不等于已收到事件。
行情查询¶
OpenTradingCoreClient.products()¶
方法详情
匿名列出当前租户所有已启用产品。
api.products()
OpenTradingCoreClient.snapshot(symbol)¶
方法详情
获取指定产品的盘口快照、最新报价及最近成交。快照不是持续订阅。
api.snapshot("BTCUSDT")
OpenTradingCoreClient.ticker_24h(symbol)¶
方法详情
当前租户指定产品的行情表头:最新价与参考价、涨跌幅、标记价、指数价、24h 高低、资金费率及 UTC 倒计时、Premium、成交量与 USDT 成交额。口径来自现有 1D 聚合,并非承诺严格滚动 24 小时;无数据返回 None。
api.ticker_24h("BTCUSDT")
| 返回字段 | 含义 |
|---|---|
last_price |
最新成交价 |
price_change_percent |
相对参考价的涨跌幅(%) |
mark_price |
标记价格 |
index_price |
指数价格 |
high_price_24h |
交易核心显示的 MD 1D 最高价 |
low_price_24h |
交易核心显示的 MD 1D 最低价 |
funding_rate_percent |
资金费率(%) |
funding_countdown_utc |
距离下一个 UTC 八小时周期的倒计时 |
premium_percent |
(标记价-指数价)/ 指数价(%) |
volume_24h |
MD 1D 基础资产成交量 |
turnover_24h_usdt |
MD 1D 成交额(USDT) |
无有效价格或成交统计时返回 None,不填充假零值。当前采用 1D 数据源,尚不能保证严格滚动 24 小时。
OpenTradingCoreClient.kline(symbol, interval="5m", limit=200)¶
方法详情
读取历史 K 线数据,需先使用 Trader 或 Broker 密钥登录。
api.kline("BTCUSDT", interval="5m", limit=200)
交易与历史¶
OpenTradingCoreClient.place_limit_order(symbol, side, quantity, price)¶
方法详情
提交限价单;超时应先查询原订单状态,不要直接重新下单。
api.place_limit_order("BTCUSDT", "Buy", "0.001", "90000")
OpenTradingCoreClient.cancel_order(symbol, order_id)¶
方法详情
根据订单 ID 撤销已有订单。
api.cancel_order("BTCUSDT", "ORDER_ID")
OpenTradingCoreClient.open_orders(symbol)¶
方法详情
查询当前已登录交易员的未完成委托。
api.open_orders("BTCUSDT")
OpenTradingCoreClient.order_history(page=0, page_size=20, symbol=None)¶
方法详情
分页查询当前交易员的历史订单及状态。
api.order_history(page=0, page_size=20, symbol="BTCUSDT")
OpenTradingCoreClient.execution_history(page=0, page_size=20, symbol=None)¶
方法详情
分页查询当前交易员成交记录。
api.execution_history(page=0, page_size=20, symbol="BTCUSDT")
余额、持仓与资金流水¶
OpenTradingCoreClient.balances()¶
方法详情
查询已登录交易员的资金余额,仅适用于 Trade 资金模式。
api.balances()
OpenTradingCoreClient.positions(symbol)¶
方法详情
查询当前交易员持仓;Order-only 产品不产生 Trade 资金持仓。
api.positions("BTC003USDT")
OpenTradingCoreClient.funds_history(page=0, page_size=50)¶
方法详情
分页读取当前交易员资金流水,服务端强制绑定本人和所属租户。
api.funds_history(page=0, page_size=50)
实时订阅¶
OpenTradingCoreClient.connect_stream(channel="market")¶
方法详情
连接公开行情或已认证私有实时流;仅使用当前 OpenTradingCoreClient。
api.connect_stream(channel="market")
OpenTradingCoreClient.subscribe_ticker(symbol)¶
方法详情
订阅当前租户指定产品的行情表头更新,数据采用已有 MD 1D 指标。请先调用 ticker_24h(symbol) 获取初始快照。
api.subscribe_ticker("BTCUSDT")
OpenTradingCoreClient.subscribe_order_book(symbol)¶
方法详情
订阅盘口初始快照与增量。发现序号缺口必须重新获取快照。
api.subscribe_order_book("BTCUSDT")
OpenTradingCoreClient.subscribe_recent_trades(symbol)¶
方法详情
订阅指定产品的最新公开成交事件。
api.subscribe_recent_trades("BTCUSDT")
OpenTradingCoreClient.subscribe_candles(symbol, interval="5m")¶
方法详情
订阅指定产品及周期的 K 线更新。
api.subscribe_candles("BTCUSDT", interval="5m")
OpenTradingCoreClient.events(channel="market")¶
方法详情
连接并订阅后遍历收到的行情事件;断线需重新连接、订阅和重建快照。
for event in api.events(channel="market"):
print(event)
OpenTradingCoreClient.subscribe_balances()¶
方法详情
订阅当前交易员余额变动,需 ACCOUNT_READ;私有持续推送尚待真实验收。
api.subscribe_balances()
OpenTradingCoreClient.subscribe_positions()¶
方法详情
订阅当前交易员持仓变更,需 ACCOUNT_READ。
api.subscribe_positions()
OpenTradingCoreClient.subscribe_order_status(symbol)¶
方法详情
订阅当前交易员指定产品的订单状态变更,需 ORDER_READ。
api.subscribe_order_status("BTCUSDT")
OpenTradingCoreClient.subscribe_executions(symbol)¶
方法详情
订阅当前交易员指定产品的成交回报,需 ORDER_READ。
api.subscribe_executions("BTCUSDT")
OpenTradingCoreClient.close_stream(channel="market")¶
方法详情
订阅结束应在 finally 中关闭对应的实时连接。
api.close_stream(channel="market")
定时刷新¶
OpenTradingCoreClient.watch_ticker_24h(symbol, interval_seconds=15)¶
方法详情
定时更新当前租户指定产品行情表头。属于查询轮询,而不是推送流。
for ticker in api.watch_ticker_24h("BTCUSDT"):
print(ticker)
OpenTradingCoreClient.watch_funds_history(interval_seconds=15)¶
方法详情
定时更新当前交易员资金流水。这是查询轮询,不是实时推送。
for funds in api.watch_funds_history():
print(funds)
Broker 代客与自定义价格¶
OpenTradingCoreClient.publish_price(data_source_id=..., index_price=..., mark_price=...)¶
方法详情
向所属租户已启用数据源发布指数价与标记价,数据源代码与产品代码互相独立。
api.publish_price(data_source_id="MY_BTC", index_price="90000", mark_price="90001", ttl_ms=60000)
OpenTradingCoreClient.place_customer_limit_order(customer_id, symbol, side, quantity, price)¶
方法详情
在有权限且属于本租户的客户账户下代客提交限价单。
api.place_customer_limit_order("CUSTOMER_ID", "BTCUSDT", "Buy", "0.001", "90000")
数据时效与安全¶
行情表头按租户与产品分别计算,当前使用 MD 1D 聚合,不能保证严格滚动 24 小时。产品行情表头和资金流水可定时只读刷新,不宣称独立推送。Order-only 产品不维护 Trade 余额与持仓;写操作结果不明确时严禁重复提交。
限流规则¶
限流以每个已登录 API Session为单位,同一个会话的 Python SDK 业务调用共用一个令牌桶。当前配置如下:
| API Key 会话 | 限流 Profile | 每秒补充 | 瞬时桶容量 |
|---|---|---|---|
| 交易员 Trader | TRADER_STANDARD |
100 次/秒 | 30 次 |
| Broker 代客交易 | TRADER_STANDARD |
100 次/秒 | 30 次 |
| 租户服务 | TENANT_STANDARD |
20 次/秒 | 10 次 |
目前每次受限业务调用消耗 1 个 token,没有各方法独立权重,也没有独立的 Broker 限流桶。这是服务端当前配置,并非性能或可用性 SLA。公开行情尽量使用订阅,不要高频轮询查询。
超限时 Python SDK 抛出包含 code=10003 的 OpenTradingCoreError(RATE_LIMIT_EXCEEDED)。对只读查询可使用有上限的指数退避及随机抖动。对于下单、撤单、客户入金等写操作,如果响应超时或结果不明,不得盲目重放,应先用订单/成交查询和原始委托 ID 核对。限流 Profile 异常代码为 10005。
错误码¶
Python SDK 本地参数校验失败会抛出 ValueError,远端请求失败抛出 OpenTradingCoreError,可从异常中的 code=... 识别公开错误码;内部异常详情不会向外暴露。常用公共错误码如下:
| 代码 | 名称 | 含义/建议 |
|---|---|---|
1、1004 |
INVALID_REQUEST |
参数无效,请检查输入 |
1005、10004 |
ACCESS_DENIED |
当前身份无权访问 |
1006 |
CHECK_FAILED |
请求校验不通过,检查操作前提条件 |
1007 |
TIMEOUT |
结果不确定;写操作先核对再决定是否重试 |
1050 |
CONNECTION_LIMIT_EXCEEDED |
连接数超限 |
5000 |
TRADE_BALANCE_NOT_ENOUGH |
交易资金不足 |
5001 |
TRADE_ACCOUNTBALANCE_NOTEXIST |
交易资金记录不存在 |
5002 |
TRADE_POSITION_NOT_ENOUGH |
可用持仓不足 |
5003 |
MARK_PRICE_NOT_FOUND |
缺少有效标记价格(包括数据源已过期) |
5004 |
SYMBOL_NOT_FOUND |
本租户不可用产品或尚未同步至 Order |
7000 |
API_NOT_EXIST |
API Key 不存在或尚未完成注册同步 |
7001 |
API_REQ_HAS_EXPIRE |
签名登录请求已过期 |
7002 |
API_SIGN_ERROR |
API 签名错误 |
7003 |
API_IP_NOT_ALLOWED |
IP 不在 Key 授权范围内 |
7004 |
API_KEY_POLICY_NOT_READY |
Gateway 尚未收到该 Key 的授权策略 |
8000 |
ORDER_NOT_FOUND |
查无授权范围内对应委托 |
9000 |
INTERNAL_ERROR |
服务内部异常,写操作不要直接重复提交 |
9001 |
USER_NOT_FOUND |
用户不存在 |
9002 |
USER_SESSION_NOTEXIST |
Session 不存在或过期,请重新认证 |
9004 |
PARAMETER_ERROR |
缺少或传错必要参数 |
9005、9008 |
AUTHENTICATION_FAILED / SIGNATURE_VERIFY_FAIL |
认证或签名未通过 |
9006 |
USER_IS_BAN |
用户已停用 |
9007 |
CLIENT_TYPE_NOT_SUPPORTED |
登录会话类型不支持 |
9009 |
BALANCE_NOT_ENOUGH |
余额不足 |
9016 |
TRADE_PERMISSION_DENIED |
没有交易权限 |
9018 |
API_KEY_LIMIT_REACHED |
API Key 数量达到上限 |
9019 |
NOT_API_USER |
要求合规 API 身份 |
10000 |
NO_POSITION |
没有对应持仓 |
10003 |
RATE_LIMIT_EXCEEDED |
只读请求退避后重试,减少频率 |
10005 |
RATE_LIMIT_PROFILE_INVALID |
请联系平台运营人员 |
不在公开白名单中的后端错误会统一转换为 9000 INTERNAL_ERROR,不会返回服务端堆栈、SQL 或内部实现信息。
公共枚举¶
以下是 Python SDK 参数取值,不是底层传输枚举:
| 参数/概念 | 值 | 说明 |
|---|---|---|
login(mode=...) |
"trader"、"broker" |
与实际申请的 Key 类型一致 |
side |
"Buy"、"Sell"(大小写不敏感) |
限价委托买卖方向 |
oc_type |
"OPEN"、"CLOSE" |
默认 OPEN |
position_side |
"Long"、"Short" |
平仓必填;平多用 Sell,平空用 Buy |
reduce_only |
True、False |
平仓要求 True;本 SDK 的 OPEN 不支持 reduce-only |
set_position_type(..., position_type=...) |
"Cross"、"Isolated" |
Trade 持仓保证金模式 |
| 订单类型/有效期 | Limit / GTC |
当前 Python 辅助方法提供 GTC 限价单,其余类型未暴露 |
| 产品撮合模式 | TRADE、ORDER_ONLY |
租户产品后台配置;ORDER_ONLY 不影响 Trade 资金及持仓 |
market_indicator |
"4"(SDK 默认) |
非必要不要更改,应符合产品实际配置 |
| 权限 Scope | MARKET_READ、ACCOUNT_READ、ORDER_READ、ORDER_WRITE、TENANT_READ、TENANT_WRITE、CUSTOMER_CASH |
由 API Key 身份授予,调用方不可自行提升 |
New、Filled 等委托状态来自服务端返回数据;不表示所有产品都支持其它未列出的订单类型,也不代表列出的状态都是终态。
参数约定¶
| 参数 | 当前 Python SDK 约束 |
|---|---|
location |
必填租户代码;产品必须属于该租户且已启用 |
symbol |
产品代码,如 BTC003USDT;不要求与绑定的数据源代码一致 |
quantity、price |
大于 0 的十进制数;建议字符串精确传值,并遵守产品最小变动单位及限额 |
page / page_size |
页码从 0 开始;历史查询分页大小 1–200 |
kline(..., limit=...) |
1–1000 根,默认 200;默认周期 "5m" |
publish_price(..., ttl_ms=...) |
1000–60000 毫秒,默认 5000;过期后标记价格不可继续使用,不能回退到已经解除关联的旧数据源 |
watch_ticker_24h / watch_funds_history |
定时查询间隔 5–3600 秒(默认 15 秒);它们是只读轮询,不是持续消息推送 |
| API 凭证 | Secret 创建后妥善保管,不写入公开代码或日志;区分 Trader/Broker 身份 |
| 委托客户端 ID | 提供独立且稳定的 clord_id,便于查询状态不明确的订单 |
行情统计严格按租户 + 产品隔离。ticker_24h() 当前使用 MD 的 1D 聚合,还不能保证严格滚动 24 小时,无数据返回 None 而不是假零值。订阅成功仅代表登记成功,不代表持续数据一定到达,也不代表断线恢复已经验收。