Historical balances and top holders
Liquid balances
Section titled “Liquid balances”get_balance reads one coin type, SUI by default, for an address or object.
The total balance includes coin_balance held as Coin<T> objects and
address_balance held without coin objects. A wallet with no coin objects
can still hold funds. For an object, only its defining module can withdraw
its address balance.
Staked SUI and DeFi position value are excluded. Use get_staking_summary
and get_defi_positions before concluding that an address holds little;
get_wallet_overview reads all its coins together.
Balance at a past moment
Section titled “Balance at a past moment”get_balance takes at (ISO 8601) or at_checkpoint. GraphQL reads a
balance directly only inside its consistent range, about the last hour
(method: consistent_read). An older point is reconstructed
(method: reconstructed): the balance at a recent anchor checkpoint, minus
the owner’s balance changes in that coin in every transaction after the
requested checkpoint up to the anchor. Balance changes include address-balance
deposits and withdrawals, so the result is exact when complete is true.
{"owner":"0x01229b3cc8469779d42d59cfc18141e4b13566b581787bf16eb5d61058c1c724","at":"2025-09-07T16:00:00Z"}"method": "reconstructed", "at_checkpoint": 187414630, …, "complete": true,"balance": "78654856875", "balance_formatted": "78.654856875 SUI","transactions_scanned": …, "anchor": { "checkpoint": …, … }The anchor and transactions_scanned depend on when the call runs; the
balance at the requested checkpoint does not.
The scan reads at most max_transactions transactions; its default and range
are in the tool reference.
When that runs out, complete is false, balance is null, and
reached_checkpoint is the oldest checkpoint the scan got back to: every
transaction after it was read. A reconstructed balance has no coin/address
split, so coin_balance and address_balance are null and anchor carries
the split at the anchor.
at_checkpoint asks for the balance at the end of that checkpoint.
An ISO at selects the last checkpoint stamped at or before that time;
the two arguments are mutually exclusive. Reconstruction uses one request
per page of 50 transactions. max_transactions does not apply to a current
balance or a direct read within the consistent range.
Staking at a past moment
Section titled “Staking at a past moment”get_staking_summary takes as_of, an ISO 8601 date or checkpoint string:
{"address":"0x…","as_of":"2025-06-01T00:00:00Z"}The result describes StakedSui objects directly held by the address at the
end of that checkpoint. A date selects the last checkpoint at or before it,
not the nearest checkpoint. total_staked_mist is their principal, excluding
rewards. Transferred stakes count for their holder, and split/joined positions
use their historical object versions. Wrapped or object-owned stakes,
FungibleStakedSui and liquid-staking tokens are outside this total. An empty
set says nothing about those excluded holdings.
Single-address consensus ownership counts as direct ownership.
For a current position walk, position_cursor resumes at a position block.
Add the position counts from each block; wallet-wide totals stay null until
the walk completes. A stopped get_wallet_overview coin-balance walk resumes
from its last cursor rather than starting its balance pages again.
method: checkpoint_objects reads the owned set at that checkpoint when the
provider retains it. Outside that range, reconstructed_object_changes
replays every transaction affecting the address, including incoming objects:
direction: reversestarts with an owned set atanchor_checkpointand reverses changes after the requested checkpoint through that anchor.direction: forwardstarts empty and applies changes from genesis through the requested checkpoint. Genesis is included when it affects the address.
The first call chooses a direction from the address’s first and latest
transaction checkpoints, then tries the other if the first cannot finish.
Each direction has its own max_transactions budget, which also bounds
object-change pages, and a 45-second replay budget. Every nested page must
finish. Missing history, discontinuous ownership, ambiguous wrapped/unwrapped
states or a budget stop give complete: false and null totals, never an
intermediate set labelled as historical holdings.
Objects created already wrapped are skipped only when a gRPC effects read
proves they never existed at top level; other missing states remain incomplete.
When effects v1 omit an input holder, the tool reads that exact object version.
A time, transaction or object-change-page stop returns continue_with, a
complete get_staking_summary call with an opaque continuation argument.
Call it unchanged to resume the selected direction with the same target and
anchor, not to start again. The saved state carries the held object IDs,
versions, principal, pool IDs and activation epochs, plus the transaction
cursor, offset within its page and any unfinished object-change cursor.
Already-applied changes are not applied twice. max_transactions can change
between calls; increasing it is not required to pass a time stop.
replay_calls counts the initial call and its resumes. attempts describes
this call; replay_transactions_scanned and replay_object_change_pages count
work across the selected replay. Totals and the historical position list remain
unavailable until it finishes.
continuation_storage explains where the state lives:
argument: authenticated, encrypted state travels in the argument when the encoded token fits within 1 KiB withSUI_STORE_PATHconfigured, or 8 KiB without a configured store. This avoids requiring a database for small held sets while keeping arguments smaller when storage is available. It needs the same server session.local_store: state above the applicable inline limit is encrypted in the result store atSUI_STORE_PATH, and the argument is a short capability for that saved state. It survives a server restart with the same store. With no writable store,continuation_unavailableexplains how to enable one before starting the replay again; a configured but unwritable store does not raise the inline limit to 8 KiB.
Both forms expire after 24 hours. Keep address, as_of and network
unchanged. Altered tokens, another network, expired tokens, missing stored
state and replay ranges the provider no longer retains are rejected rather
than restarting against different data. A resumed reverse replay uses its
saved owned set even after the anchor leaves the recent ownership range;
an unfinished anchor enumeration still needs that range.
detail: full returns all positions from a completed read. Display caps leave
totals intact and give a saved-result page or full call for omitted rows.
Saved-result arguments redact the incoming continuation, and the full-call
link omits it. Read the saved-result pages to avoid replaying; the full-call
fallback starts a fresh replay without exposing the previous capability.
estimated_reward_mist is separate. Each position’s principal converts to
pool tokens at its activation-epoch exchange rate, then back to SUI at the
requested checkpoint’s epoch, with integer rounding. Inactive pools stop at
their deactivation epoch. Missing rates leave rewards null without discarding
known principal. The estimate excludes a withdrawal-time cap from the pool’s
remaining reward balance; it never substitutes today’s rate.
Why events alone do not establish holdings
Section titled “Why events alone do not establish holdings”0x3::validator::StakingRequestEvent records the requester in staker_address;
UnstakingRequestEvent records the withdrawer. Subtracting their principal
amounts by that field measures requests and withdrawals attributed to an
address. It does not track transfer recipients, splits, joins, genesis stakes
or conversion to fungible stake. A later holder can withdraw another
address’s original stake, so this event net can even be negative.
GraphQL’s availableRange reports separate retention for owned-object sets,
point object history and transaction/event lists. The tool returns these
ranges rather than assuming that historical object reads imply historical
owner enumeration. gRPC and its archive read known object IDs and versions;
they do not enumerate an address’s holdings at an old checkpoint. GraphQL
resolves the historical versions needed by this reconstruction. Event-list
retention and the absence of a staker_address field filter also prevent an
unqualified event-only fallback.
See GraphQL scope and retention and the validator event definitions.
Top holders
Section titled “Top holders”get_top_holders returns a ranking only when complete_ranking is true. It
walks Coin<T> objects and address balances (funds credited to an owner’s
address without coin objects). Both walks use object-id order, which is
unrelated to balance. A scan that stops early reports the largest holders
found in that sample; raising max_scan can change them.
A truncated scan therefore returns sampled_holders, without a rank or a
percentage of supply, along with a caveat naming which walk stopped. Raise
max_scan (applied to each walk) until truncated is false to get a real
ranking; that is only practical for coins with few enough objects to
enumerate. A scan also stops when it runs out of time, marked
time_budget_reached, and the caveat reports how far the scan got and whether
a retry or a smaller max_scan would help.
In a sample, each holder’s balance is read directly for that address, since
the walk saw only some of its coins, and balance_in_sample is the walk’s own
sum. Each holder carries coin_balance and address_balance beside the
total, and owner_kind, because an address balance can belong to an object
such as a bridge’s liquidity bank. analyze_token reports the same
distinction.
Without mode, a type the chain knows as a coin is scanned as a token: one
with a Coin<T> object, an address balance, coin metadata or a coin registry
entry. Anything else is scanned as an NFT collection.
For NFT collections, holder_kind says how each holder was found; see
Kiosk-held NFTs.
Objects by Move type
Section titled “Objects by Move type”list_objects_by_type scans current top-level objects of a Move struct or
module across all owners. An object wrapped inside another object’s fields is
not indexed by type and is not listed. For an illustrative Bid<SUI> whose
offer field is a Balance<SUI>, count funded bids and sum their offers:
{"type":"0xabc::bidding::Bid<0x2::sui::SUI>","sum_fields":["offer"],"where":{"field":"offer","gt":"0"}}An illustrative completed scan with two funded bids includes:
{"scanned":3,"matched":2,"complete":true,"sums":{"offer":{"total":"1000000000","min":"300000000","max":"700000000","count":2,"unreadable":0,"coin_type":"0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI","formatted_total":"1","decimals":9,"decimals_source":"registry"}},"owner_kinds":{"shared":2,"address":0,"object":0,"consensus":0,"immutable":0,"unknown":0}}scanned counts every object read and matched counts bids passing where.
owner_kinds counts owners of matched rows. Sums cover all matching rows,
including rows the display cap leaves under omitted. Amounts are raw
integers; formatted_total applies the coin’s decimals and
decimals_source says where they came from. For a nested field use a path
such as state.offer; balance.value and balance read the same
Balance<T>. sum_fields accepts at most eight paths, and where.gt
is a nonnegative raw integer, defaulting to "0".
A total is given only when every amount is in one unit. A field the struct
layout shows to be a Balance<T> or Supply<T> is counted in coin T, so
objects of different types holding the same coin add up. Any other field is
counted per concrete object type. When the scanned objects hold the field in
more than one unit, total, min and max are null and sum_units lists
each unit:
{"sums":{"offer":{"total":null,"min":null,"max":null,"count":3,"unreadable":0,"unit_count":2}}, "sum_units":[ {"field":"offer","coin_type":"0xc0…::coins::A","count":2,"raw_total":"150","min":"50","max":"100","formatted_total":"1.5","decimals":2,"decimals_source":"coin_metadata"}, {"field":"offer","coin_type":"0xc0…::coins::B","count":1,"raw_total":"7000000","min":"7000000","max":"7000000","formatted_total":"7","decimals":6,"decimals_source":"coin_metadata"}]}A value that cannot be read as an integer leaves total null, with
observed_total (a lower bound when one unit was identified) and
unreadable saying what was read. An object whose struct has no field at
the path is counted under absent; when no matched object has it,
field_note lists the first object’s fields. where_unreadable and
where_absent count objects the where test could not be applied to;
matched_complete: false identifies an unreadable test, so matched is
only a lower bound. When a struct’s coin layout is not read, its amounts are
counted per object type, and layout_note says how many struct definitions
that affected; an unavailable decimal scale leaves amounts raw under
scale_unavailable.
The type is rewritten to the package version that defined each struct, type arguments included, since that is the id an object’s type carries. A module, struct or type argument the package does not define is refused with the closest names:
{"error":"Package 0x…0002 defines no struct in a module named SUI, so no object can have this type. Modules that define structs, closest first: sui, bag, bcs, coin, …"}The scan walks by type and object ID, not by value. It scans up to 10,000
objects by default (max_scan can raise this to 50,000) and checks a
45-second time budget between pages. complete: false means the sums and
counts cover only the scanned portion. stop_reason says why the walk
stopped: max_scan, time_budget or missing_or_repeated_cursor. A walk
that reached the end of a module filter with other defining versions left
reports other_defining_packages there.
next_call resumes at the next cursor with separate, noncumulative totals
when a cursor is available. Use detail: "full" to retrieve omitted rows.
A full view too large for one response continues with row_offset, which
scans current state again from the same cursor, so rows can move between
pages if objects changed. A module filter can span types introduced by
different package versions; other_defining_packages lists the versions
this scan did not cover.
DeFi positions
Section titled “DeFi positions”get_defi_positions values staked SUI with accrued rewards, liquid-staking
coins at their issuer’s exchange rate, CLMM and AMM liquidity, lending, and
balances inside owned objects such as vaults, coin tables and wrapped
positions.
Each position has asset legs, its valuation method, evidence tier and
usd. If any leg has no price, usd is null and unpriced_reason explains
why. total_usd and by_protocol sum every priced position, not the missing
ones. coverage compares supported positions with the wallet’s owned objects
and lists unrecognised types and counts; unread records failed reads.
Lending health includes the protocol’s borrow_limit_used and
liquidation_threshold_used. When those figures differ from the legs’ USD by
more than 2%, health_basis explains the difference. leads flags positions
near their borrow limit and shared vaults the wallet operates, including what
they hold.
The default summary keeps the most valuable positions within a display budget
and every unpriced position. omitted reports the rest.
detail: "full" returns every position.
get_wallet_overview with include_prices: true values the same positions
beside the wallet’s coins and totals each group apart. Adding
include_nfts: true walks every object and kiosk item the wallet holds and
reads each collection’s market, so a wallet holding many objects costs many
requests. The NFT estimates stay out of the total.