Skip to content

3.8 成交明细 API ​

Prediction

IMPORTANT

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

http
GET /api/v1/prediction/report/trades

返回指定时间区间内有变动的成交,以成交(trade)为单位,用于将成交增量同步至商户系统。成交写入及其后的状态变更均视为变动。仅返回调用方代理旗下玩家的成交,不含平台机器人的成交。数据保留最近 6 个月。请求须带入 HMAC 验证 Header。

TIP

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

请求参数(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。金额字段:无 _local 后缀为 USD,_local 后缀为玩家币种。

json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "account_id": "00000000-0000-0000-0000-000000000000",
        "name": "player1_name",
        "account_external_id": "player1",
        "event_id": "sr:match:00000000",
        "market_id": "1",
        "specifiers": "",
        "outcome_id": "1",
        "order_id": "019e0000-0000-0000-0000-000000000000",
        "trade_id": "019e0000-0000-0000-0000-000000000001",
        "side": "yes",
        "action": "buy",
        "role": "taker",
        "price_cents": "55",
        "max_price_ticks": 10000,
        "matched_qty_units": "1000",
        "remaining_qty_units": "0",
        "currency": "CNY",
        "mid_rate": "7.1",
        "commission": "",
        "commission_local": "",
        "commission_rate": "0.03",
        "fee": "0.0495",
        "fee_local": "0.35145",
        "fee_rate": "0.02",
        "status": "accepted",
        "reject_reason": "",
        "ex_seq": "4000000000001",
        "ex_market_id": "2000000000001",
        "ex_market_seq": "5000000000001",
        "ex_tx_id": "6000000000001",
        "ex_order_id": "3000000000001",
        "product_id": "3",
        "trade_time": "2026-10-05T08:00:01Z",
        "created_at": "2026-10-05T08:00:01Z",
        "changed_at": "2026-10-05T08:00:01.284553771Z",
        "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_name": "Team A vs Team B",
        "market_name": "Match Winner",
        "outcome_name": "Team A",
        "home_competitor_id": "sr:competitor:0001",
        "home_competitor": "Team A",
        "away_competitor_id": "sr:competitor:0002",
        "away_competitor": "Team B",
        "event_start_time": "2026-10-10T12:00:00Z",
        "home_score": "0",
        "away_score": "0",
        "period_home_score": "0",
        "period_away_score": "0",
        "match_status": "0",
        "event_status": "not_started",
        "client_ip": "203.0.113.10",
        "device_type": "PC",
        "device_id": "device-001",
        "order_time": "2026-10-05T08:00:00Z",
        "order_status": "PREDICTION_ORDER_STATUS_FILLED"
      }
    ],
    "has_more": true,
    "next_cursor": "eyJ2IjoyLCJzIjoxNzkxOTM2MDAwMDAwMDAwMDAw..."
  }
}

IMPORTANT

响应中的 side、action、role、status 为小写字符串(如 yes、buy、accepted);order_status 为完整枚举值(如 PREDICTION_ORDER_STATUS_FILLED)。

字段类型说明
itemsarray区间内有变动的成交,内容为查询当下的最新状态
has_moreboolean此区间是否还有下一页
next_cursorstring下一页游标;has_more 为 false 时为空字符串

items[] 字段 ​

字段类型说明
account_idstring下单账号 UUID(同 player_id)
namestring下单账号名称
account_external_idstring下单账号 ID(商户侧玩家 ID)
event_idstring赛事 ID
market_idstring市场 ID
specifiersstring市场参数;无参数市场为空字符串
outcome_idstring投注选项 ID
order_idstring所属委托单号
trade_idstring成交单号,属唯一值
sidestring方向 yes / no
actionstring买卖动作 buy / sell
rolestring角色 maker / taker
price_centsstring成交价(美分 / 股,0.01–99.99)
max_price_ticksinteger价格 tick 基数(价格换算用)
matched_qty_unitsstring本次成交股数(单位 1/100 股)
remaining_qty_unitsstring本次成交后所属委托单剩余股数(单位 1/100 股)
currencystring玩家币种
mid_ratestring汇率快照(显示用)
commissionstring佣金(USD);亏损卖出为 0,买入成交为空字符串
commission_localstring佣金(玩家币种)
commission_ratestring佣金率快照
feestring成交手续费(USD),见公式;买卖均收取
fee_localstring成交手续费(玩家币种)
fee_ratestring本笔实际生效的手续费率;BUY 取当下费率与下单时快照上限的较小值
statusstring成交状态 pending / accepted / rejected
reject_reasonstring拒绝原因;仅 status = rejected 时有值
ex_seqstring撮合引擎全局递增序号
ex_market_idstring撮合引擎市场 ID(对账用)
ex_market_seqstring撮合引擎市场级序号
ex_tx_idstring撮合引擎成交交易 ID
ex_order_idstring撮合引擎委托单 ID(对账用)
product_idstring1 = 走地,3 = 早盘
trade_timestring撮合时间(RFC3339 UTC)
created_atstring平台写入时间(RFC3339 UTC)
changed_atstring该成交的最后变动时间(RFC3339 UTC,最多 9 位小数秒);同一成交只增不减,可作为版本号
agent_id / agent_namestring所属代理 UUID / 名称
sport_id / sport_namestring运动 ID / 名称
tournament_id / tournament_namestring联赛 ID / 名称
event_namestring赛事名称(主队 vs 客队)
market_namestring市场名称
outcome_namestring投注选项名称
home_competitor_id / away_competitor_idstring主 / 客队 ID
home_competitor / away_competitorstring主 / 客队名称
event_start_timestring赛事开始时间(RFC3339 UTC)
home_score / away_scorestring下单时主 / 客队比分
period_home_score / period_away_scorestring下单时当前节 / 半场比分
match_statusstring比赛状态码
event_statusstring赛事状态(如 not_started、live、ended)
client_ipstring下单时客户端 IP(由所属委托单带入)
device_typestring装置类型(由所属委托单带入)
device_idstring装置识别码(由所属委托单带入)
order_timestring所属委托单下单时间(RFC3339 UTC)
order_statusstring所属委托单状态(PREDICTION_ORDER_STATUS_*,见 3.7 委托单状态)

TIP

changed_at 为平台数据的变动时间,并非撮合时间,请勿作为业务时间使用。本 API 不返回对手方信息。

数值单位 ​

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

成交手续费 fee ​

fee = 股数 × fee_rate × p × (1 − p)

p 为成交价(美元 / 股,即 price_cents ÷ 100)。

排序与分页 ​

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

同步建议 ​

建议的同步流程

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

错误码 ​

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

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

BFX · BE THE GAME CHANGER