跳转至

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 而不是假零值。订阅成功仅代表登记成功,不代表持续数据一定到达,也不代表断线恢复已经验收。