# Balances and holders

> An account's token balances, and a token's largest holders, fetched once or kept live.

This page is part of the Intear API docs. The Intear API is at `https://api.intea.rs` and `wss://api.intea.rs/ws`, with no API key. https://docs.intear.tech/api/llms-full.txt has all of its pages in one file, and https://docs.intear.tech/llms.txt lists every page of the Intear docs.

## An account's balances

[`balances.get`](https://docs.intear.tech/api/reference/balances.md#balancesget) 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`).

```json
{ "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. `native` reports it for an account that doesn't exist too.

## Live balances

[`balances.subscribe`](https://docs.intear.tech/api/reference/balances.md#balancessubscribe) follows `direct` and `native` balances. Each push has every balance a block changed, including NEAR spent on gas and refunded:

```json
{ "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](https://docs.intear.tech/api/guides/live-token-lists.md#reading-pushes), and `token_min_change` sets [thresholds](https://docs.intear.tech/api/guides/live-token-lists.md#fewer-updates) for them.

- Rhea deposits aren't followed live, and the reply says so with `"not_live": ["rhea"]`.
- A balance subscription ends with `too_far_behind` if the client falls behind. Subscribe again for the current balances.

## A token's holders

[`holders.get`](https://docs.intear.tech/api/reference/holders.md#holdersget) pages through a token's holders, largest balance first, with `total`, the number of holders. [`holders.subscribe`](https://docs.intear.tech/api/reference/holders.md#holderssubscribe) follows the top holders:

```json
{ "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.