B2B API

Two dimensions, and the badge tells you which

Every endpoint on this page carries one of two badges, and they are not decoration — they are the whole difference between a call that works and a 401 session_required.

Take a session with POST /b2b/v1/auth/session and {"player_id":"…"} in the body — that call is itself merchant dimension, because it is the one that produces a session rather than consuming one. It is also the only place a player id travels in a request: the X-Player-Id header is retired and a request still carrying it is refused with 400 player_id_header_retired across the whole of /b2b/v1. Full rules and the session lifetime are on Authentication.

The eighteen player-dimension endpoints, in full

Listing markets, and paging through them

GET /b2b/v1/markets/list is the lobby feed. It pages by keyset, not by offset: pass the next_cursor you were given back as cursor, and stop when has_more is false. There is deliberately no total — counting matching rows on every page was the single slowest query in the product, and a keyset cursor also cannot skip or repeat a market when the catalogue changes mid-scroll, which an offset can.

Filters (category, subcategory, market_type, timeframe, keyword) are applied server-side and must be resent unchanged with the cursor — and that is advice, not a rule the server enforces: send a cursor from one filter with another filter's query and you get rows, not an error, positioned by a cursor that never belonged to them. limit defaults to 20 and is clamped to 100 — asking for more returns 100 rather than an error, so page on has_more and never on having received fewer rows than you asked for. A zero or negative limit is not an error either: it falls back to the default 20, so a page size computed by arithmetic that reaches zero returns twenty rows rather than none — verified live at 0 and -1. A keyword longer than 64 characters is silently truncated to the first 64 — the request succeeds and the extra characters simply never took part in the match, so a long paste searches for its own prefix and returns more than you asked for. Unknown query parameters are ignored the same way: a misspelt filter name returns the full unfiltered page rather than an error, which reads as "the filter found everything".

A page can also come back shorter than limit while has_more is still true. Markets the upstream has no live price for are filtered out after the page is read, because listing a market you would then be refused a quote on is worse than a short page. Treat has_more as the only end-of-feed signal.

An unusable cursor is not rejected — it silently restarts the feed. The value is parsed permissively and anything that does not parse becomes zero, which means "no cursor". Verified live: abc, -1, 0 and a cursor larger than any row all return the first page, byte for byte the same rows as sending no cursor at all, with has_more true. A client that corrupts or mislays its cursor therefore loops on page one forever and never sees an error. Guard for it on your side: if a page comes back with the same next_cursor you just sent, or with rows you have already seen, stop rather than continue — the feed will not tell you.

Walking the whole catalogue is a normal thing to do and it does not get slower as you go. Measured on the sandbox across 79 consecutive pages of 100: the last page cost the same server time as the first, within the noise of the measurement, which is the property keyset pagination exists for. Budget the walk on page count rather than on depth.

Over a walk that long, expect the occasional transient failure — one of those 79 pages answered 502, and the identical cursor then succeeded five times in a row. This is the one place a keyset cursor is markedly easier to live with than an offset: the retry is the same request with the same cursor and it cannot land you on a shifted window. Retry the page rather than restarting the walk.

# first page
GET /b2b/v1/markets/list?category=crypto&limit=30
→ { "items": [ ... ], "next_cursor": 242817, "has_more": true }

# next page — same filters, cursor echoed back
GET /b2b/v1/markets/list?category=crypto&limit=30&cursor=242817
→ { "items": [ ... ], "has_more": false }        # next_cursor omitted when exhausted

What a row contains

One warning from having got this wrong ourselves, repeatedly. Reading market_type in the obvious place is the easy part; the side wording leaks into more of a client than you would expect. Ours was wrong in five separate ways at once: a hardcoded lookup table, a mapping layer that quietly dropped the field so the correct helper received nothing, a literal side === 1 ? 'YES' : 'NO', the words baked into translated copy, and copy that did interpolate but was never passed the value. Each one rendered YES on a market whose buttons said UP.

What worked was a rule rather than a list: nothing outside one module may name a side, enforced by a scan over the whole tree. Enumerating the files that need fixing only proves the listed ones have not regressed, and the next occurrence appears somewhere nobody listed.

Grouping a market's siblings

Rows in the lobby carry an event_id when they are outcomes of one question — several strikes on the same underlying, or the candidates in one race. Fetching the whole set is a separate call, and it is the one to build a grouped board on.

The response is unbounded — there is no server-side cap on how many outcomes come back, and none is needed at present: across 40 sandbox events the median is 2 and the largest is 16. Size your rendering against the shape of the data rather than a limit you can pass, because there is no limit you can pass.

Three prices, not interchangeable

1. price_yes0.660

   The probability. Render it as 66% — but a bet does not cost this. Reaching for it because it is the one that looks like a percentage is the common mistake.

2. + engine margin and shading (not yours, not adjustable)
   price_base_yes0.684

   The operator's base buy price. The gap from the probability is the engine's own spread, already applied before you see the row. This is the rung to build on — it is the one field that means the same thing everywhere it appears.

3. + margin_add_pct (yours)
   price_base_yes + margin_add_pct/1000.684

   What a buy actually costs, and the number to put in front of a player. Compute it yourself and clamp to [0,1]. Equal to the base on this real row only because that merchant's margin_add_pct is 0 — with a margin set, this rung sits higher.

A row carries the probability and the cost separately, and they differ by your margin. Showing the wrong one understates what a bet costs. Depend on the formula, not on price_buy_*: that field is a convenience for existing integrations and is slated to change calibration or be withdrawn, so new work should read price_base_* with margin_add_pct and apply clamp01(base + pct/100) itself. The identity price_buy_* === clamp01(price_base_* + margin_add_pct/100) holds on every row today — verified live — which is what makes the migration a no-op rather than a change of numbers.

The two buy prices do not sum to one. Buying both sides costs more than the unit they are guaranteed to return between them, and the difference is the engine's spread — it is there whether or not you add a margin. Sampled across twenty live sandbox markets with margin_add_pct at zero, the sum ran from 1.0145 to 1.0480 with a median of 1.0292. Size your own margin knowing that is already in the price, and do not read a sum above one as an arbitrage: it is the house edge, and the same holds on any market maker.

Live prices over a socket

GET /b2b/v1/ws/ticks upgrades to a WebSocket carrying price ticks. It is the answer to “how do I keep a board live without polling”, and it behaves differently enough from a typical market feed that the promises are worth stating before the payload.

• SubscriptionNone — connect and you get everything

  There is no subscribe frame and no per-market filtering. Every active market's ticks arrive on every socket, and anything you send upstream is read and discarded. Filter on your side.

• AuthThe same HMAC as a REST GET — merchant dimension, no session

  Signed before the upgrade, with an empty body in the canonical: ts \n GET \n /b2b/v1/ws/ticks \n \n nonce \n — six fields, so the string ends with that last newline. Ticks name no player, so no Bearer is involved and sending one changes nothing. A failed signature is refused as an HTTP error, so watch the upgrade response, not the socket.

• DeliveryBest-effort, and you can be dropped

  Ticks are display state, so a consumer whose buffer fills is disconnected rather than slowing everyone down. The buffer is 1024 ticks per connection: fall that far behind and the socket is closed on you, with no error frame first. Liveness is a 60-second pong deadline — we answer your pings, and a socket that goes quiet past that is dropped too. Treat a disconnect as normal, reconnect, and re-read prices over REST rather than assuming you have every tick.

• HeartbeatServer pings every 25s; 60s read deadline

  Answer pings — most clients do automatically. A socket that goes quiet for 60s is dead on our side even if your end still shows it open, which is the usual cause of a display that silently stops updating.

• Framemarket_id · price_yes · price_buy_yes · price_buy_no · ts

  Prices as decimal strings, ts as epoch milliseconds. One trap: price_buy_yes/price_buy_no on a tick are the operator BASE prices, without your margin — not the same calibration as the identically-named REST fields, which have it applied. The hub broadcasts one payload to every connection and so structurally cannot reprice per merchant. Add margin_add_pct/100 yourself and clamp, exactly as you should for price_base_* over REST; `tick.price_buy_yes ?? card.price_buy_yes` is the wrong thing to write, and it is invisible on a zero margin.

The socket complements the read-refresh behaviour above rather than replacing it. Reads are what pull a cold market forward; the socket is what keeps an already-warm board moving between reads. A board built on both — REST on open, socket thereafter, REST again on reconnect — needs no polling at all.

A suspended side is not visible until you hit it

Suspension is per side: YES can be closed while NO still trades. The flags that carry it, is_suspended_yes and is_suspended_no, are on the operator and merchant views and are deliberately absent from the market payload you receive — the C-end contract does not carry internal risk signals. There is no field to check, and no combination of fields that implies it.

The practical consequence is that you learn about it from the refusal, not before it. A quote or an order on a suspended side answers market_locked, and the same code also covers past-close, a market with no anchored price, and a stale feed, so the response alone will not tell you which of the four you hit. Design for that: keep both sides selectable in your UI, let the refusal be the thing that closes one off, and word the message so it reads as temporary rather than as an error the player caused. It usually is temporary — a suspension is lifted by the operator, unlike past-close, which never clears.

Market stats, and which of them are real

GET /b2b/v1/markets/{marketId}/stats returns a 24-hour summary. It is worth reading this section before you use any of it, because the fields do not share a provenance and nothing in their names says so.

• position_countreal only

  Open positions. Always real — synthesised activity holds no positions, so nothing can inflate this.

• open_price · high_24h · low_24hreal + synthesised

  Taken from trade rows, real and synthesised together, over the same 24h window. Zero means the window holds no trades of either kind, not that the price was zero.

• volume_24h · turnover · participant_countsynthesised

  A synthesised component is added to the real figure. It is computed analytically from a market-heat function, not counted from rows, so it moves smoothly and is not a trade count.

The synthesised rows exist to give a new market a plausible public surface, and they are marked is_isolated at rest so they can never reach reconciliation or settlement. Your ledger and ours agree regardless of what this endpoint reports. The line to hold is simply that these are presentation figures: do not drive risk limits, liquidity decisions or your own reporting from them, and do not reconcile against them. Everything you actually need for that lives in /orders, /positions and /settlements, which are real throughout.

Two behaviours follow from how the rows are produced. They are generated when a market is first opened, so a market nobody has looked at yet returns zero for the three price fields and fills in shortly after the first visit — a fresh market answering 0 is not an error. And the whole blend is gated: with the ambient engine, the compliance switch, your merchant setting or your jurisdiction turned off, every field above falls back to real-only and the same market reports far smaller numbers. Neither transition means anything changed about the market itself.

Positions and closing early

Placing an order is half the lifecycle. These three complete it. Closing is two calls: quote first, then submit. The quote does not lock the price — the close is repriced inside the transaction that executes it, exactly as a buy is. What protects the player is min_proceeds: pass the floor they agreed to and a close that would pay less is refused, which is the mirror of max_price on a buy. Omitting it is not a neutral default — it turns the protection off.

quote_id is required on submit — without it you get 400 bad_request, verified live. Its job is idempotency, not price: the key is cashout-<quote_id>, so submitting the same quote twice replays the first result rather than closing again. Take a fresh quote for every submit, or a player closing a position in two halves will find the second call quietly returning the first half's numbers.

One name to watch: POST /b2b/v1/positions/close is an alias of the quote endpoint, not the close. It returns a quote and moves nothing. The call that actually closes is /cashout/submit.

Limit orders

Two things here differ from an exchange and will bite if assumed away. A limit buy debits the wallet the moment it is placed, not when it fills — the seamless wallet model has no freeze primitive, so resting an order costs the money up front, and a cancel or expiry returns it as a refund. And your limit_price is a bound, not the traded price: the fill executes at the execution-average price at match time, and the limit only gates it — a buy never pays above it and a sell never receives below it, so a buy that fills usually fills a little better than the reservation, and the difference between what was reserved and what the fill cost comes back as a second ledger entry (lofillrefund-<id>). Reconciliation has to expect that second entry. Fills are also all-or-nothing — there are no partial fills in the current version, so an order is entirely unfilled until the moment it is entirely filled.

Settlements and the ledger

The last two reads close the loop. Both are GETs signed with an empty body.

This endpoint reflects the operator-side ledger only. Under the zero-custody rule the operator neither holds nor moves your players' funds: with a self-hosted wallet every debit and credit happens in your ledger via the hooks, so nothing is written here and the endpoint returns an empty list forever — verified on a live merchant whose hook is enabled. It is populated in the hosted-wallet model, where the reference backend holds the wallet. Reconcile against your own ledger, not this one, unless you are hosted.

Response envelopes

The read endpoints do not share one list shape. A generic list handler written against any single one of them will break on the others, so check this table before writing the first parser. Every shape below was read off the live API rather than inferred.

Three kinds of pagination coexist here. The lobby uses a keyset cursor because it scans a large catalogue. /orders and /orders/limit use conventional limit/offset. The remaining three per-player reads do not paginate at all.

GET /orders reads limit (1..200, default 100 — echoed back in the envelope), offset (non-negative) and status (the integer states 1..4, not a name). Invalid values are an explicit 400 rather than a silent fallback — limit=abc or status=open refuses instead of handing you 100 rows you did not ask for. It also does exact lookup: ?idem_key= (checked first) or ?order_id= returns that one order as a one-row list, and a miss is an empty list with total: 0, never a 404 — "not found" and "not booked yet" call for the same handling on your side. The idem_key lookup is the recovery path for an undecided order: when a placement answers order_status: 2, poll GET /orders?idem_key=<your key> until the order reaches 3 or 4 instead of re-sending the placement.

The three remaining per-player reads — /wallet/transactions, /settlements, /settlements/views — read no pagination parameter at all. They return the most recent 100 rows. Sending limit=2, offset=1 or page=2 returns a byte-identical response, verified against the live API. Their limit field is the constant 100 — not what you asked for, and not the number of rows you got.

This matters for one field. On the lobby, has_more: true means call again with the cursor. On /orders it is offset-aware (offset + rows returned < total), so a "load more" control wired to it works. On the three fixed-window reads it means there are older rows and this endpoint cannot reach them — it is total > rows returned, nothing more. A "load more" control wired to one of those will call the same URL and render the same 100 rows forever. Once a player passes 100 records there, treat the older history as unavailable and reconcile from your own ledger — or, for orders specifically, page through /orders with offset.