Getting Data
Retrieve account-scoped balances, orders, positions, transactions, and sync status.
Read account data after Connect has created a durable grant. Use the financial accountId returned by listAccounts or account.grant.created, and keep your company API key on the backend.
The Client SDK returns { success, error, warning }. The Node and Python Server SDKs return { traceId, data, warnings, errors }.
List accounts
Request sync status with the account list so your UI can distinguish authorization from data readiness.
1type AccountSummary = { accountId: string; syncStatus?: string };
2
3const result = await finatic.v1.listAccounts<AccountSummary[]>({
4 includeSyncStatus: true,
5});
6
7if (result.error) {
8 console.error(result.error);
9} else {
10 const accounts = result.success?.data ?? [];
11 console.log('Accounts:', accounts, result._id);
12}companyAccountId identifies your tenant. Never pass it as the route accountId; the API returns ACCOUNT_ID_TYPE_MISMATCH.
Account pagination
Use limit and offset for list pagination, and request sync status when deciding whether a new grant is ready.
1const result = await finatic.v1.listAccounts({
2 limit: 50,
3 offset: 0,
4 includeSyncStatus: true,
5});Read balances
1const result = await finatic.v1.listBalances({
2 accountId: 'account_123',
3});
4
5console.log(result.success?.data ?? []);Read positions
1const result = await finatic.v1.listPositions({
2 accountId: 'account_123',
3});
4
5console.log(result.success?.data ?? []);Read orders, fills, and events
1const orders = await finatic.v1.listOrders({
2 accountId: 'account_123',
3 limit: 50,
4});
5const fills = await finatic.v1.getAccountOrderFills({
6 accountId: 'account_123',
7 orderId: 'order_123',
8});
9const events = await finatic.v1.getAccountOrderEvents({
10 accountId: 'account_123',
11 orderId: 'order_123',
12});
13
14console.log(orders.success?.data, fills.success?.data, events.success?.data);Exact futures identity
Orders expose identity per ordered legs[] entry. Fills and positions expose instrument directly; order events expose ordered affectedInstruments[] aligned with affectedLegs[]. Use the opaque instrument.finaticInstrumentId as the matching and P&L key. Legacy securityId, symbol, and contractCode remain compatibility or display fields.
1{
2 "finaticInstrumentId": "018f1f20-7b2a-7d18-9d73-0d43724f3c1a",
3 "displaySymbol": "MGCZ6",
4 "assetType": "FUTURE",
5 "providerNativeId": "provider-contract-42",
6 "providerSymbol": "MGCZ6",
7 "future": {
8 "identityQuality": "EXACT",
9 "productRoot": "MGC",
10 "contractCode": "MGCZ6",
11 "contractMonth": "2026-12-01",
12 "expirationDate": "2026-12-29",
13 "exchangeMic": "XCEC"
14 }
15}
16MGCZ6 and MGCG7 are different exact contracts. MGC is root-only and must not be matched to an exact contract. When identity fields are absent, never parse a symbol or use client-side root matching to infer month, expiration, venue, identity quality, or provenance, and current positions or lots are not a universal reconstruction source for a historical order or fill.
Transactions and lots
1const transactions = await finatic.v1.listTransactions({
2 accountId: 'account_123',
3});Position-lot reads are not exposed by the published v1 facades. Use the released account positions response instead of documenting a non-existent listPositionLots helper.
Sync status and pagination
Aggregate sync status means:
pending: no selected accounts are visible yet.syncing: at least one selected account is still loading.reauth_required: send the user back through Connect.failed: at least one selected account failed.ready: selected accounts are ready for reads.
Provider timing varies. Poll with a bounded timeout rather than sleeping for a fixed interval. The released Server SDKs wrap session sync status and keep the company API key on the backend:
1type SessionSyncStatus = 'pending' | 'syncing' | 'reauth_required' | 'failed' | 'ready';
2
3const result = await finatic.v1.getSessionSyncStatus(sessionId);
4
5if (result.errors.length) {
6 console.error(result.traceId, result.errors);
7} else {
8 const status = result.data?.status as SessionSyncStatus | undefined;
9 if (status === 'reauth_required') {
10 // Send the user back through Connect.
11 }
12 if (status === 'ready') {
13 // Query account data.
14 }
15}Use limit and offset on account-scoped list calls. See Standard Response Object and Error Handling for envelope and retry behavior.