The three grains
They nest strictly: one position contains N bets, one bet contains N fills.
Building a portfolio view
Positions. Exposure per market, already netted.
Showing a bet history
Bets. One row per bet the user placed.
Drilling down into fills
Fills. Granular fills for a bet.
Positions
One row per market, netted across all your bets in it — total staked, best case, worst case. The grain for a portfolio view, and the only one that computes PnL for you.status is required here and takes a CSV list. See GET /positions-v3
for every field, the required-status rule, realised PnL, and the counts route.
Bets
One row per bet you placed — everything that came out of one order you submitted, blended. Swept four resting levels? One bet,fillCount: 4. The grain a user recognises, so the right one for a history view.
totalReturn is gross (it includes your stake); page with nextKey. See
GET /trades-v3 for the full row, filters, paging, and settlement fields.
Fills
One row per match against one counterparty. The finest grain, and the only one carrying the price you actually got and the order it came from.tradeId (not id), and read the real per-match price off fillOdds. See
GET /fills-v3 for the row, its four ids, and the sort order.
Realtime equivalents
Each grain has a channel, and they carry the same shapes as the REST rows:Related
Get your bets
The bet row in full and its filters.
Get your fills
The fill row, its four ids, and the sort order.
Get your positions
Every field, the required-status rule, and realised PnL.
Tracking your orders
Keeping a live view of what is resting on the book.