3.7 委托单明细 API
PredictionIMPORTANT
Prediction 目前仍在内部测试阶段(alpha),请求参数与响应字段可能调整。
GET /api/v1/prediction/report/orders返回指定时间区间内有变动的委托单,以委托单(order)为单位,用于将委托单增量同步至商户系统。下单、撮合、撤单、下单失败等委托单本身的变动均视为变动。仅返回调用方代理旗下的数据。数据保留最近 6 个月。请求须带入 HMAC 验证 Header。
TIP
本 API 限流 100 次 / 分钟,超过返回 code:10060。额度按 api_key × 接口独立计算,各接口不共用;每次请求(含返回错误者)均计入。
IMPORTANT
委托单本身没有结算结果。结算、重新结算、回滚、作废等变动发生在持仓上,请以 3.9 持仓明细 同步。
请求参数(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。金额字段:usd_ 前缀为美元,无前缀为玩家币种。
{
"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..."
}
}| 字段 | 类型 | 说明 |
|---|---|---|
| items | array | 区间内有变动的委托单,内容为查询当下的最新状态 |
| has_more | boolean | 此区间是否还有下一页 |
| next_cursor | string | 下一页游标;has_more 为 false 时为空字符串 |
items[] 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| order_id | string | 委托单号,属唯一值 |
| idempotency_key | string | 下单幂等键 |
| player_id | string | 平台内部玩家 UUID |
| player_external_id | string | 玩家 ID(商户侧) |
| player_name | string | 玩家名称 |
| agent_id | string | 平台内部代理 UUID |
| agent_name | string | 代理名称 |
| sport_id / sport_name | string | 运动 ID / 名称 |
| tournament_id / tournament_name | string | 联赛 ID / 名称 |
| event_id / event_name | string | 赛事 ID / 名称 |
| event_start_time | string | 赛事开始时间(RFC3339 UTC) |
| market_id / market_name | string | 市场 ID / 名称 |
| specifiers | string | 市场参数;无参数市场为空字符串 |
| outcome_id / outcome_name | string | 投注选项 ID / 名称 |
| home_competitor_id / away_competitor_id | string | 主 / 客队 ID |
| home_competitor / away_competitor | string | 主 / 客队名称 |
| home_score / away_score | string | 下单时主 / 客队比分 |
| period_home_score / period_away_score | string | 下单时当前节 / 半场比分 |
| event_status | string | 赛事状态(如 not_started、live、ended) |
| match_status | string | 比赛状态码 |
| side | string | 方向(PREDICTION_SIDE_*) |
| action | string | 买卖动作(PREDICTION_ACTION_*) |
| limit_price_cents | string | 限价(美分 / 股,0.01–99.99) |
| max_price_ticks | integer | 价格 tick 基数(价格换算用) |
| qty_units | string | 委托股数(单位 1/100 股) |
| filled_units | string | 已成交股数(单位 1/100 股);未成交股数 = qty_units − filled_units |
| persistence | string | 挂单持续策略(如 Lapse) |
| runner_id | string | 撮合引擎 runner ID |
| currency | string | 玩家币种 |
| mid_rate | string | 下单时汇率 |
| deducted_amount | string | 实际扣款(玩家币种),已含 fee_reserve |
| usd_deducted_amount | string | 实际扣款(USD),已含 usd_fee_reserve |
| truncation_loss | string | 小数截断产生的差额(玩家币种) |
| usd_truncation_loss | string | 小数截断产生的差额(USD) |
| fee_reserve | string | 手续费预扣(玩家币种),按本单扣款比例换算;SELL 为 0 |
| usd_fee_reserve | string | 手续费预扣上限(USD),见公式;SELL 为 0 |
| status | string | 委托单状态(PREDICTION_ORDER_STATUS_*) |
| cancel_cause | string | 取消原因代码 |
| cause_detail | string | 取消原因详细说明 |
| release_at | string | 延迟送单释放时间(RFC3339 UTC);仅 status = HELD 时有值 |
| order_time | string | 下单时间(RFC3339 UTC) |
| updated_at | string | 最后更新时间(RFC3339 UTC) |
| changed_at | string | 该委托单的最后变动时间(RFC3339 UTC,最多 9 位小数秒);同一委托单只增不减,可作为版本号 |
| client_ip | string | 下单时客户端 IP |
| device_type | string | 装置类型 |
| device_id | string | 装置识别码 |
| ex_market_id | string | 撮合引擎市场 ID(对账用) |
| ex_order_id | string | 撮合引擎委托单 ID(对账用) |
| engine_flipped | boolean | 撮合引擎是否已将本单转换为对侧等价单(YES / NO 等价转换) |
| url | string | 委托单详情页链接,含签名参数,可直接分享 |
TIP
changed_at 为平台数据的变动时间,并非下单时间,请勿作为业务时间使用。
数值单位
| 字段 | 单位 |
|---|---|
| qty_units、filled_units | 1/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。 - 翻页期间委托单若再次变动,该委托单会移到更后面的位置再出现一次;已经取得的其他委托单不受影响,不会漏单。
同步建议
建议的同步流程
- 以固定间隔(例如每 5 分钟)执行一轮同步,本轮区间为
[上一轮 end_time, 当前时间 − 3 分钟],且不超过 24 小时。 - 不带
cursor取第一页,依has_more/next_cursor取完全部页。 - 每笔委托单以
order_id写入(upsert):仅当changed_at比已存数据新时才覆盖。 - 本轮全部页取完后,记录本轮
end_time,作为下一轮的start_time。
end_time建议比当前时间早至少 3 分钟。 数据来源为备库,与主库之间有同步延迟;区间结束时间过于接近当前时间,可能漏取尚未同步的变动。- 区间可无缝衔接。 下一轮直接以本轮
end_time作为start_time;区间两端皆含,落在边界上的委托单可能在两轮都出现。 - 须容许重复。 同一委托单可能在不同页或不同区间重复出现,商户端须以
order_idupsert,保持幂等。 - 偶有批量变动。 平台重新同步数据时,可能有大量委托单在同一区间内出现,内容不变,按 upsert 处理即可。
- 平行处理或重试时须比对
changed_at。 多个 worker 同时同步、或失败重试较晚写入时,较旧的结果可能晚于较新的结果写入;仅在changed_at较新时覆盖,可避免旧状态覆盖新状态。
委托单、成交与持仓
Prediction 查询 API 分为三个层级:
| 3.7 委托单明细 | 3.8 成交明细 | 3.9 持仓明细 | |
|---|---|---|---|
| 单位 | 委托单 order | 成交 trade | 持仓 position |
| upsert 唯一键 | order_id | trade_id | player_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 错误对照表。