Skip to content

3.7 Order Details API ​

Prediction

IMPORTANT

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

http
GET /api/v1/prediction/report/orders

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

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

json
{
  "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..."
  }
}
FieldTypeDescription
itemsarrayOrders 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
order_idstringOrder ID, unique
idempotency_keystringOrder idempotency key
player_idstringPlatform-internal player UUID
player_external_idstringPlayer ID (merchant side)
player_namestringPlayer name
agent_idstringPlatform-internal agent UUID
agent_namestringAgent name
sport_id / sport_namestringSport ID / name
tournament_id / tournament_namestringTournament ID / name
event_id / event_namestringEvent ID / name
event_start_timestringEvent start time (RFC3339 UTC)
market_id / market_namestringMarket ID / name
specifiersstringMarket specifiers; empty string for markets without specifiers
outcome_id / outcome_namestringOutcome ID / name
home_competitor_id / away_competitor_idstringHome / away team ID
home_competitor / away_competitorstringHome / away team name
home_score / away_scorestringHome / away score at order time
period_home_score / period_away_scorestringCurrent period / half score at order time
event_statusstringEvent status (e.g. not_started, live, ended)
match_statusstringMatch status code
sidestringSide (PREDICTION_SIDE_*)
actionstringAction (PREDICTION_ACTION_*)
limit_price_centsstringLimit price (cents / share, 0.01–99.99)
max_price_ticksintegerPrice tick base (for price conversion)
qty_unitsstringOrder quantity (in 1/100 shares)
filled_unitsstringFilled quantity (in 1/100 shares); unfilled = qty_units − filled_units
persistencestringOrder persistence policy (e.g. Lapse)
runner_idstringMatching engine runner ID
currencystringPlayer currency
mid_ratestringExchange rate at order time
deducted_amountstringAmount actually deducted (player currency), including fee_reserve
usd_deducted_amountstringAmount actually deducted (USD), including usd_fee_reserve
truncation_lossstringDifference caused by decimal truncation (player currency)
usd_truncation_lossstringDifference caused by decimal truncation (USD)
fee_reservestringFee reserve (player currency), converted at this order's deduction ratio; 0 for SELL
usd_fee_reservestringFee reserve upper bound (USD), see formula; 0 for SELL
statusstringOrder status (PREDICTION_ORDER_STATUS_*)
cancel_causestringCancellation reason code
cause_detailstringCancellation reason details
release_atstringDelayed-submission release time (RFC3339 UTC); only set when status = HELD
order_timestringOrder time (RFC3339 UTC)
updated_atstringLast updated time (RFC3339 UTC)
changed_atstringLast 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_ipstringClient IP at order time
device_typestringDevice type
device_idstringDevice identifier
ex_market_idstringMatching engine market ID (for reconciliation)
ex_order_idstringMatching engine order ID (for reconciliation)
engine_flippedbooleanWhether the matching engine has converted this order to its equivalent on the opposite side (YES / NO equivalence)
urlstringOrder 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 ​

FieldUnit
qty_units, filled_units1/100 share, e.g. 1000 = 10 shares
limit_price_centsCents / 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 by changed_at from oldest to newest, then by order_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 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

  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 order_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 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_id on 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_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.

Orders, Trades and Positions ​

The Prediction query APIs cover three levels:

3.7 Order Details3.8 Trade Details3.9 Position Details
UnitOrderTradePosition
Upsert keyorder_idtrade_idplayer_id + event_id + market_id + specifiers + outcome_id + side
Counts as a changePlacement, fills, cancellation, failed placementTrade written, trade status changeBuys, sells, sell-lock / unlock, settlement, re-settlement, rollback, voiding, payout credited
Use forOrders, deductions, cancellationsMatched prices, fees, commissionSettlement 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_) ​

ValueDescription
YESPredicts the event will happen
NOPredicts the event will not happen

Action (prefix PREDICTION_ACTION_) ​

ValueDescription
BUYBuy, opening a position
SELLSell held shares, closing a position; only SELL realizes PnL

Order Status (prefix PREDICTION_ORDER_STATUS_) ​

ValueDescription
PENDINGOrder placed, awaiting matching engine confirmation
HELDDelayed submission; not sent before release_at
FAILEDOrder failed
OPENConfirmed by the matching engine, resting on the book
PARTIALLY_FILLEDPartially filled
FILLEDFully filled
CANCELLEDCancelled (no fills)
PARTIAL_CANCELLEDCancelled (partially filled)

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