Connecting Brokers

Learn how to connect your users to their brokerages using Finatic's secure portal.

Connecting Brokers

Connecting users to their brokerages is the first step after setting up your Finatic SDK. This guide walks you through the process of securely connecting broker accounts.

Overview

Finatic provides a secure authentication portal that handles broker connections for you. Users authenticate directly with their broker through Finatic's portal, and you get access to their data through the unified API.

SDK Differences:

Client SDK (Recommended): Use openPortal() to open the portal in an iframe directly with callbacks. Best for browser-based applications.
Server SDK: Use getPortalUrl() to get a URL and redirect users. Use this for server-side applications where you need to handle redirects.

Quick Start

The fastest way to connect a broker:

// Client SDK (Recommended)
await finatic.openPortal({
  onSuccess: (userId) => {
    console.log('User authenticated:', userId);
    // IMPORTANT: Save userId to your database
  },
  onError: (error) => {
    console.error('Portal error:', error);
  },
  onClose: () => {
    console.log('Portal closed');
  }
});

Step-by-Step Guide

1. Initialize the SDK

First, ensure your SDK is initialized. See the Quick Start Guide for details.

2. Open the Connection Portal

The portal allows users to:

Select their broker
Authenticate with their broker credentials
Grant permissions for Finatic to access their data

// Client SDK (Recommended) - Opens portal in an iframe with callbacks
await finatic.openPortal({
  brokers: ['broker-id'], // Optional: filter specific brokers
  email: 'user@example.com', // Optional: pre-fill user email
  mode: 'dark', // Optional: mode ('light' or 'dark')
  onSuccess: (userId) => {
    // IMPORTANT: Save userId to your database
    console.log('User authenticated:', userId);
  },
  onError: (error) => console.error('Portal error:', error), // Optional: error callback
  onClose: () => console.log('Portal closed') // Optional: close callback
});

Important Notes for Client SDK (openPortal):
The userId in the success callback is the Finatic user ID for this authenticated session
You must save this userId to your database, associated with your user account
This userId is required for subsequent SDK initializations and immediate data fetch
If the user closes the portal without connecting, the success callback will not be called

3. Verify the Connection

After connecting, you can verify that users have approved access by calling getBrokerConnections(). Any connections that have been approved will appear in the response. If the array is empty, no connections were added.

// Client SDK
const result = await finatic.getBrokerConnections();

if (result.success) {
  const connections = result.success.data;
  console.log(`Found ${connections.length} broker connection(s)`);
} else {
  console.error('Failed to get connections:', result.error);
}

Next Steps

After connecting brokers:

Fetch Account Data - Retrieve accounts, orders, and positions
Handle Errors - Learn error handling patterns
Explore the API Reference - See all available broker operations