getBalanceHistory

Time-series of a set of sub-accounts’ settled collateral movements — deposits and withdraws — from the analytics subgraph.


import { getBalanceHistory } from "@symmio/trading-core";
 
const history = await getBalanceHistory(config, {
  accounts: [subAccount],
  first: 50,
});

Parameters

accountsreadonly Address[]required

The sub-accounts whose deposit / withdraw history to read (e.g. the addresses from getUserSubAccounts). The query filters on the movement’s account, so pass every sub-account to cover. An empty array reads nothing.

filterBalanceHistoryFilterdefault All

Movement-type filter: All (deposits and withdraws), Deposit, or Withdraw.

internalTransfersInternalTransfersModedefault exclude

How to treat internal margin-transfer legs (bookkeeping side effects of moving margin between a user’s own SubAccount and a Virtual Account): "exclude" (genuine deposits/withdrawals only), "only", or "include". Orthogonal to filter.

firstnumberdefault 1000

Page size.

skipnumberdefault 0

Page offset.

startTimenumberdefault 0

Lower bound on the movement timestamp (unix seconds).

endTimenumberdefault 2_000_000_000

Upper bound on the movement timestamp (unix seconds).

orderDirection"asc" | "desc"default desc

Sort direction on the movement timestamp.

chainIdnumberoptional

Optional chain override.

Returns

readonly BalanceHistoryRow[]

idstring

Subgraph entity id (use as a stable row key).

typeBalanceChangeType

Movement kind — DEPOSIT, WITHDRAW, or BRIDGE (a bridged withdraw).

amountbigint

Amount, raw bigint in the collateral token’s decimals (not 18) — scale by collateralDecimals (6 on HyperEVM) for display.

accountAddress

The sub-account the movement belongs to.

timestampnumber

Block timestamp, unix seconds.

transactionHex

Transaction hash of the movement.

isInternalTransferboolean

true when this row is an internal margin-transfer leg rather than a real user deposit / withdrawal. Always false under the default internalTransfers: "exclude".

marginTransferTypeMarginTransferType | null

The margin-transfer kind (ADD / REMOVE / AUTO_RETURN) when isInternalTransfer is true; otherwise null.

Query options


import { getBalanceHistoryQueryOptions } from "@symmio/trading-core";
import { useQuery } from "@tanstack/react-query";
 
useQuery(getBalanceHistoryQueryOptions(config, { accounts: [subAccount] }));