Skip to content

3.7 委托单明细 API ​

Prediction

IMPORTANT

Prediction 目前仍在内部测试阶段(alpha),请求参数与响应字段可能调整。

http
GET /api/v1/prediction/report/orders

返回指定时间区间内有变动的委托单,以委托单(order)为单位,用于将委托单增量同步至商户系统。下单、撮合、撤单、下单失败等委托单本身的变动均视为变动。仅返回调用方代理旗下的数据。数据保留最近 6 个月。请求须带入 HMAC 验证 Header。

TIP

本 API 限流 100 次 / 分钟,超过返回 code:10060。额度按 api_key × 接口独立计算,各接口不共用;每次请求(含返回错误者)均计入。

IMPORTANT

委托单本身没有结算结果。结算、重新结算、回滚、作废等变动发生在持仓上,请以 3.9 持仓明细 同步。

请求参数(Query String) ​

字段必填类型说明
start_timeTRUEstring变动时间区间起(含),RFC3339 UTC,须对齐整秒,例如 2026-10-20T00:00:00Z;不可早于 6 个月前
end_timeTRUEstring变动时间区间迄(含),RFC3339 UTC,须对齐整秒;须晚于 start_time,与 start_time 间隔不可超过 24 小时
cursorFALSEstring分页游标;第一页不带,之后带上一页响应的 next_cursor
langFALSEstringLANGUAGE_ZH_CN / LANGUAGE_EN(默认英文)

TIP

本 API 以游标分页,每页固定最多 100 笔,不提供 page / page_size。cursor 仅对产生它的同一组 start_time / end_time 有效,更换区间须从第一页重新开始。cursor 内容不保证格式,请勿自行解析或组装。

响应 data ​

data 包含 items[](委托单)、has_more、next_cursor。金额字段:usd_ 前缀为美元,无前缀为玩家币种。

json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "order_id": "019e0000-0000-0000-0000-000000000000",
        "idempotency_key": "00000000-0000-0000-0000-000000000000",
        "player_id": "00000000-0000-0000-0000-000000000000",
        "player_external_id": "player1",
        "player_name": "player1_name",
        "agent_id": "00000000-0000-0000-0000-000000000001",
        "agent_name": "agent_demo",
        "sport_id": "sr:sport:1",
        "sport_name": "足球",
        "tournament_id": "sr:tournament:16",
        "tournament_name": "World Cup",
        "event_id": "sr:match:00000000",
        "event_name": "Team A vs Team B",
        "event_start_time": "2026-10-10T12:00:00Z",
        "market_id": "1",
        "market_name": "Match Winner",
        "specifiers": "",
        "outcome_id": "1",
        "outcome_name": "Team A",
        "home_competitor_id": "sr:competitor:0001",
        "home_competitor": "Team A",
        "away_competitor_id": "sr:competitor:0002",
        "away_competitor": "Team B",
        "home_score": "0",
        "away_score": "0",
        "period_home_score": "0",
        "period_away_score": "0",
        "event_status": "not_started",
        "match_status": "0",
        "side": "PREDICTION_SIDE_YES",
        "action": "PREDICTION_ACTION_BUY",
        "limit_price_cents": "55",
        "max_price_ticks": 10000,
        "qty_units": "1000",
        "filled_units": "1000",
        "persistence": "Lapse",
        "runner_id": "1000000000001",
        "currency": "CNY",
        "mid_rate": "7.1",
        "deducted_amount": "39.40145",
        "usd_deducted_amount": "5.5495",
        "truncation_loss": "0",
        "usd_truncation_loss": "0",
        "fee_reserve": "0.35145",
        "usd_fee_reserve": "0.0495",
        "status": "PREDICTION_ORDER_STATUS_FILLED",
        "cancel_cause": "",
        "cause_detail": "",
        "release_at": null,
        "order_time": "2026-10-05T08:00:00Z",
        "updated_at": "2026-10-05T08:00:01Z",
        "changed_at": "2026-10-05T08:00:01.284553771Z",
        "client_ip": "203.0.113.10",
        "device_type": "PC",
        "device_id": "device-001",
        "ex_market_id": "2000000000001",
        "ex_order_id": "3000000000001",
        "engine_flipped": false,
        "url": "https://…"
      }
    ],
    "has_more": true,
    "next_cursor": "eyJ2IjoyLCJzIjoxNzkxOTM2MDAwMDAwMDAwMDAw..."
  }
}
字段类型说明
itemsarray区间内有变动的委托单,内容为查询当下的最新状态
has_moreboolean此区间是否还有下一页
next_cursorstring下一页游标;has_more 为 false 时为空字符串

items[] 字段 ​

字段类型说明
order_idstring委托单号,属唯一值
idempotency_keystring下单幂等键
player_idstring平台内部玩家 UUID
player_external_idstring玩家 ID(商户侧)
player_namestring玩家名称
agent_idstring平台内部代理 UUID
agent_namestring代理名称
sport_id / sport_namestring运动 ID / 名称
tournament_id / tournament_namestring联赛 ID / 名称
event_id / event_namestring赛事 ID / 名称
event_start_timestring赛事开始时间(RFC3339 UTC)
market_id / market_namestring市场 ID / 名称
specifiersstring市场参数;无参数市场为空字符串
outcome_id / outcome_namestring投注选项 ID / 名称
home_competitor_id / away_competitor_idstring主 / 客队 ID
home_competitor / away_competitorstring主 / 客队名称
home_score / away_scorestring下单时主 / 客队比分
period_home_score / period_away_scorestring下单时当前节 / 半场比分
event_statusstring赛事状态(如 not_started、live、ended)
match_statusstring比赛状态码
sidestring方向(PREDICTION_SIDE_*)
actionstring买卖动作(PREDICTION_ACTION_*)
limit_price_centsstring限价(美分 / 股,0.01–99.99)
max_price_ticksinteger价格 tick 基数(价格换算用)
qty_unitsstring委托股数(单位 1/100 股)
filled_unitsstring已成交股数(单位 1/100 股);未成交股数 = qty_units − filled_units
persistencestring挂单持续策略(如 Lapse)
runner_idstring撮合引擎 runner ID
currencystring玩家币种
mid_ratestring下单时汇率
deducted_amountstring实际扣款(玩家币种),已含 fee_reserve
usd_deducted_amountstring实际扣款(USD),已含 usd_fee_reserve
truncation_lossstring小数截断产生的差额(玩家币种)
usd_truncation_lossstring小数截断产生的差额(USD)
fee_reservestring手续费预扣(玩家币种),按本单扣款比例换算;SELL 为 0
usd_fee_reservestring手续费预扣上限(USD),见公式;SELL 为 0
statusstring委托单状态(PREDICTION_ORDER_STATUS_*)
cancel_causestring取消原因代码
cause_detailstring取消原因详细说明
release_atstring延迟送单释放时间(RFC3339 UTC);仅 status = HELD 时有值
order_timestring下单时间(RFC3339 UTC)
updated_atstring最后更新时间(RFC3339 UTC)
changed_atstring该委托单的最后变动时间(RFC3339 UTC,最多 9 位小数秒);同一委托单只增不减,可作为版本号
client_ipstring下单时客户端 IP
device_typestring装置类型
device_idstring装置识别码
ex_market_idstring撮合引擎市场 ID(对账用)
ex_order_idstring撮合引擎委托单 ID(对账用)
engine_flippedboolean撮合引擎是否已将本单转换为对侧等价单(YES / NO 等价转换)
urlstring委托单详情页链接,含签名参数,可直接分享

TIP

changed_at 为平台数据的变动时间,并非下单时间,请勿作为业务时间使用。

数值单位 ​

字段单位
qty_units、filled_units1/100 股,例如 1000 = 10 股
limit_price_cents美分 / 股,0.01–99.99
大整数(股数、引擎 ID)以字符串输出,避免 JavaScript 精度丢失

手续费预扣 usd_fee_reserve ​

usd_fee_reserve = 股数 × max(taker 费率, maker 费率) × p × (1 − p)

p 为限价(美元 / 股,即 limit_price_cents ÷ 100)。

排序与分页 ​

  • items[] 依 changed_at 由旧到新排列,changed_at 相同时依 order_id 排列。
  • 第一页不带 cursor;has_more 为 true 时,带上 next_cursor 取下一页,直到 has_more 为 false。
  • 翻页期间委托单若再次变动,该委托单会移到更后面的位置再出现一次;已经取得的其他委托单不受影响,不会漏单。

同步建议 ​

建议的同步流程

  1. 以固定间隔(例如每 5 分钟)执行一轮同步,本轮区间为 [上一轮 end_time, 当前时间 − 3 分钟],且不超过 24 小时。
  2. 不带 cursor 取第一页,依 has_more / next_cursor 取完全部页。
  3. 每笔委托单以 order_id 写入(upsert):仅当 changed_at 比已存数据新时才覆盖。
  4. 本轮全部页取完后,记录本轮 end_time,作为下一轮的 start_time。
  • end_time 建议比当前时间早至少 3 分钟。 数据来源为备库,与主库之间有同步延迟;区间结束时间过于接近当前时间,可能漏取尚未同步的变动。
  • 区间可无缝衔接。 下一轮直接以本轮 end_time 作为 start_time;区间两端皆含,落在边界上的委托单可能在两轮都出现。
  • 须容许重复。 同一委托单可能在不同页或不同区间重复出现,商户端须以 order_id upsert,保持幂等。
  • 偶有批量变动。 平台重新同步数据时,可能有大量委托单在同一区间内出现,内容不变,按 upsert 处理即可。
  • 平行处理或重试时须比对 changed_at。 多个 worker 同时同步、或失败重试较晚写入时,较旧的结果可能晚于较新的结果写入;仅在 changed_at 较新时覆盖,可避免旧状态覆盖新状态。

委托单、成交与持仓 ​

Prediction 查询 API 分为三个层级:

3.7 委托单明细3.8 成交明细3.9 持仓明细
单位委托单 order成交 trade持仓 position
upsert 唯一键order_idtrade_idplayer_id + event_id + market_id + specifiers + outcome_id + side
视为变动下单、撮合、撤单、下单失败成交写入、成交状态变更买入、卖出、挂卖冻结 / 解冻、结算、重新结算、回滚、作废、派彩入账
适用场景下单、扣款、取消撮合价格、手续费、佣金结算盈亏、派彩

三个 API 的请求参数、分页方式与同步建议相同,可使用同一组 start_time / end_time 依序同步。

一张委托单可拆分为多笔成交;同一玩家在同一选项、同一方向上的成交累计为一笔持仓,结算盈亏以持仓为单位计算。

枚举 ​

方向 side(前缀 PREDICTION_SIDE_) ​

值说明
YES预测事件会发生
NO预测事件不会发生

买卖动作 action(前缀 PREDICTION_ACTION_) ​

值说明
BUY买入,建仓
SELL卖出持仓,平仓;仅 SELL 会实现盈亏

委托单状态 status(前缀 PREDICTION_ORDER_STATUS_) ​

值说明
PENDING已下单,等待撮合引擎确认
HELD延迟送单中,release_at 前不送出
FAILED下单失败
OPEN撮合引擎确认,挂单中
PARTIALLY_FILLED部分成交
FILLED全部成交
CANCELLED已取消(无任何成交)
PARTIAL_CANCELLED已取消(有部分成交)

错误码 ​

code说明
10020参数错误:缺少 start_time / end_time、未对齐整秒、end_time 未晚于 start_time、区间超过 24 小时、start_time 早于 6 个月前、cursor 无效或不属于本次区间

其他错误码与其他查询 API 一致,详见查询 APIs 错误对照表。

BFX · BE THE GAME CHANGER