Skip to content

3.9 持仓明细 API ​

Prediction

IMPORTANT

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

http
GET /api/v1/prediction/report/positions

返回指定时间区间内有变动的玩家持仓,以持仓(position)为单位,含结算盈亏与派彩,用于将持仓增量同步至商户系统。买入、卖出、挂卖冻结 / 解冻、结算、重新结算、回滚、作废、派彩入账等变动均视为变动。仅返回调用方代理旗下的数据。数据保留最近 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。金额字段:usd_ 前缀为美元,无前缀为玩家币种。

json
{
  "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)。

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

items[] 字段 ​

字段类型说明
player_idstring平台内部玩家 UUID
namestring玩家名称
player_external_idstring玩家 ID(商户侧)
event_idstring赛事 ID
market_idstring市场 ID
specifiersstring市场参数;无参数市场为空字符串
outcome_idstring投注选项 ID
sidestring方向 yes / no
qty_unitsstring持有股数(单位 1/100 股)
locked_qty_unitsstring挂卖单冻结中的股数(单位 1/100 股);可卖股数 = qty_units − locked_qty_units
trade_countinteger本持仓累计成交笔数
buy_trade_matched_qty_unitsstring累计买入成交股数(单位 1/100 股)
avg_coststring加权平均每股成本(USD,0–1)
avg_commission_ratestring加权平均佣金率;结算佣金以此计算
currencystring玩家币种;无 usd_ 前缀的金额字段以此计价
settlement_statusstring结算状态 pending / settled / voided
settled_timestring结算时间(RFC3339 UTC);未结算时不返回
settlement_pnlstring结算盈亏(玩家币种),未扣佣金
settlement_commissionstring结算佣金(玩家币种);仅实际获胜时收取,作废及和局分账均不收取
net_pnlstring净盈亏(玩家币种)= settlement_pnl − settlement_commission
net_payoutstring结算派彩(玩家币种)= 派彩总额 − 佣金,含本金
usd_settlement_pnlstring结算盈亏(USD),未扣佣金
usd_settlement_commissionstring结算佣金(USD)
usd_net_pnlstring净盈亏(USD)
usd_net_payoutstring结算派彩(USD),含本金
payout_creditedboolean派彩是否已入账至玩家钱包
void_sourcestring作废来源;仅 settlement_status = voided 时有意义,见作废来源
created_atstring建仓时间(首笔买入成交时间,RFC3339 UTC)
updated_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)

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_units1/100 股,例如 1000 = 10 股
avg_costUSD / 股,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。
  • 翻页期间持仓若再次变动,该持仓会移到更后面的位置再出现一次;已经取得的其他持仓不受影响,不会漏单。

同步建议 ​

建议的同步流程

  1. 以固定间隔(例如每 5 分钟)执行一轮同步,本轮区间为 [上一轮 end_time, 当前时间 − 3 分钟],且不超过 24 小时。
  2. 不带 cursor 取第一页,依 has_more / next_cursor 取完全部页。
  3. 每笔持仓以六个字段组成的唯一键写入(upsert):仅当 changed_at 比已存数据新时才覆盖。
  4. 本轮全部页取完后,记录本轮 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 错误对照表。

BFX · BE THE GAME CHANGER