Toolkit v7.2 & SDK v8.2: Freebet Share and Recorded Bet Figures

Every figure that values a freebet now shows what the bettor receives: the bettor’s share of the payout, by the freebet contract’s rule. Bet figures are read as the bets subgraph records them, already priced by the protocol’s rule, with no client-side re-pricing. useBetsSummary also gains freebet totals and a withdrawable figure.

What’s New

Toolkit v7.2.0

• calcFreebetBettorShare - new. Returns the share of a freebet’s payout that the bettor receives. Takes CalcFreebetBettorShareParams (payout, amount, isAmountReturnable).
• getBetsReport and calcBetsReport read every bet’s recorded payout with no combo rebuild, read a leg’s void from its selection result alone, and value the freebet line at the bettor’s share with profit = returns.
• BetsReportEntry.isFreebetAmountReturnable is new and optional. BetsReportEntry.createdAt and BetsReportSelection.odds are now optional, deprecated and ignored, so entries built by older callers still type-check. BetsReportEntry.isRedeemed stays required but is deprecated and ignored: a redeemed bet’s rawPayout is already the amount actually paid.
• SINGLE_MARGIN_REMOVED_AT - new constant. calcComboOdds prices a single leg created at or after it at its quoted odds.
• Deprecated, still exported and still working: calcComboOdds and MARGIN_APPLIED_AT (read a bet’s odds / settledOdds and potentialPayout / payout, or rawPotentialPayout / rawPayout, instead of re-pricing its legs), and isSelectionCanceled (read selection.result === SelectionResult.Canceled).
• Fragment additions, none removed: BetFragment gains rawAmount, rawPotentialPayout, rawPayout and core.liquidityPool.tokenDecimals; BettorFragment gains the affiliate, the counts and the freebet totals; BetReportFragment gains isFreebetAmountReturnable; the v3 bets of GameBetsQuery gain isFreebet and isFreebetAmountReturnable.
• SelectionResult now includes Canceled.
• isExtendedConditionId - new. Tells whether a condition is extended from the first digit of its id: 5 or 6. groupConditionsByMarket and getPredefinedCombo use it, so a condition starting with either digit takes the extended path: named by its API titles, never by @azuro-org/dictionaries.

SDK v8.2.0

• useBets reads totalOdds, possibleWin, payout and settledPayout as recorded. A freebet’s money fields are the bettor’s share, and a leg’s won, lost and canceled flags come from its selection result alone. Bets from useLegacyBets keep the v2 figures.
• useRedeemBet also sets a redeemed bet’s payout to null in the cached useBets list as soon as the transaction is confirmed, alongside isRedeemed and isRedeemable, instead of keeping it until the next read.
• useBetsSummary returns the exported BetsSummary type with the new canceledBetsCount, cashedOutBetsCount, withdrawable and freebet block. It sums every pool and affiliate row of the wallet and formats with the decimals of its chain (chainId, or the app’s current chain), also after a chain switch.
• Redeem and cash-out patch the summary at once, on the bet’s own pool and affiliate row, and re-read it about 5 s and 15 s later. A cash-out no longer lowers betsCount. A new bet re-reads the summary about 0, 4, 10 and 25 s after the receipt.
• useBetsReport inherits the toolkit report change.
• useBetsSummaryBySelection values a won freebet at the bettor’s share and a lost freebet at 0.
• useBets names the legs of extended conditions, starting with 5 or 6, from the titles recorded with the bet or, failing those, from the API, never from @azuro-org/dictionaries.

A freebet pays the bettor a share of its payout

The liquidity pool pays a freebet’s whole payout to the freebet contract, which splits it between the bettor and the freebet fund:

• Payout no greater than the stake: the bettor receives nothing and all of it goes back to the fund. A lost freebet pays 0, and a canceled one pays back exactly its stake.
• The freebet’s amount is returnable: the stake goes back to the fund and the bettor receives payout - stake.
• Otherwise (the flag is exactly false): the bettor receives the whole payout.

A freebet whose flag is absent (null or undefined) is valued as returnable. That is the smaller of the two shares, so the app never shows more than the bettor receives.

For a freebet of 1.00 won at 1.50, the pool pays 1.50:

import { parseUnits } from 'viem'
import { calcFreebetBettorShare } from '@azuro-org/toolkit'
 
// a returnable freebet of 1 USDT that won at 1.5: the pool pays 1.5, the bettor receives 0.5
const share = calcFreebetBettorShare({
  payout: parseUnits('1.5', 6), // the bet's payout as the pool records it, token base units
  amount: parseUnits('1', 6), // the freebet's stake, token base units
  isAmountReturnable: true, // null or undefined counts as returnable
})

The math is plain bigint over base units, nothing is rounded.

Bet figures as recorded

useBets no longer re-prices anything on the client. Per state:

• Pending: totalOdds is the odds the bet was placed at, possibleWin is the recorded potential payout, payout and settledPayout are null.
• Won: totalOdds is the settled odds, payout is the recorded payout while the bet is redeemable, settledPayout is the recorded payout and survives redemption.
• Lost: payout is null, settledPayout is 0, and possibleWin keeps the win that was missed.
• Canceled: totalOdds is 1, and possibleWin, settledPayout and, while redeemable, payout are the stake, or 0 for a freebet.
• Cashed out: payout is null. Read cashout for what the cash-out paid.

For a freebet each of these money figures is the bettor’s share. A combo is no longer re-priced on the client, and calcComboOdds is deprecated.

The bettor summary

import { useBetsSummary } from '@azuro-org/sdk'
 
const { data } = useBetsSummary({ account: '0x...' })
const { betsCount, toPayout, withdrawable, freebet } = data ?? {}
 
// freebet.betsCount, freebet.turnover, freebet.inBets, freebet.toPayout, freebet.totalPayout
const hasEverBet = (betsCount ?? 0) + (freebet?.betsCount ?? 0) > 0

withdrawable is what the wallet can redeem now: toPayout plus freebet.toPayout. A won real-money bet waiting for redemption with 2.00 and a won returnable freebet of 1.00 at 1.50 give toPayout 2.00, freebet.toPayout 0.50 and withdrawable 2.50.

• The top-level figures cover the wallet’s own funds, and freebets are counted only in freebet. Its payouts are the bettor’s share.
• A redeem or cash-out made through the SDK updates the summary at once and confirms it from the subgraph about 5 s and 15 s later.
• A new bet appears in the summary without a reload, once the subgraph has recorded it.

See the full documentation.

Learn more

• useBets
• useBetsSummary
• useBetsReport
• getBetsReport
• calcComboOdds
• isExtendedConditionId