useBetsSummary
The useBetsSummary hook is used to fetch bets summary information for user’s address. It returns the wallet’s
betting totals on one chain, summed over every pool and affiliate row the subgraph keeps for it (or only the
given affiliates).
The query needs a bets subgraph that serves the freebet fields of Bettor. Polygon, Base, Polygon Amoy and
Base Sepolia serve them. On a chain whose bets subgraph does not serve them yet - at the time of this
release Gnosis, Chiliz, Chiliz Spicy, BSC and BSC Testnet - the query fails with a validation error and the hook returns
an error. useBets still works on those chains.
Hook represents a logic wrapper over TanStack Query’s useQuery hook. Explore TanStack Query docs to understand what data the hook returns.
Usage
import { useBetsSummary } from '@azuro-org/sdk'
const { data, isFetching, error } = useBetsSummary({
account: '0x...'
})
const { toPayout, inBets, totalPayout, totalProfit, betsCount, withdrawable, freebet } = data || {}
const { betsCount: freebetsCount, toPayout: freebetToPayout } = freebet || {}Props
{
account: string // user's address
chainId?: ChainId
affiliates?: string[] // array of affiliate addresses that will be included in data
query?: QueryParameter<BettorsQuery['bettors']>
}type ChainId =
| 100 // Gnosis
| 137 // Polygon
| 80002 // Polygon Amoy
| 88888 // Chiliz
| 88882 // Chiliz Spicy
| 8453 // Base
| 84532 // Base Sepolia
| 97 // BSC Testnet
| 56 // BSC
type BettorsQuery = {
__typename?: 'Query'
bettors: Array<{
__typename?: 'Bettor'
id: string
affiliate: string
rawToPayout: string
rawInBets: string
rawTotalPayout: string
rawTotalProfit: string
betsCount: number
wonBetsCount: number
lostBetsCount: number
canceledBetsCount: number
cashedOutBetsCount: number
freebetBetsCount: number
freebetWonBetsCount: number
freebetLostBetsCount: number
freebetCanceledBetsCount: number
rawFreebetTurnover: string
rawFreebetInBets: string
rawFreebetToPayout: string
rawFreebetTotalPayout: string
}>
}Return Value
UseQueryResult<BetsSummary>import { type UseQueryResult } from '@tanstack/react-query'
import { type BetsSummary } from '@azuro-org/sdk'
/**
* A wallet's betting totals on one chain, as the bets subgraph keeps them. Amounts are formatted with
* the chain's bet token decimals.
*
* The top-level figures cover bets placed with the wallet's own funds; freebets are counted only in
* `freebet`, whose payouts are the bettor's share.
* */
type BetsSummary = {
/** payouts and refunds of settled bets that are not yet redeemed */
toPayout: string
/** stakes of bets that are not settled yet */
inBets: string
totalPayout: string
totalProfit: string
betsCount: number
wonBetsCount: number
lostBetsCount: number
canceledBetsCount: number
cashedOutBetsCount: number
/** what the wallet can redeem now: `toPayout` plus `freebet.toPayout` */
withdrawable: string
freebet: {
betsCount: number
wonBetsCount: number
lostBetsCount: number
canceledBetsCount: number
/** stakes of every freebet placed */
turnover: string
/** stakes of freebets that are not settled yet */
inBets: string
/** the bettor's share of settled freebets that are not yet redeemed */
toPayout: string
/** the bettor's share of what redeemed freebets paid out */
totalPayout: string
}
}New in SDK v8.2.0: canceledBetsCount, cashedOutBetsCount, withdrawable and freebet, and the behaviours
described below. Existing fields keep their names.
Own funds and freebets
The top-level figures (betsCount, inBets, toPayout, totalPayout, totalProfit and the won, lost and
canceled counts) cover the wallet’s own funds only. A freebet is counted only in freebet, and its payouts
(freebet.toPayout, freebet.totalPayout) are the bettor’s share, never the pool’s whole payout.
betsCount does not include freebets, so a check of whether the wallet has ever bet should test
betsCount + freebet.betsCount. A wallet that only placed freebets has betsCount of 0. toPayout includes the refunds of canceled bets.
withdrawable
withdrawable is toPayout plus freebet.toPayout: what the wallet can redeem now. For example, 2.00 waiting
from a won real-money bet plus a won returnable freebet of 1.00 at 1.50 gives toPayout 2.00,
freebet.toPayout 0.50 and withdrawable 2.50.
Cash-outs
A cash-out raises cashedOutBetsCount by one and lowers inBets by the stake. betsCount stays the same, a
cashed-out bet is still a bet.
Staying current
The hook has no polling interval, and its staleTime is 5 seconds with no refetch on window focus. It is kept
current after the wallet’s own actions:
-
Redeem or cash-out through the SDK (
useRedeemBet,useCashout): every cached summary of the account is patched at once, on the row of that bet’s pool and affiliate only, by the amount the subgraph will record:- a real-money redeem lowers
toPayoutby the bet’s payout, or by its stake when it was canceled; - a freebet redeem lowers
freebet.toPayoutby the bettor’s share; - a cash-out lowers
inBetsby the stake and raisescashedOutBetsCountby one.
No figure goes below zero. The summary is then re-read from the subgraph about 5 and 15 seconds later to confirm. The patch takes the bet’s figures from a cached
useBetslist: a summary with no row for the bet, or every summary when the bet is in no cached list, is re-read immediately instead. - a real-money redeem lowers
-
A new bet through
useBet: the summary is re-read about 0, 4, 10 and 25 seconds after the transaction receipt, so the bet appears once the subgraph has recorded it, without a reload.
Formatting
Amounts are summed in the token’s base units and then formatted with the bet token decimals of the hook’s
chain: chainId when given, otherwise the app’s current chain, whose switch the formatting follows while the
hook stays mounted.