Migrate from Beta

Map connection-first beta routes and SDK wrappers to the account-first API.

The beta API exposed broker connections as the primary integration resource. The API makes the financial account and company grant the public resource. Existing beta routes remain available during the migration window, but new integrations should use sessions, Connect grants, account-scoped data reads, account-scoped trading, and webhook subscriptions.

Migration checklist

Replace stored connectionId references with financial accountId references returned by account APIs.
Create company-owned sessions from your backend.
Open Connect through a portal link. Treat onSuccess as session/user linkage and account.grant.created through onEvent as durable grant creation.
Wait for session or account sync readiness, then read balances, positions, transactions, and orders under /api/v1/accounts/{accountId}/....
Add Idempotency-Key to order create/modify/cancel commands.
Persist instrument.finaticInstrumentId from account-scoped reads as the opaque matching identity. Keep legacy symbol and flat identity fields for compatibility/display only.
For placement, send the previously returned canonical value as finaticInstrumentId within the same authorized account/provider scope. Keep provider-native instrumentId separate when the broker requires it.
Subscribe to webhook event types and route events by companyAccountId, accountId, and grantId.

Route mapping

Beta route family	Current API
`POST /api/beta/session/init`	`POST /api/v1/sessions` from a backend with `X-API-Key`.
`POST /api/beta/session/start`	Browser SDK initialization from a one-time token.
`GET /api/beta/session/portal`	`POST /api/v1/sessions/{sessionId}/portal-links`, then open Connect.
`GET /api/beta/session/{sessionId}/user`	`GET /api/v1/sessions/{sessionId}/user` from the backend.
`POST /api/beta/session/link-user`	`POST /api/v1/portal/{sessionId}/user-link`.
`GET /api/beta/portal/{token}`	`GET /api/v1/portal/{token}`.
`POST /api/beta/portal/{sessionId}/complete`	`POST /api/v1/portal/{sessionId}/complete`.
`GET /api/beta/brokers`	`GET /api/v1/portal/{sessionId}/institutions`.
`POST /api/beta/brokers/connect`	`POST /api/v1/portal/{sessionId}/auth-attempts`.
`GET /api/beta/brokers/data/accounts`	`GET /api/v1/accounts`.
`GET /api/beta/brokers/data/balances`	`GET /api/v1/accounts/{accountId}/balances`.
`GET /api/beta/brokers/data/positions`	`GET /api/v1/accounts/{accountId}/positions`.
`GET /api/beta/brokers/data/orders`	`GET /api/v1/accounts/{accountId}/orders`.
`GET /api/beta/brokers/data/orders/{orderId}/fills`	`GET /api/v1/accounts/{accountId}/orders/{orderId}/fills`.
`GET /api/beta/brokers/data/orders/{orderId}/events`	`GET /api/v1/accounts/{accountId}/orders/{orderId}/events`.
`GET /api/beta/brokers/data/transactions`	`GET /api/v1/accounts/{accountId}/transactions`.
`POST /api/beta/brokers/orders`	`POST /api/v1/accounts/{accountId}/orders`.
`PATCH /api/beta/brokers/orders/{orderId}`	`PATCH /api/v1/accounts/{accountId}/orders/{orderId}`.
`DELETE /api/beta/brokers/orders/{orderId}`	`DELETE /api/v1/accounts/{accountId}/orders/{orderId}`.
`GET /api/beta/brokers/connections`	`GET /api/v1/accounts` and `GET /api/v1/account-grants`.
Beta disconnect with `connectionId`	`POST /api/v1/users/{userId}/broker-connections/offboarding` with `{ "accountId": "..." }` and `Idempotency-Key`.

SDK mapping

Beta SDK pattern	SDK pattern
`finatic.getBrokerConnections()`	`finatic.v1.listAccounts()` plus `finatic.v1.listAccountGrants()`.
`finatic.getAccounts({ connectionId })`	`finatic.v1.listAccounts()` then account-scoped methods.
`finatic.getPositions({ connectionId, accountId })`	`finatic.v1.listPositions({ accountId })`.
`finatic.getOrders({ connectionId, accountId })`	`finatic.v1.listOrders({ accountId })`.
`finatic.placeOrder({ broker, accountNumber, order })`	`finatic.v1.createAccountOrder({ accountId, body,
idempotencyKey })`.
Server `getToken()` only	Server session plus portal-link flow for new Connect sessions.
`disconnectBroker({ connectionId })`	`offboardBrokerConnection({ userId, accountId, idempotencyKey })` / `offboard_broker_connection(user_id, account_id, idempotency_key=...)`.

The v1 replacement deliberately does not accept or return connectionId. Choose an account belonging to the broker connection you want to offboard. Revoke a single account grant when the broker connection should remain available, and use user-wide offboarding only when every broker connection for that user should be removed.

Instrument identity migration

The descriptor is additive, so existing symbol-only callers can migrate without removing compatibility fields in one release:

Read instrument on fills, positions, position lots, and lot fills; read each order leg's instrument; and align an event's ordered affectedInstruments with affectedLegs.
Store instrument.finaticInstrumentId as the opaque matching/P&L key. Continue showing legacy securityId, symbol, contractCode, or broker fields only as compatibility/display values.
Treat futures with future.identityQuality: "EXACT" (for example MGCZ6 or MGCG7) as distinct contracts. Treat MGC with ROOT_ONLY as root-only, never as an exact contract.
Do not infer missing month, expiration, exchange MIC, quality, or provenance, and do not reconstruct historical order/fill identity from current positions or lots.
When placing an order, send finaticInstrumentId only if it came from the same authorized account/provider. Keep instrumentId as the separately named provider-native identifier. If both are sent, they must resolve to the same instrument or the request fails closed.

The Python generated model exposes finatic_instrument_id; JSON and raw wrapper dictionaries use the wire field finaticInstrumentId.

Webhook migration

Beta webhook event names such as account.orders.updated and connection.updated are replaced by current event names such as order.updated, account.sync.succeeded, and connection.reauth.required.

Use the catalog endpoint and this docs page as the source of truth for current event strings:

curl https://api.finatic.dev/api/v1/webhooks/catalog

Current webhook payloads and headers are camelCase. Route by companyAccountId, financial accountId, and grantId, and verify HMAC signatures against the exact raw request body before parsing JSON.