Balances and holders

An account’s balances

balances.get returns what an account holds, from any of three sources:

• direct: its own token balances.
• native: its NEAR balance, as token near in yoctoNEAR.
• rhea: its deposits in Rhea (v2.ref-finance.near).

{ "id": 1, "method": "balances.get", "params": { "account": "alice.near", "sources": ["direct", "native"], "token_fields": ["symbol", "decimals", "price_usd"] } }

token_fields brings along fields of each token held, so a wallet view needs one request. Native NEAR gets wrap.near’s fields.

The reply has:

• balances: a table of token, source and balance, in the token’s smallest units.
• tokens: the held tokens’ token_fields, only when token_fields was given.
• unknown: tokens the account holds that this API doesn’t know, without balances.
• errors: sources that couldn’t be read right now, as upstream_unavailable. The other sources’ balances are there all the same.

Live balances

balances.subscribe follows direct and native balances. Each push has every balance a block changed, including NEAR spent on gas and refunded:

{ "sub": 1, "height": 219969300, "timestamp_millis": 1792003525000, "balances": { "wrap.near": "1500000000000000000000000" } }

With token_fields, set carries changes to the held tokens’ fields, like a token subscription, and token_min_change sets thresholds for them.

• Rhea deposits aren’t followed live, and the reply says so with "not_live": ["rhea"].
• A connection can follow up to 100 accounts.
• A balance subscription ends with too_far_behind if the client falls behind, since balance changes can’t be read back. Subscribe again for the current balances.

A token’s holders

holders.get pages through a token’s holders, largest balance first, with total, the number of holders. holders.subscribe follows the top holders (up to 1,000):

{ "sub": 1, "height": 219969300, "timestamp_millis": 1792003525000, "set": { "alice.near": "1200000" }, "left": ["bob.near"] }

set has the new balances in the top, including accounts that came into it, and left the accounts that fell out.

Holders are counted from this project’s indexed balances. An account that has held a token since before indexing started and hasn’t touched it since isn’t counted until its balances are re-checked.