3.7 Order Details API
PredictionIMPORTANT
Prediction is still in internal testing (alpha); request parameters and response fields may change.
GET /api/v1/prediction/report/ordersReturns the orders that changed within a time range, one record per order, for incrementally syncing orders into the merchant's system. Any change to the order itself — placement, a fill, a cancellation, a failed placement, and so on — counts as a change. 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.
IMPORTANT
Orders carry no settlement result. Settlement, re-settlement, rollback and voiding happen on positions; sync them with 3.9 Position Details.
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[] (orders), has_more and next_cursor. Amount fields: the usd_ prefix means USD; no prefix means player currency.
{
"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..."
}
}| Field | Type | Description |
|---|---|---|
| items | array | Orders 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 |
|---|---|---|
| order_id | string | Order ID, unique |
| idempotency_key | string | Order idempotency key |
| player_id | string | Platform-internal player UUID |
| player_external_id | string | Player ID (merchant side) |
| player_name | string | Player name |
| agent_id | string | Platform-internal agent UUID |
| agent_name | string | Agent name |
| sport_id / sport_name | string | Sport ID / name |
| tournament_id / tournament_name | string | Tournament ID / name |
| event_id / event_name | string | Event ID / name |
| event_start_time | string | Event start time (RFC3339 UTC) |
| market_id / market_name | string | Market ID / name |
| specifiers | string | Market specifiers; empty string for markets without specifiers |
| outcome_id / outcome_name | string | Outcome ID / name |
| home_competitor_id / away_competitor_id | string | Home / away team ID |
| home_competitor / away_competitor | string | Home / away team name |
| home_score / away_score | string | Home / away score at order time |
| period_home_score / period_away_score | string | Current period / half score at order time |
| event_status | string | Event status (e.g. not_started, live, ended) |
| match_status | string | Match status code |
| side | string | Side (PREDICTION_SIDE_*) |
| action | string | Action (PREDICTION_ACTION_*) |
| limit_price_cents | string | Limit price (cents / share, 0.01–99.99) |
| max_price_ticks | integer | Price tick base (for price conversion) |
| qty_units | string | Order quantity (in 1/100 shares) |
| filled_units | string | Filled quantity (in 1/100 shares); unfilled = qty_units − filled_units |
| persistence | string | Order persistence policy (e.g. Lapse) |
| runner_id | string | Matching engine runner ID |
| currency | string | Player currency |
| mid_rate | string | Exchange rate at order time |
| deducted_amount | string | Amount actually deducted (player currency), including fee_reserve |
| usd_deducted_amount | string | Amount actually deducted (USD), including usd_fee_reserve |
| truncation_loss | string | Difference caused by decimal truncation (player currency) |
| usd_truncation_loss | string | Difference caused by decimal truncation (USD) |
| fee_reserve | string | Fee reserve (player currency), converted at this order's deduction ratio; 0 for SELL |
| usd_fee_reserve | string | Fee reserve upper bound (USD), see formula; 0 for SELL |
| status | string | Order status (PREDICTION_ORDER_STATUS_*) |
| cancel_cause | string | Cancellation reason code |
| cause_detail | string | Cancellation reason details |
| release_at | string | Delayed-submission release time (RFC3339 UTC); only set when status = HELD |
| order_time | string | Order time (RFC3339 UTC) |
| updated_at | string | Last updated time (RFC3339 UTC) |
| changed_at | string | Last change time of the order (RFC3339 UTC, up to 9 fractional-second digits); never decreases for a given order, so it can be used as a version |
| client_ip | string | Client IP at order time |
| device_type | string | Device type |
| device_id | string | Device identifier |
| ex_market_id | string | Matching engine market ID (for reconciliation) |
| ex_order_id | string | Matching engine order ID (for reconciliation) |
| engine_flipped | boolean | Whether the matching engine has converted this order to its equivalent on the opposite side (YES / NO equivalence) |
| url | string | Order detail page link, including signature parameters; shareable as-is |
TIP
changed_at is the time the platform's data changed. It is not the order time, so do not use it as a business time.
Units
| Field | Unit |
|---|---|
| qty_units, filled_units | 1/100 share, e.g. 1000 = 10 shares |
| limit_price_cents | Cents / share, 0.01–99.99 |
| Large integers (quantities, engine IDs) | Returned as strings to avoid JavaScript precision loss |
Fee Reserve usd_fee_reserve
usd_fee_reserve = shares × max(taker rate, maker rate) × p × (1 − p)
p is the limit price (USD / share, i.e. limit_price_cents ÷ 100).
Sorting and Pagination
items[]is sorted bychanged_atfrom oldest to newest, then byorder_idwhenchanged_atis equal.- Omit
cursorfor the first page. Whilehas_moreistrue, passnext_cursorto fetch the next page, untilhas_moreisfalse. - If an order changes again while you are paging, it moves further back and appears once more; the other orders 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
order_id: overwrite only whenchanged_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 an order 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
order_idon the merchant side to stay idempotent. - Occasional bulk changes. When the platform re-syncs data, a large number of orders 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.
Orders, Trades and Positions
The Prediction query APIs cover three levels:
| 3.7 Order Details | 3.8 Trade Details | 3.9 Position Details | |
|---|---|---|---|
| Unit | Order | Trade | Position |
| Upsert key | order_id | trade_id | player_id + event_id + market_id + specifiers + outcome_id + side |
| Counts as a change | Placement, fills, cancellation, failed placement | Trade written, trade status change | Buys, sells, sell-lock / unlock, settlement, re-settlement, rollback, voiding, payout credited |
| Use for | Orders, deductions, cancellations | Matched prices, fees, commission | Settlement PnL, payouts |
All three APIs share the same request parameters, pagination and sync recommendations, so you can sync them in turn with the same start_time / end_time.
One order can be split into multiple trades; a player's trades on the same outcome and side accumulate into one position, and settlement PnL is calculated per position.
Enums
Side (prefix PREDICTION_SIDE_)
| Value | Description |
|---|---|
| YES | Predicts the event will happen |
| NO | Predicts the event will not happen |
Action (prefix PREDICTION_ACTION_)
| Value | Description |
|---|---|
| BUY | Buy, opening a position |
| SELL | Sell held shares, closing a position; only SELL realizes PnL |
Order Status (prefix PREDICTION_ORDER_STATUS_)
| Value | Description |
|---|---|
| PENDING | Order placed, awaiting matching engine confirmation |
| HELD | Delayed submission; not sent before release_at |
| FAILED | Order failed |
| OPEN | Confirmed by the matching engine, resting on the book |
| PARTIALLY_FILLED | Partially filled |
| FILLED | Fully filled |
| CANCELLED | Cancelled (no fills) |
| PARTIAL_CANCELLED | Cancelled (partially filled) |
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.