# avanza-ts

> TypeScript SDK for Avanza

Latest version **1.0.0** (published 2026-09-24) · 0 weekly downloads

## Install

```sh
npm install avanza-ts
pnpm add avanza-ts
yarn add avanza-ts
bun add avanza-ts
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2026-09-24 |
| First published | 2022-11-20 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22.12.0 |
| Dependencies | 2 |
| Unpacked size | 400.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 1 |
| Maintainers | antewall |

## Links

- npm: https://www.npmjs.com/package/avanza-ts
- Repository: https://github.com/AnteWall/avanza-ts
- Homepage: https://github.com/AnteWall/avanza-ts#readme
- Issues: https://github.com/AnteWall/avanza-ts/issues
- npm.io page: https://npm.io/package/avanza-ts

## Dependencies (2)

- [zod](https://npm.io/package/zod.md) ^4.6.5
- [tough-cookie](https://npm.io/package/tough-cookie.md) ^6.0.2

## Recent versions

- 1.0.0 (latest) — 2026-09-24
- 0.7.0 — 2022-12-04
- 0.6.0 — 2022-11-28
- 0.5.0 — 2022-11-25
- 0.4.0 — 2022-11-22
- 0.3.0 — 2022-11-22
- 0.2.0 — 2022-11-20

## README

# avanza-ts

Reusable, ESM-first TypeScript SDK for Avanza.

## Disclaimer

This is an unofficial TypeScript SDK for Avanza's API. It is not affiliated with Avanza Bank AB. The underlying API can be taken down or changed without warning at any point in time.

The author of this software is not responsible for any indirect damages (foreseeable or unforeseeable), such as, if necessary, loss or alteration of or fraudulent access to data, accidental transmission of viruses or of any other harmful element, loss of profits or opportunities, the cost of replacement goods and services or the attitude and behavior of a third party.

## Client

`AvanzaClient` owns one HTTP transport, one mutable in-memory session, and domain clients that will
contain the individual API operations.

```ts
import { AvanzaClient, type AvanzaSession } from 'avanza-ts';

const session: AvanzaSession = {
  authenticationSession: process.env.AVANZA_AUTHENTICATION_SESSION!,
  mode: 'totp',
  securityToken: process.env.AVANZA_SECURITY_TOKEN!,
};

const client = new AvanzaClient({ session });

client.accounts;
client.auth;
client.instruments;
client.market;
client.orders;
client.websocket;
```

The stock screener and authentication endpoints are available; other domain clients establish the
SDK structure for future operations.

## Stock screener

```ts
const { stocks, totalNumberOfOrderbooks } = await client.instruments.screenStocks({
  filter: { marketPlaces: ['se'], sectors: ['38'], numberOfOwners: { minValue: 100 } },
  offset: 0,
  limit: 20,
  sortBy: { field: 'numberOfOwners', order: 'desc' },
});

const options = await client.instruments.getStockFilterOptions();
const theme = await client.instruments.getThemeStocks(['5361', '1234'], {
  field: 'numberOfOwners',
  order: 'desc',
});
const movers = await client.instruments.getGainersLosers({ marketPlaces: ['se'] });
```

The response includes pagination, filter options, and per-stock prices, performance, ownership,
fundamentals, and technical indicators. Requests and responses are validated with Zod. Stock sector
lists are available through `getPopularStockSectors()` and `getAllStockSectors()`.

With an authenticated session, `getStockScreenerMetadata()`, `getStockScreenerTabs()`, and
`getSavedStockFilters()` read personal settings. `saveStockScreenerTabs(tabs)` and
`saveStockFilters(filters)` replace their respective complete collections;
`deleteStockScreenerTabs()` deletes all custom tabs.

## Sessions

Session persistence does not belong to the SDK. Applications can load a session from their preferred
store, pass it to the constructor, and update the active session later.

```ts
client.setSession(session);
client.clearSession();
```

Sessions are discriminated by `mode`. TOTP sessions contain authentication headers, while BankID
sessions contain an RFC-compliant, JSON-serializable cookie snapshot and may contain a security
token. Authentication-required requests fail before making a network call when no session is
available.

Sessions contain sensitive credentials. Persist them only in a suitable credential store; do not log
them or commit them to source control.

## TOTP authentication

Log in with either the current six-digit code or the base32 secret used to generate it:

```ts
const session = await client.auth.loginWithTotp({
  username: process.env.AVANZA_USERNAME!,
  password: process.env.AVANZA_PASSWORD!,
  totpSecret: process.env.AVANZA_TOTP_SECRET!,
});
```

Use `totpCode` instead of `totpSecret` when code generation happens outside the SDK. The completed
session is returned and installed on `client.session`.

## BankID authentication

Starting BankID returns an attempt with the current QR payload and a same-device autostart URL:

```ts
const attempt = await client.auth.startBankId();

renderQr(attempt.challenge.qrPayload);

while (true) {
  await new Promise((resolve) => setTimeout(resolve, attempt.challenge.refreshAfterMs));
  const result = await attempt.poll();

  if (result.status === 'pending') {
    renderQr(result.challenge.qrPayload);
    continue;
  }
  if (result.status === 'complete') {
    console.log('Authenticated');
  }
  break;
}
```

`qrPayload` is the text to encode in a QR image; it is not an image URL. Avanza rotates it while the
attempt is pending, so callers must rerender the QR returned by each poll. The SDK deliberately does
not choose an SVG, PNG, terminal, or browser renderer. When Avanza supplies same-device autostart
metadata, `autostartUrl` uses the `bankid://` scheme.

Call `attempt.cancel()` when abandoning an in-progress login. Attempts default to a 120-second
overall timeout and suggest polling every 1.5 seconds.

## Session lifecycle

Restored sessions can be checked before use, and logout clears the local session even when remote
cleanup fails:

```ts
const valid = await client.auth.validateSession();

if (valid) {
  await client.auth.logout();
}
```

`getSessionInfo()` returns the raw session-info response. It sends the installed session when one is
available and otherwise makes the same request anonymously:

```ts
const info = await client.auth.getSessionInfo();
```

## Configuration

The client uses `https://www.avanza.se` and the Node.js global `fetch` implementation by default. Both
can be replaced, primarily for testing or routing through a controlled transport.

```ts
const client = new AvanzaClient({
  baseUrl: 'https://example.test',
  fetch: customFetch,
});
```

---
_Source: https://npm.io/package/avanza-ts · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._