3.8 成交明细 API
PredictionIMPORTANT
Prediction 目前仍在内部测试阶段(alpha),请求参数与响应字段可能调整。
GET /api/v1/prediction/report/trades返回指定时间区间内有变动的成交,以成交(trade)为单位,用于将成交增量同步至商户系统。成交写入及其后的状态变更均视为变动。仅返回调用方代理旗下玩家的成交,不含平台机器人的成交。数据保留最近 6 个月。请求须带入 HMAC 验证 Header。
TIP
本 API 限流 100 次 / 分钟,超过返回 code:10060。额度按 api_key × 接口独立计算,各接口不共用;每次请求(含返回错误者)均计入。
请求参数(Query String)
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
| start_time | TRUE | string | 变动时间区间起(含),RFC3339 UTC,须对齐整秒,例如 2026-10-20T00:00:00Z;不可早于 6 个月前 |
| end_time | TRUE | string | 变动时间区间迄(含),RFC3339 UTC,须对齐整秒;须晚于 start_time,与 start_time 间隔不可超过 24 小时 |
| cursor | FALSE | string | 分页游标;第一页不带,之后带上一页响应的 next_cursor |
| lang | FALSE | string | LANGUAGE_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 后缀为玩家币种。
{
"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)。
| 字段 | 类型 | 说明 |
|---|---|---|
| items | array | 区间内有变动的成交,内容为查询当下的最新状态 |
| has_more | boolean | 此区间是否还有下一页 |
| next_cursor | string | 下一页游标;has_more 为 false 时为空字符串 |
items[] 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| account_id | string | 下单账号 UUID(同 player_id) |
| name | string | 下单账号名称 |
| account_external_id | string | 下单账号 ID(商户侧玩家 ID) |
| event_id | string | 赛事 ID |
| market_id | string | 市场 ID |
| specifiers | string | 市场参数;无参数市场为空字符串 |
| outcome_id | string | 投注选项 ID |
| order_id | string | 所属委托单号 |
| trade_id | string | 成交单号,属唯一值 |
| side | string | 方向 yes / no |
| action | string | 买卖动作 buy / sell |
| role | string | 角色 maker / taker |
| price_cents | string | 成交价(美分 / 股,0.01–99.99) |
| max_price_ticks | integer | 价格 tick 基数(价格换算用) |
| matched_qty_units | string | 本次成交股数(单位 1/100 股) |
| remaining_qty_units | string | 本次成交后所属委托单剩余股数(单位 1/100 股) |
| currency | string | 玩家币种 |
| mid_rate | string | 汇率快照(显示用) |
| commission | string | 佣金(USD);亏损卖出为 0,买入成交为空字符串 |
| commission_local | string | 佣金(玩家币种) |
| commission_rate | string | 佣金率快照 |
| fee | string | 成交手续费(USD),见公式;买卖均收取 |
| fee_local | string | 成交手续费(玩家币种) |
| fee_rate | string | 本笔实际生效的手续费率;BUY 取当下费率与下单时快照上限的较小值 |
| status | string | 成交状态 pending / accepted / rejected |
| reject_reason | string | 拒绝原因;仅 status = rejected 时有值 |
| ex_seq | string | 撮合引擎全局递增序号 |
| ex_market_id | string | 撮合引擎市场 ID(对账用) |
| ex_market_seq | string | 撮合引擎市场级序号 |
| ex_tx_id | string | 撮合引擎成交交易 ID |
| ex_order_id | string | 撮合引擎委托单 ID(对账用) |
| product_id | string | 1 = 走地,3 = 早盘 |
| trade_time | string | 撮合时间(RFC3339 UTC) |
| created_at | string | 平台写入时间(RFC3339 UTC) |
| changed_at | string | 该成交的最后变动时间(RFC3339 UTC,最多 9 位小数秒);同一成交只增不减,可作为版本号 |
| agent_id / agent_name | string | 所属代理 UUID / 名称 |
| sport_id / sport_name | string | 运动 ID / 名称 |
| tournament_id / tournament_name | string | 联赛 ID / 名称 |
| event_name | string | 赛事名称(主队 vs 客队) |
| market_name | string | 市场名称 |
| outcome_name | string | 投注选项名称 |
| home_competitor_id / away_competitor_id | string | 主 / 客队 ID |
| home_competitor / away_competitor | string | 主 / 客队名称 |
| event_start_time | string | 赛事开始时间(RFC3339 UTC) |
| home_score / away_score | string | 下单时主 / 客队比分 |
| period_home_score / period_away_score | string | 下单时当前节 / 半场比分 |
| match_status | string | 比赛状态码 |
| event_status | string | 赛事状态(如 not_started、live、ended) |
| client_ip | string | 下单时客户端 IP(由所属委托单带入) |
| device_type | string | 装置类型(由所属委托单带入) |
| device_id | string | 装置识别码(由所属委托单带入) |
| order_time | string | 所属委托单下单时间(RFC3339 UTC) |
| order_status | string | 所属委托单状态(PREDICTION_ORDER_STATUS_*,见 3.7 委托单状态) |
TIP
changed_at 为平台数据的变动时间,并非撮合时间,请勿作为业务时间使用。本 API 不返回对手方信息。
数值单位
| 字段 | 单位 |
|---|---|
| matched_qty_units、remaining_qty_units | 1/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。 - 翻页期间成交若再次变动,该成交会移到更后面的位置再出现一次;已经取得的其他成交不受影响,不会漏单。
同步建议
建议的同步流程
- 以固定间隔(例如每 5 分钟)执行一轮同步,本轮区间为
[上一轮 end_time, 当前时间 − 3 分钟],且不超过 24 小时。 - 不带
cursor取第一页,依has_more/next_cursor取完全部页。 - 每笔成交以
trade_id写入(upsert):仅当changed_at比已存数据新时才覆盖。 - 本轮全部页取完后,记录本轮
end_time,作为下一轮的start_time。
end_time建议比当前时间早至少 3 分钟。 数据来源为备库,与主库之间有同步延迟;区间结束时间过于接近当前时间,可能漏取尚未同步的变动。- 区间可无缝衔接。 下一轮直接以本轮
end_time作为start_time;区间两端皆含,落在边界上的成交可能在两轮都出现。 - 须容许重复。 同一成交可能在不同页或不同区间重复出现,商户端须以
trade_idupsert,保持幂等。 - 偶有批量变动。 平台重新同步数据时,可能有大量成交在同一区间内出现,内容不变,按 upsert 处理即可。
- 平行处理或重试时须比对
changed_at。 多个 worker 同时同步、或失败重试较晚写入时,较旧的结果可能晚于较新的结果写入;仅在changed_at较新时覆盖,可避免旧状态覆盖新状态。
错误码
| code | 说明 |
|---|---|
| 10020 | 参数错误:缺少 start_time / end_time、未对齐整秒、end_time 未晚于 start_time、区间超过 24 小时、start_time 早于 6 个月前、cursor 无效或不属于本次区间 |
其他错误码与其他查询 API 一致,详见查询 APIs 错误对照表。