Skip to content

3.9 Position Details API ​

Prediction

IMPORTANT

Prediction is still in internal testing (alpha); request parameters and response fields may change.

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

Returns the player positions that changed within a time range, one record per position, including settlement PnL and payouts, for incrementally syncing positions into the merchant's system. Buys, sells, sell-lock / unlock, settlement, re-settlement, rollback, voiding, payout crediting and similar changes count as changes. Only data under the calling agent is returned. The most recent 6 months of data is retained. Requests must include the HMAC authentication header.

TIP

This API is rate-limited to 100 requests / minute; exceeding it returns code:10060. The quota is counted per api_key × endpoint — endpoints do not share a quota, and every request (including those returning an error) counts toward it.

Request Parameters (Query String) ​

FieldRequiredTypeDescription
start_timeTRUEstringStart of the change time range (inclusive), RFC3339 UTC, aligned to whole seconds, e.g. 2026-10-20T00:00:00Z; must not be earlier than 6 months ago
end_timeTRUEstringEnd of the change time range (inclusive), RFC3339 UTC, aligned to whole seconds; must be later than start_time and no more than 24 hours after it
cursorFALSEstringPagination cursor; omit it for the first page, then pass the next_cursor from the previous response
langFALSEstringLANGUAGE_ZH_CN / LANGUAGE_EN (defaults to English)

TIP

This API uses cursor pagination with a fixed maximum of 100 items per page; page / page_size are not supported. A cursor is valid only for the same start_time / end_time pair that produced it — when you change the range, start again from the first page. The cursor format is not guaranteed; do not parse or construct it yourself.

Response data ​

data contains items[] (positions), has_more and next_cursor. Amount fields: the usd_ prefix means USD; no prefix means player currency.

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

In the response, side and settlement_status are lowercase strings (e.g. yes, settled).

FieldTypeDescription
itemsarrayPositions that changed within the range, with their current state at query time
has_morebooleanWhether this range has another page
next_cursorstringCursor for the next page; an empty string when has_more is false

items[] Fields ​

FieldTypeDescription
player_idstringPlatform-internal player UUID
namestringPlayer name
player_external_idstringPlayer ID (merchant side)
event_idstringEvent ID
market_idstringMarket ID
specifiersstringMarket specifiers; empty string for markets without specifiers
outcome_idstringOutcome ID
sidestringSide yes / no
qty_unitsstringShares held (in 1/100 shares)
locked_qty_unitsstringShares locked by resting sell orders (in 1/100 shares); sellable = qty_units − locked_qty_units
trade_countintegerCumulative number of trades in this position
buy_trade_matched_qty_unitsstringCumulative bought quantity (in 1/100 shares)
avg_coststringWeighted average cost per share (USD, 0–1)
avg_commission_ratestringWeighted average commission rate; settlement commission is calculated with it
currencystringPlayer currency; amount fields without the usd_ prefix are denominated in it
settlement_statusstringSettlement status pending / settled / voided
settled_timestringSettlement time (RFC3339 UTC); not returned while unsettled
settlement_pnlstringSettlement PnL (player currency), before commission
settlement_commissionstringSettlement commission (player currency); only charged on an actual win, not charged on voids or dead-heat splits
net_pnlstringNet PnL (player currency) = settlement_pnl − settlement_commission
net_payoutstringSettlement payout (player currency) = gross payout − commission, including principal
usd_settlement_pnlstringSettlement PnL (USD), before commission
usd_settlement_commissionstringSettlement commission (USD)
usd_net_pnlstringNet PnL (USD)
usd_net_payoutstringSettlement payout (USD), including principal
payout_creditedbooleanWhether the payout has been credited to the player's wallet
void_sourcestringVoid source; only meaningful when settlement_status = voided, see Void Source
created_atstringPosition-opening time (time of the first buy fill, RFC3339 UTC)
updated_atstringLast updated time (RFC3339 UTC)
changed_atstringLast change time of the position (RFC3339 UTC, up to 9 fractional-second digits); never decreases for a given position, so it can be used as a version
agent_id / agent_namestringAgent UUID / name
sport_id / sport_namestringSport ID / name
tournament_id / tournament_namestringTournament ID / name
event_namestringEvent name (home vs away)
market_namestringMarket name
outcome_namestringOutcome name
home_competitor_id / away_competitor_idstringHome / away team ID
home_competitor / away_competitorstringHome / away team name
event_start_timestringEvent start time (RFC3339 UTC)

IMPORTANT

While unsettled, settlement amount fields return an empty string "", not "0", to distinguish "not yet settled" from "zero PnL".

TIP

A position has no single ID; it is identified by the six fields player_id + event_id + market_id + specifiers + outcome_id + side. An empty specifiers is still part of the key. changed_at is the time the platform's data changed. It is not the opening or settlement time, so do not use it as a business time.

Amounts ​

  • Fields without a prefix are in player currency; the usd_ prefix means USD.
  • Player-currency amounts are converted by the platform at this position's cost ratio and match the amount actually credited to the player's wallet.
  • A fully closed position with zero cost basis cannot be converted; its player-currency fields return "0".

Void Source void_source ​

ValueDescriptionPayout
Not returnedEvent cancelled; the whole market is voidedEach YES / NO share settles at 0.5
adminA single position voided by the platform back officeRefunded at cost

IMPORTANT

The two kinds of void pay out completely differently; read void_source before interpreting a voided position.

Units ​

FieldUnit
qty_units, locked_qty_units, buy_trade_matched_qty_units1/100 share, e.g. 1000 = 10 shares
avg_costUSD / share, 0–1 (= price in cents ÷ 100)
Large integers (quantities)Returned as strings to avoid JavaScript precision loss

Sorting and Pagination ​

  • items[] is sorted by changed_at from oldest to newest, then by player_id, event_id, market_id, specifiers, outcome_id, side when changed_at is equal.
  • Omit cursor for the first page. While has_more is true, pass next_cursor to fetch the next page, until has_more is false.
  • If a position changes again while you are paging, it moves further back and appears once more; the other positions you already fetched are unaffected, so nothing is missed.

Sync Recommendations ​

Recommended sync flow

  1. Run a sync round at a fixed interval (e.g. every 5 minutes). The range for each round is [previous end_time, now − 3 minutes], and must not exceed 24 hours.
  2. Fetch the first page without cursor, then fetch every page by following has_more / next_cursor.
  3. Upsert each item by the six-field key: overwrite only when changed_at is newer than the stored data.
  4. After all pages of the round are fetched, save the round's end_time as the next round's start_time.
  • Keep end_time at least 3 minutes before the current time. Data comes from a standby database that syncs from the primary database with a delay; an end time too close to now may miss changes that have not been synced yet.
  • Ranges chain without gaps. Use this round's end_time directly as the next round's start_time. Both ends of a range are inclusive, so a position exactly on the boundary may appear in both rounds.
  • Expect duplicates. The same item may appear on different pages or in different ranges. Upsert by the six-field key on the merchant side to stay idempotent.
  • Occasional bulk changes. When the platform re-syncs data, a large number of positions may appear in the same range with unchanged content. Upsert them as usual.
  • Compare changed_at when processing in parallel or retrying. With several workers syncing at once, or a failed request retried later, an older result may be written after a newer one. Overwriting only when changed_at is newer prevents an old state from replacing a new one.

Error Codes ​

codeDescription
10020Invalid parameter: start_time / end_time missing or not aligned to whole seconds, end_time not later than start_time, range longer than 24 hours, start_time earlier than 6 months ago, or cursor invalid or not belonging to this range

Other error codes are the same as the other query APIs; see the Query APIs Error Reference.

BFX · BE THE GAME CHANGER