> For the complete documentation index, see [llms.txt](https://docs.osero.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.osero.com/osero-sdk/core-concepts/balance-helpers.md).

# Balance Helpers

`@osero/client` exports a set of read-only helpers for querying balances of the three canonical tokens — USDC, USDS, and sUSDS — across all supported chains. These helpers use the SDK's internal chain registry and public client wiring, so you do not need to drop down to raw ERC-20 `balanceOf` calls or manage chain-specific addresses yourself.

All balance helpers return raw `bigint` values and use the same `ResultAsync` model as actions.

***

## Available helpers

| Helper             | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `getTokenBalance`  | Reads one of the three canonical tokens by symbol                   |
| `getTokenBalances` | Reads all three balances in a single call, returning a keyed object |
| `getUsdcBalance`   | Shorthand for USDC balance                                          |
| `getUsdsBalance`   | Shorthand for USDS balance                                          |
| `getSUsdsBalance`  | Shorthand for sUSDS balance                                         |

***

## getTokenBalances

The most common helper. Returns all three balances in one call:

```typescript
import { getTokenBalances } from '@osero/client';

const result = await getTokenBalances(client, {
  chainId: 8453,
  account: '0xYourAddress',
});

if (result.isOk()) {
  console.log('USDC:', result.value.USDC);   // raw bigint, 6 decimals
  console.log('USDS:', result.value.USDS);   // raw bigint, 18 decimals
  console.log('sUSDS:', result.value.sUSDS); // raw bigint, 18 decimals
}
```

***

## getTokenBalance

Reads a single token by symbol:

```typescript
import { getTokenBalance } from '@osero/client';

const result = await getTokenBalance(client, {
  chainId: 42161,
  account: '0xYourAddress',
  token: 'sUSDS',
});

if (result.isOk()) {
  console.log('sUSDS balance:', result.value);
}
```

The `token` field accepts `'USDC'`, `'USDS'`, or `'sUSDS'`.

***

## Single-token shorthand helpers

For the common case of reading one token, the shorthand helpers keep the code concise:

```typescript
import { getUsdcBalance, getUsdsBalance, getSUsdsBalance } from '@osero/client';

const usdc = await getUsdcBalance(client, { chainId: 8453, account });
const usds = await getUsdsBalance(client, { chainId: 8453, account });
const susds = await getSUsdsBalance(client, { chainId: 8453, account });
```

***

## Token decimals

When formatting balances for display, use the correct decimal precision for each token:

| Token | Decimals |
| ----- | -------- |
| USDC  | 6        |
| USDS  | 18       |
| sUSDS | 18       |

```typescript
import { formatUnits } from 'viem';

if (result.isOk()) {
  const formattedUSDC = formatUnits(result.value.USDC, 6);
  const formattedUSDS = formatUnits(result.value.USDS, 18);
  const formattedSUSDS = formatUnits(result.value.sUSDS, 18);
}
```

***

## Error handling

Balance helpers surface the same error variants as actions via `ResultAsync`. The two error types you are most likely to encounter are:

* `UnsupportedChainError` — the `chainId` is not in `SUPPORTED_CHAIN_IDS`
* `UnexpectedError` — an RPC failure or other unexpected condition; inspect `.cause` for the original error

```typescript
const result = await getSUsdsBalance(client, { chainId: 8453, account });

if (result.isErr()) {
  if (result.error.name === 'UnsupportedChainError') {
    console.error('Chain not supported');
  } else {
    console.error('RPC error:', result.error.cause);
  }
}
```

See [Error Handling](broken://pages/8f08d9929188263a38c52d1838d1313117db3664) for the full error reference.

***

## Tracking balance deltas

A common pattern — demonstrated in the roundtrip examples — is to read balances before and after a mint or redeem to track the exact delta:

```typescript
const before = await getTokenBalances(client, { chainId: 8453, account });

// ... execute mintSUsds ...

const after = await getTokenBalances(client, { chainId: 8453, account });

if (before.isOk() && after.isOk()) {
  const usdcSpent = before.value.USDC - after.value.USDC;
  const susdsReceived = after.value.sUSDS - before.value.sUSDS;
  console.log(`Spent ${formatUnits(usdcSpent, 6)} USDC`);
  console.log(`Received ${formatUnits(susdsReceived, 18)} sUSDS`);
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.osero.com/osero-sdk/core-concepts/balance-helpers.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.