3.9 Position Details API
PredictionIMPORTANT
Prediction is still in internal testing (alpha); request parameters and response fields may change.
GET /api/v1/prediction/report/positionsReturns 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)
| Field | Required | Type | Description |
|---|---|---|---|
| start_time | TRUE | string | Start 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_time | TRUE | string | End 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 |
| cursor | FALSE | string | Pagination cursor; omit it for the first page, then pass the next_cursor from the previous response |
| lang | FALSE | string | LANGUAGE_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.
{
"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).
| Field | Type | Description |
|---|---|---|
| items | array | Positions that changed within the range, with their current state at query time |
| has_more | boolean | Whether this range has another page |
| next_cursor | string | Cursor for the next page; an empty string when has_more is false |
items[] Fields
| Field | Type | Description |
|---|---|---|
| player_id | string | Platform-internal player UUID |
| name | string | Player name |
| player_external_id | string | Player ID (merchant side) |
| event_id | string | Event ID |
| market_id | string | Market ID |
| specifiers | string | Market specifiers; empty string for markets without specifiers |
| outcome_id | string | Outcome ID |
| side | string | Side yes / no |
| qty_units | string | Shares held (in 1/100 shares) |
| locked_qty_units | string | Shares locked by resting sell orders (in 1/100 shares); sellable = qty_units − locked_qty_units |
| trade_count | integer | Cumulative number of trades in this position |
| buy_trade_matched_qty_units | string | Cumulative bought quantity (in 1/100 shares) |
| avg_cost | string | Weighted average cost per share (USD, 0–1) |
| avg_commission_rate | string | Weighted average commission rate; settlement commission is calculated with it |
| currency | string | Player currency; amount fields without the usd_ prefix are denominated in it |
| settlement_status | string | Settlement status pending / settled / voided |
| settled_time | string | Settlement time (RFC3339 UTC); not returned while unsettled |
| settlement_pnl | string | Settlement PnL (player currency), before commission |
| settlement_commission | string | Settlement commission (player currency); only charged on an actual win, not charged on voids or dead-heat splits |
| net_pnl | string | Net PnL (player currency) = settlement_pnl − settlement_commission |
| net_payout | string | Settlement payout (player currency) = gross payout − commission, including principal |
| usd_settlement_pnl | string | Settlement PnL (USD), before commission |
| usd_settlement_commission | string | Settlement commission (USD) |
| usd_net_pnl | string | Net PnL (USD) |
| usd_net_payout | string | Settlement payout (USD), including principal |
| payout_credited | boolean | Whether the payout has been credited to the player's wallet |
| void_source | string | Void source; only meaningful when settlement_status = voided, see Void Source |
| created_at | string | Position-opening time (time of the first buy fill, RFC3339 UTC) |
| updated_at | string | Last updated time (RFC3339 UTC) |
| changed_at | string | Last 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_name | string | Agent UUID / name |
| sport_id / sport_name | string | Sport ID / name |
| tournament_id / tournament_name | string | Tournament ID / name |
| event_name | string | Event name (home vs away) |
| market_name | string | Market name |
| outcome_name | string | Outcome name |
| home_competitor_id / away_competitor_id | string | Home / away team ID |
| home_competitor / away_competitor | string | Home / away team name |
| event_start_time | string | Event 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
| Value | Description | Payout |
|---|---|---|
| Not returned | Event cancelled; the whole market is voided | Each YES / NO share settles at 0.5 |
| admin | A single position voided by the platform back office | Refunded at cost |
IMPORTANT
The two kinds of void pay out completely differently; read void_source before interpreting a voided position.
Units
| Field | Unit |
|---|---|
| qty_units, locked_qty_units, buy_trade_matched_qty_units | 1/100 share, e.g. 1000 = 10 shares |
| avg_cost | USD / share, 0–1 (= price in cents ÷ 100) |
| Large integers (quantities) | Returned as strings to avoid JavaScript precision loss |
Sorting and Pagination
items[]is sorted bychanged_atfrom oldest to newest, then byplayer_id,event_id,market_id,specifiers,outcome_id,sidewhenchanged_atis equal.- Omit
cursorfor the first page. Whilehas_moreistrue, passnext_cursorto fetch the next page, untilhas_moreisfalse. - 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
- 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. - Fetch the first page without
cursor, then fetch every page by followinghas_more/next_cursor. - Upsert each item by the six-field key: overwrite only when
changed_atis newer than the stored data. - After all pages of the round are fetched, save the round's
end_timeas the next round'sstart_time.
- Keep
end_timeat 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_timedirectly as the next round'sstart_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_atwhen 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 whenchanged_atis newer prevents an old state from replacing a new one.
Error Codes
| code | Description |
|---|---|
| 10020 | Invalid 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.