# startBalanceRefresh

Scan an account's balances every 30 seconds, so notes that arrive while the app is open are found
without an explicit refresh. Off until started; runs until the returned function is called, `signal`
aborts or the config is destroyed.

Runs never overlap. A run that finds a refresh in progress joins it, and a run while refreshes are
paused (as during plan execution) is skipped. Background runs emit no `balance-refresh-*` events;
a failure stays in `state.scan` and the next run tries again.

A config runs one loop: starting again, for example for another account, replaces it, and the
replaced loop's stop function then does nothing.

## Import

```ts
import { startBalanceRefresh } from "@0xcurvy/curvy-sdk/actions";
```

## Usage

```ts
const stop = startBalanceRefresh({ runImmediately: true }); // active account, first scan now
stop();
```

## Signature

```ts
function startBalanceRefresh(parameters?: StartBalanceRefreshParameters): () => void
```

## Returns

`() => void`

Stops this loop. Unlike aborting `signal`, it lets a scan already running finish.

## Parameters

### `accountId`

- **Type:** `string`
- **Required:** no

The account to keep scanning. Defaults to the account that is active at each run.

```ts
const result = startBalanceRefresh({
  accountId, // [!code focus]
});
```

### `runImmediately`

- **Type:** `boolean`
- **Required:** no

Scan once now instead of waiting a full interval for the first run.

```ts
const result = startBalanceRefresh({
  runImmediately, // [!code focus]
});
```

### `signal`

- **Type:** `AbortSignal`
- **Required:** no

Stops the loop and cancels a scan it started, for example when the signed-in session ends.

```ts
const result = startBalanceRefresh({
  signal, // [!code focus]
});
```

### `config`

- **Type:** `CurvyConfig`
- **Required:** no

Curvy config to use. Defaults to the ambient config.

```ts
const result = startBalanceRefresh({
  config, // [!code focus]
});
```

## Errors

Errors from config resolution and the underlying SDK operation are propagated to the caller.

## Related

- [Querying balances guide](/for-programmers/querying-balances)

## Source

[packages/@0xcurvy/sdk/src/actions/balances/startBalanceRefresh.ts](https://github.com/0xCurvy/curvy-monorepo/blob/main/packages/@0xcurvy/sdk/src/actions/balances/startBalanceRefresh.ts)