3.8 Trade Details API
PredictionIMPORTANT
Prediction is still in internal testing (alpha); request parameters and response fields may change.
GET /api/v1/prediction/report/tradesReturns the trades that changed within a time range, one record per trade, for incrementally syncing trades into the merchant's system. A trade being written and any later status change count as changes. Only trades of the calling agent's players are returned; platform bot trades are not included. 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[] (trades), has_more and next_cursor. Amount fields: no _local suffix means USD; the _local suffix means player currency.
{
"code": 0,
"message": "success",
"data": {
"items": [
{
"account_id": "00000000-0000-0000-0000-000000000000",
"name": "player1_name",
"account_external_id": "player1",
"event_id": "sr:match:00000000",
"market_id": "1",
"specifiers": "",
"outcome_id": "1",
"order_id": "019e0000-0000-0000-0000-000000000000",
"trade_id": "019e0000-0000-0000-0000-000000000001",
"side": "yes",
"action": "buy",
"role": "taker",
"price_cents": "55",
"max_price_ticks": 10000,
"matched_qty_units": "1000",
"remaining_qty_units": "0",
"currency": "CNY",
"mid_rate": "7.1",
"commission": "",
"commission_local": "",
"commission_rate": "0.03",
"fee": "0.0495",
"fee_local": "0.35145",
"fee_rate": "0.02",
"status": "accepted",
"reject_reason": "",
"ex_seq": "4000000000001",
"ex_market_id": "2000000000001",
"ex_market_seq": "5000000000001",
"ex_tx_id": "6000000000001",
"ex_order_id": "3000000000001",
"product_id": "3",
"trade_time": "2026-10-05T08:00:01Z",
"created_at": "2026-10-05T08:00:01Z",
"changed_at": "2026-10-05T08:00:01.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",
"home_score": "0",
"away_score": "0",
"period_home_score": "0",
"period_away_score": "0",
"match_status": "0",
"event_status": "not_started",
"client_ip": "203.0.113.10",
"device_type": "PC",
"device_id": "device-001",
"order_time": "2026-10-05T08:00:00Z",
"order_status": "PREDICTION_ORDER_STATUS_FILLED"
}
],
"has_more": true,
"next_cursor": "eyJ2IjoyLCJzIjoxNzkxOTM2MDAwMDAwMDAwMDAw..."
}
}IMPORTANT
In the response, side, action, role and status are lowercase strings (e.g. yes, buy, accepted); order_status is the full enum value (e.g. PREDICTION_ORDER_STATUS_FILLED).
| Field | Type | Description |
|---|---|---|
| items | array | Trades 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 |
|---|---|---|
| account_id | string | Ordering account UUID (same as player_id) |
| name | string | Ordering account name |
| account_external_id | string | Ordering account ID (merchant-side player ID) |
| 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 |
| order_id | string | Parent order ID |
| trade_id | string | Trade ID, unique |
| side | string | Side yes / no |
| action | string | Action buy / sell |
| role | string | Role maker / taker |
| price_cents | string | Trade price (cents / share, 0.01–99.99) |
| max_price_ticks | integer | Price tick base (for price conversion) |
| matched_qty_units | string | Quantity matched in this trade (in 1/100 shares) |
| remaining_qty_units | string | Remaining quantity of the parent order after this trade (in 1/100 shares) |
| currency | string | Player currency |
| mid_rate | string | Exchange rate snapshot (for display) |
| commission | string | Commission (USD); 0 for a losing sell, empty string for buy fills |
| commission_local | string | Commission (player currency) |
| commission_rate | string | Commission rate snapshot |
| fee | string | Trade fee (USD), see formula; charged on both buys and sells |
| fee_local | string | Trade fee (player currency) |
| fee_rate | string | Fee rate actually applied; for BUY, the lower of the current rate and the cap snapshotted at order time |
| status | string | Trade status pending / accepted / rejected |
| reject_reason | string | Rejection reason; only set when status = rejected |
| ex_seq | string | Matching engine global sequence number |
| ex_market_id | string | Matching engine market ID (for reconciliation) |
| ex_market_seq | string | Matching engine per-market sequence number |
| ex_tx_id | string | Matching engine transaction ID |
| ex_order_id | string | Matching engine order ID (for reconciliation) |
| product_id | string | 1 = in-play, 3 = pre-match |
| trade_time | string | Matching time (RFC3339 UTC) |
| created_at | string | Platform write time (RFC3339 UTC) |
| changed_at | string | Last change time of the trade (RFC3339 UTC, up to 9 fractional-second digits); never decreases for a given trade, 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) |
| 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 |
| match_status | string | Match status code |
| event_status | string | Event status (e.g. not_started, live, ended) |
| client_ip | string | Client IP at order time (from the parent order) |
| device_type | string | Device type (from the parent order) |
| device_id | string | Device identifier (from the parent order) |
| order_time | string | Parent order time (RFC3339 UTC) |
| order_status | string | Parent order status (PREDICTION_ORDER_STATUS_*, see 3.7 Order Status) |
TIP
changed_at is the time the platform's data changed. It is not the matching time, so do not use it as a business time. This API does not return counterparty information.
Units
| Field | Unit |
|---|---|
| matched_qty_units, remaining_qty_units | 1/100 share, e.g. 1000 = 10 shares |
| price_cents | Cents / share, 0.01–99.99 |
| Large integers (quantities, engine IDs) | Returned as strings to avoid JavaScript precision loss |
Trade Fee fee
fee = shares × fee_rate × p × (1 − p)
p is the trade price (USD / share, i.e. price_cents ÷ 100).
Sorting and Pagination
items[]is sorted bychanged_atfrom oldest to newest, then bytrade_idwhenchanged_atis equal.- Omit
cursorfor the first page. Whilehas_moreistrue, passnext_cursorto fetch the next page, untilhas_moreisfalse. - If a trade changes again while you are paging, it moves further back and appears once more; the other trades 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
trade_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 a trade 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
trade_idon the merchant side to stay idempotent. - Occasional bulk changes. When the platform re-syncs data, a large number of trades 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.