> For AI agents: the documentation index is at https://sdk.nimbusprivacy.xyz/llms.txt, and every page is available as Markdown at its URL with .md appended.

# Balances, history and sync (/reference/reads)

The private balance and its history live on the user's device. A sync brings them up to date, and
the reads return what it left. [Balances](https://sdk.nimbusprivacy.xyz/helpers/balances), [History](https://sdk.nimbusprivacy.xyz/helpers/history) and
[Sync](https://sdk.nimbusprivacy.xyz/helpers/sync) walk through each.

## readBalances

Use it whenever you show the private balance. It is cheap enough to call after every sync.

```ts
function readBalances(
  session: NimbusSession,
  _args?: Readonly<Record<string, never>>,
  options?: { readonly zone?: number },
): Promise<readonly Balance[]>;
```

Reads the session's balances in one zone from its note store: one entry per mint and state, in
the order of the mints' identifiers.

Reads only what [`syncNoteStore`](https://sdk.nimbusprivacy.xyz/reference/reads#syncnotestore) has synced; nothing is fetched. A session whose
store holds nothing yet reads as no balances.

**Parameters**

| Parameter  | Type                                                                                                                    | Description                                              |
| ---------- | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
| `session`  | `NimbusSession`                                                                                                         | The opened session.                                      |
| `_args?`   | `Readonly<Record<string, never>>`                                                                                       | Unused; kept so every function takes the same arguments. |
| `options?` | `{ /** The zone, below 2^20; 0 when omitted. A zone no note carries reads as no balances. */ readonly zone?: number; }` | The zone, below 2^20; 0 when omitted.                    |

**Returns**

`Promise<readonly Balance[]>`

The balances.

**Throws**

[`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"unreadable"` when the store was replaced while it was
read or cannot be read back; `"unsupported-browser"` when the browser refuses it.

**Example**

```ts
import { readBalances } from "@umbra/nimbus-solana-web";
import type { NimbusSession } from "@umbra/nimbus-solana-web";

declare const session: NimbusSession;
const balances = await readBalances(session, {});
const available = balances.filter((balance) => balance.state === "available");
```

Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/reads.ts`.

## readHistory

Use it to show the user's past payments, one page at a time.

```ts
function readHistory(
  session: NimbusSession,
  _args?: Readonly<Record<string, never>>,
  options?: { readonly limit?: number; readonly after?: HistoryPosition },
): Promise<HistoryPage>;
```

Reads one page of the session's history from its note store, newest first: each transaction with
the identity's notes it created and spent, and its record when it is the session's.

Reads only what [`syncNoteStore`](https://sdk.nimbusprivacy.xyz/reference/reads#syncnotestore) has synced; nothing is fetched. A page's
`coverage` names, per pool, the slot its history is complete through: nothing above it is shown
as nothing having happened. A session whose store holds nothing yet reads as an empty page.

**Parameters**

| Parameter  | Type                                                                                                                                                                                                                 | Description                                                                                                                         |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `session`  | `NimbusSession`                                                                                                                                                                                                      | The opened session.                                                                                                                 |
| `_args?`   | `Readonly<Record<string, never>>`                                                                                                                                                                                    | Unused; kept so every function takes the same arguments.                                                                            |
| `options?` | ``{ /** The most transactions the page holds, 1 to 100; 20 when omitted. */ readonly limit?: number; /** The previous page's `next.position`; from the newest when omitted. */ readonly after?: HistoryPosition; }`` | The page size, 1 to 100, 20 when omitted; and `after`, the position the previous page's `next` named, from the newest when omitted. |

**Returns**

`Promise<HistoryPage>`

The page.

**Throws**

[`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"misconfigured"` when `limit` is not a whole number
from 1 to 100, before the store is opened; `"unreadable"` when the store was replaced while it
was read or cannot be read back; `"unsupported-browser"` when the browser refuses it.

**Example**

```ts
import { readHistory } from "@umbra/nimbus-solana-web";
import type { NimbusSession } from "@umbra/nimbus-solana-web";

declare const session: NimbusSession;
const first = await readHistory(session, {}, { limit: 10 });
if (first.next.kind === "more") {
  await readHistory(session, {}, { after: first.next.position, limit: 10 });
}
```

Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/reads.ts`.

## syncNoteStore

Use it before you read the balance or history, and on a timer while your app is open.

```ts
function syncNoteStore(
  session: NimbusSession,
  _args?: Readonly<Record<string, never>>,
  options?: SyncNoteStoreOptions,
): Promise<NoteStoreSyncResult>;
```

Syncs the session's note store: the pools' accounts and counters at the confirmed slot, then
each followed pool's notes, spends, records and registrations from the indexer, a page of each
per round, until every stream is caught up, or `maxRounds` rounds when given.

Notes sealed to the identity become its balance; spends retire its notes; records become its
history; its registration row in a pool lets it spend from that pool. Every row is checked against
its stream before it is taken. A store with no birthday, which an identity that has not registered
through it has, is left untouched. Last, a spend whose tab stopped before sending anything, its
lock no longer held by any tab of this origin, is released, so its notes are available again; a
browser that cannot list its locks skips that step.

**Parameters**

| Parameter  | Type                              | Description                                                                      |
| ---------- | --------------------------------- | -------------------------------------------------------------------------------- |
| `session`  | `NimbusSession`                   | The opened session.                                                              |
| `_args?`   | `Readonly<Record<string, never>>` | Unused; kept so every function takes the same arguments.                         |
| `options?` | `SyncNoteStoreOptions`            | The most rounds, a signal that stops it, the rows per page, and a progress hook. |

**Returns**

`Promise<NoteStoreSyncResult>`

`ingested`, `unregistered`, or `unavailable` with the step the store could not finish.
`ingested` is `caughtUp` unless `maxRounds` ran out first.

**Throws**

[`NimbusSdkError`](https://sdk.nimbusprivacy.xyz/reference/errors#nimbussdkerror) with reason `"misconfigured"` when `maxRounds` is not a whole
number of at least 1 or `pageRows` is not a whole number from 1 to 1000, before anything is
fetched or read; `"service-unavailable"` when the indexer or the RPC cannot be reached;
`"unreadable"` when either answers what cannot be read, or the store was replaced while it was
read; `"unsupported-browser"` when the browser refuses the store.

`signal`'s reason once it aborts, between rounds.

**Example**

```ts
import { syncNoteStore } from "@umbra/nimbus-solana-web";
import type { NimbusSession } from "@umbra/nimbus-solana-web";

declare const session: NimbusSession;
const result = await syncNoteStore(session, {}, {
  onProgress: (round) => {
    console.log(round.round, round.caughtUp);
  },
});
```

Generated from the TSDoc in `sdks/typescript/nimbus-solana-web/src/reads.ts`.


Last updated 21 October 2026