Skip to content

3.8 Trade Details API ​

Prediction

IMPORTANT

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

http
GET /api/v1/prediction/report/trades

Returns 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) ​

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[] (trades), has_more and next_cursor. Amount fields: no _local suffix means USD; the _local suffix means player currency.

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

FieldTypeDescription
itemsarrayTrades 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
account_idstringOrdering account UUID (same as player_id)
namestringOrdering account name
account_external_idstringOrdering account ID (merchant-side player ID)
event_idstringEvent ID
market_idstringMarket ID
specifiersstringMarket specifiers; empty string for markets without specifiers
outcome_idstringOutcome ID
order_idstringParent order ID
trade_idstringTrade ID, unique
sidestringSide yes / no
actionstringAction buy / sell
rolestringRole maker / taker
price_centsstringTrade price (cents / share, 0.01–99.99)
max_price_ticksintegerPrice tick base (for price conversion)
matched_qty_unitsstringQuantity matched in this trade (in 1/100 shares)
remaining_qty_unitsstringRemaining quantity of the parent order after this trade (in 1/100 shares)
currencystringPlayer currency
mid_ratestringExchange rate snapshot (for display)
commissionstringCommission (USD); 0 for a losing sell, empty string for buy fills
commission_localstringCommission (player currency)
commission_ratestringCommission rate snapshot
feestringTrade fee (USD), see formula; charged on both buys and sells
fee_localstringTrade fee (player currency)
fee_ratestringFee rate actually applied; for BUY, the lower of the current rate and the cap snapshotted at order time
statusstringTrade status pending / accepted / rejected
reject_reasonstringRejection reason; only set when status = rejected
ex_seqstringMatching engine global sequence number
ex_market_idstringMatching engine market ID (for reconciliation)
ex_market_seqstringMatching engine per-market sequence number
ex_tx_idstringMatching engine transaction ID
ex_order_idstringMatching engine order ID (for reconciliation)
product_idstring1 = in-play, 3 = pre-match
trade_timestringMatching time (RFC3339 UTC)
created_atstringPlatform write time (RFC3339 UTC)
changed_atstringLast 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_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)
home_score / away_scorestringHome / away score at order time
period_home_score / period_away_scorestringCurrent period / half score at order time
match_statusstringMatch status code
event_statusstringEvent status (e.g. not_started, live, ended)
client_ipstringClient IP at order time (from the parent order)
device_typestringDevice type (from the parent order)
device_idstringDevice identifier (from the parent order)
order_timestringParent order time (RFC3339 UTC)
order_statusstringParent 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 ​

FieldUnit
matched_qty_units, remaining_qty_units1/100 share, e.g. 1000 = 10 shares
price_centsCents / 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 by changed_at from oldest to newest, then by trade_id 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 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

  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 trade_id: 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 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_id on 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_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