Finatic Client SDK

Browser SDK for integrating Finatic in frontend applications.

This package is optimized for SDK-first portal and brokerage-data workflows from client-side apps.

Version lines (FDX v1)

| Version | API surface | Use when | |---------|-------------|----------| | 1.0.0+ | /api/v1/* via finatic.v1 | New account-grant integrations | | 0.9.x | /api/beta/* via legacy wrappers | Existing apps until migrated |

Legacy beta clients live under src/openapi-legacy/; v1 OpenAPI output is under src/openapi/.

Install

npm install @finatic/client

Quick Start

import { FinaticConnect } from '@finatic/client';

const finatic = await FinaticConnect.init('one-time-token', undefined, {
  apiEnvironment: 'sandbox', // or 'live'
});
await finatic.openPortal({ mode: 'dark' });
const accounts = await finatic.v1.listAccounts({ includeSyncStatus: true });
const positions = await finatic.v1.listPositions({ accountId: 'account-id' });

The client SDK requires a one-time token generated by a backend flow (typically via server SDK). Account-first v1 calls send X-Finatic-Environment: live|sandbox and use financial account ids in /api/v1/accounts/{accountId}/... paths. Beta connection-first wrappers remain available for compatibility, but new browser workflows should prefer finatic.v1 for session-authenticated account, grant, consent, data, trading, and webhook calls.

Migrating From Beta Wrappers

The generated beta wrappers (SessionWrapper, BrokersWrapper, and CompanyWrapper) are deprecated for new account-first browser work. They remain exported for compatibility while API PR #174 finalizes the v1 OpenAPI contract.

Use this mapping from the API beta migration metadata:

| Beta route family | v1 browser/client replacement | |---|---| | /api/beta/session/init | Backend/server SDK session creation; initialize browser SDK with the one-time token | | /api/beta/session/start | FinaticConnect.init(...) with the one-time token | | /api/beta/session/portal | finatic.openPortal(...) or a backend/server SDK portal-link flow | | /api/beta/session/{session_id}/user | Backend/server SDK session lookup | | /api/beta/session/link-user | finatic.v1.linkPortalUser(...) | | /api/beta/portal/{token} | finatic.v1.exchangePortalToken(...) | | /api/beta/portal/{session_id}/complete | finatic.v1.completePortalSession(...) | | /api/beta/brokers | finatic.v1.listPortalInstitutions(...) | | /api/beta/brokers/connect | finatic.v1.createPortalAuthAttempt(...) | | /api/beta/brokers/data/accounts | finatic.v1.listAccounts(...) | | /api/beta/brokers/data/balances | finatic.v1.listBalances({ accountId, ... }) | | /api/beta/brokers/data/positions | finatic.v1.listPositions({ accountId, ... }) | | /api/beta/brokers/data/positions/lots | finatic.v1.listPositionLots({ accountId, ... }) | | /api/beta/brokers/data/positions/lots/{lot_id}/fills | finatic.v1.getAccountPositionLotFills({ accountId, lotId }) | | /api/beta/brokers/data/orders | finatic.v1.listOrders({ accountId, ... }) | | /api/beta/brokers/data/orders/{order_id}/fills | finatic.v1.getAccountOrderFills({ accountId, orderId }) | | /api/beta/brokers/data/orders/{order_id}/events | finatic.v1.getAccountOrderEvents({ accountId, orderId }) | | /api/beta/brokers/data/transactions | finatic.v1.listTransactions({ accountId, ... }) | | /api/beta/brokers/orders | finatic.v1.createAccountOrder({ accountId, ... }) | | /api/beta/brokers/orders/{order_id} | finatic.v1.modifyAccountOrder(...) or finatic.v1.cancelAccountOrder(...) | | /api/beta/brokers/connections | finatic.v1.listAccounts(...) plus finatic.v1.listAccountGrants() |

The v1 surface uses financial account ids in path parameters. Do not carry beta connectionId or user_broker_connection_id values into new browser flows. The API-key-owned v1 session routes are intentionally not callable through the browser-safe finatic.v1 wrapper; use a backend/server SDK flow for those routes.

Environments

Use the environment option for the standard Finatic targets, or custom with explicit URLs:

const finatic = await FinaticConnect.init('one-time-token', undefined, {
  environment: 'staging',
});

finatic.configure({ environment: 'production' });

Supported presets are production, staging, development, and sandbox. Runtime config changes rebuild the SDK's API clients and wrappers so future calls use the new target. Use FinaticConnect.reset() before init(...) when you need a fresh singleton and session boundary.

Common Commands

| Task | Command | |---|---| | Build | npm run build | | Test | npm test | | Coverage | npm run test:coverage | | Lint | npm run lint | | Format | npm run format |

Core Capabilities

• Initialize a Finatic client session from a one-time token.
• Launch connection/auth portal in iframe or URL redirect mode.
• Read account-scoped v1 resources (accounts, balances, positions, transactions, orders).
• Manage account grants, consents, and webhook/event catalog calls from the browser-safe v1 wrapper.
• Listen to portal lifecycle events for UX state handling.
• Use typed request/response models across methods.

Documentation

• Product docs: https://finatic.dev/docs
• API reference: https://finatic.dev/docs/api-reference
• LLM context doc: https://finatic.dev/llms.txt

Using Finatic with AI

You can use this SDK to power AI-assisted product experiences today:

• retrieve balances, positions, and order history across connected brokers
• standardize broker operations behind one client-facing SDK surface
• combine SDK outputs with application-specific AI prompts and workflows

MCP support is coming soon.