3.9 持仓明细 API
PredictionIMPORTANT
Prediction 目前仍在内部测试阶段(alpha),请求参数与响应字段可能调整。
GET /api/v1/prediction/report/positions返回指定时间区间内有变动的玩家持仓,以持仓(position)为单位,含结算盈亏与派彩,用于将持仓增量同步至商户系统。买入、卖出、挂卖冻结 / 解冻、结算、重新结算、回滚、作废、派彩入账等变动均视为变动。仅返回调用方代理旗下的数据。数据保留最近 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。金额字段:usd_ 前缀为美元,无前缀为玩家币种。
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"player_id": "00000000-0000-0000-0000-000000000000",
"name": "player1_name",
"player_external_id": "player1",
"event_id": "sr:match:00000000",
"market_id": "1",
"specifiers": "",
"outcome_id": "1",
"side": "yes",
"qty_units": "1000",
"locked_qty_units": "0",
"trade_count": 1,
"buy_trade_matched_qty_units": "1000",
"avg_cost": "0.55",
"avg_commission_rate": "0.03",
"currency": "CNY",
"settlement_status": "settled",
"settled_time": "2026-10-10T14:00:00Z",
"settlement_pnl": "31.95",
"settlement_commission": "0.9585",
"net_pnl": "30.9915",
"net_payout": "70.0415",
"usd_settlement_pnl": "4.5",
"usd_settlement_commission": "0.135",
"usd_net_pnl": "4.365",
"usd_net_payout": "9.865",
"payout_credited": true,
"created_at": "2026-10-05T08:00:01Z",
"updated_at": "2026-10-10T14:00:05Z",
"changed_at": "2026-10-10T14:00:05.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"
}
],
"has_more": true,
"next_cursor": "eyJ2IjoyLCJzIjoxNzkxOTM2MDAwMDAwMDAwMDAw..."
}
}IMPORTANT
响应中的 side、settlement_status 为小写字符串(如 yes、settled)。
| 字段 | 类型 | 说明 |
|---|---|---|
| items | array | 区间内有变动的持仓,内容为查询当下的最新状态 |
| has_more | boolean | 此区间是否还有下一页 |
| next_cursor | string | 下一页游标;has_more 为 false 时为空字符串 |
items[] 字段
| 字段 | 类型 | 说明 |
|---|---|---|
| player_id | string | 平台内部玩家 UUID |
| name | string | 玩家名称 |
| player_external_id | string | 玩家 ID(商户侧) |
| event_id | string | 赛事 ID |
| market_id | string | 市场 ID |
| specifiers | string | 市场参数;无参数市场为空字符串 |
| outcome_id | string | 投注选项 ID |
| side | string | 方向 yes / no |
| qty_units | string | 持有股数(单位 1/100 股) |
| locked_qty_units | string | 挂卖单冻结中的股数(单位 1/100 股);可卖股数 = qty_units − locked_qty_units |
| trade_count | integer | 本持仓累计成交笔数 |
| buy_trade_matched_qty_units | string | 累计买入成交股数(单位 1/100 股) |
| avg_cost | string | 加权平均每股成本(USD,0–1) |
| avg_commission_rate | string | 加权平均佣金率;结算佣金以此计算 |
| currency | string | 玩家币种;无 usd_ 前缀的金额字段以此计价 |
| settlement_status | string | 结算状态 pending / settled / voided |
| settled_time | string | 结算时间(RFC3339 UTC);未结算时不返回 |
| settlement_pnl | string | 结算盈亏(玩家币种),未扣佣金 |
| settlement_commission | string | 结算佣金(玩家币种);仅实际获胜时收取,作废及和局分账均不收取 |
| net_pnl | string | 净盈亏(玩家币种)= settlement_pnl − settlement_commission |
| net_payout | string | 结算派彩(玩家币种)= 派彩总额 − 佣金,含本金 |
| usd_settlement_pnl | string | 结算盈亏(USD),未扣佣金 |
| usd_settlement_commission | string | 结算佣金(USD) |
| usd_net_pnl | string | 净盈亏(USD) |
| usd_net_payout | string | 结算派彩(USD),含本金 |
| payout_credited | boolean | 派彩是否已入账至玩家钱包 |
| void_source | string | 作废来源;仅 settlement_status = voided 时有意义,见作废来源 |
| created_at | string | 建仓时间(首笔买入成交时间,RFC3339 UTC) |
| updated_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) |
IMPORTANT
未结算时,结算相关金额字段返回空字符串 "" 而非 "0",用于区分「尚未结算」与「盈亏为零」。
TIP
持仓没有单一 ID,以 player_id + event_id + market_id + specifiers + outcome_id + side 六个字段唯一识别;specifiers 为空字符串时也是唯一键的一部分。changed_at 为平台数据的变动时间,并非建仓或结算时间,请勿作为业务时间使用。
金额说明
- 无前缀字段为玩家币种,
usd_前缀为 USD。 - 玩家币种金额由平台按本持仓的成本比例换算,与玩家钱包实际入账金额一致。
- 已完全平仓、成本归零的持仓无法换算,玩家币种字段返回
"0"。
作废来源 void_source
| 值 | 说明 | 派彩方式 |
|---|---|---|
| 不返回 | 赛事取消,整个市场作废 | YES / NO 每股均按 0.5 结算 |
| admin | 平台后台作废单笔持仓 | 按成本退款 |
IMPORTANT
两种作废的派彩方式完全不同,解读 voided 持仓前须先读取 void_source。
数值单位
| 字段 | 单位 |
|---|---|
| qty_units、locked_qty_units、buy_trade_matched_qty_units | 1/100 股,例如 1000 = 10 股 |
| avg_cost | USD / 股,0–1(= 美分价格 ÷ 100) |
| 大整数(股数) | 以字符串输出,避免 JavaScript 精度丢失 |
排序与分页
items[]依changed_at由旧到新排列,changed_at相同时依player_id、event_id、market_id、specifiers、outcome_id、side排列。- 第一页不带
cursor;has_more为true时,带上next_cursor取下一页,直到has_more为false。 - 翻页期间持仓若再次变动,该持仓会移到更后面的位置再出现一次;已经取得的其他持仓不受影响,不会漏单。
同步建议
建议的同步流程
- 以固定间隔(例如每 5 分钟)执行一轮同步,本轮区间为
[上一轮 end_time, 当前时间 − 3 分钟],且不超过 24 小时。 - 不带
cursor取第一页,依has_more/next_cursor取完全部页。 - 每笔持仓以六个字段组成的唯一键写入(upsert):仅当
changed_at比已存数据新时才覆盖。 - 本轮全部页取完后,记录本轮
end_time,作为下一轮的start_time。
end_time建议比当前时间早至少 3 分钟。 数据来源为备库,与主库之间有同步延迟;区间结束时间过于接近当前时间,可能漏取尚未同步的变动。- 区间可无缝衔接。 下一轮直接以本轮
end_time作为start_time;区间两端皆含,落在边界上的持仓可能在两轮都出现。 - 须容许重复。 同一持仓可能在不同页或不同区间重复出现,商户端须以唯一键 upsert,保持幂等。
- 偶有批量变动。 平台重新同步数据时,可能有大量持仓在同一区间内出现,内容不变,按 upsert 处理即可。
- 平行处理或重试时须比对
changed_at。 多个 worker 同时同步、或失败重试较晚写入时,较旧的结果可能晚于较新的结果写入;仅在changed_at较新时覆盖,可避免旧状态覆盖新状态。
错误码
| code | 说明 |
|---|---|
| 10020 | 参数错误:缺少 start_time / end_time、未对齐整秒、end_time 未晚于 start_time、区间超过 24 小时、start_time 早于 6 个月前、cursor 无效或不属于本次区间 |
其他错误码与其他查询 API 一致,详见查询 APIs 错误对照表。