Skip to main content

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.
Filter by 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:

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.
Last modified on August 11, 2026