Getting Started with SnapTrade

This guide will help you connect a brokerage account, retrieve account data, and, where enabled, place a trade. Start by choosing the customer model that matches who will use the integration.

For definitions used throughout this guide, see Terminology. For more detail about the two customer models, see SnapTrade Personal vs Commercial and Authentication Methods.

The interactive Getting Started Demo currently demonstrates the Commercial flow.

Choose a Customer Model

Personal users can share their connected brokerage data with OAuth-enabled apps or access it directly with a Personal API key. Commercial integrations either use an API key to manage brokerage accounts for their end users or register an OAuth app that end users authorize to access the accounts they manage in SnapTrade Personal.

• Follow the Personal quickstart
• Follow the Commercial quickstart

SnapTrade SDKs

We recommend using a SnapTrade SDK. If you call the API directly, follow Request Signatures to sign each request.

Personal Quickstart

Use this path when you are connecting and managing your own brokerage accounts.

1. Create a Personal Account

1. Create a Personal account in the SnapTrade Dashboard.
2. Verify your email.

2. Choose How to Access Your Data

Most Personal users connect their brokerage accounts in the SnapTrade Dashboard and share that data with apps through OAuth. You can also create a Personal API key when you want to access your data programmatically.

Share Your Data Through OAuth

1. Connect and manage your brokerage accounts in the SnapTrade Dashboard.
2. In an OAuth-enabled app or AI assistant, choose SnapTrade as a data source.
3. Sign in to SnapTrade and approve the access the app requests.

The app receives a scoped OAuth token instead of your Personal API credentials. Do not give an app your consumerKey. OAuth supports reading account data and managing connections. Trading through OAuth is in beta: an app that requests the trade permission can place, modify, and cancel orders in accounts where your brokerage connection supports trading.

To share data with an AI assistant, see the SnapTrade MCP Server. Developers building an app that receives shared data should see Build an OAuth App.

Access Your Data With a Personal API Key

1. Enable two-factor authentication in the SnapTrade Dashboard.
2. Create your Personal API key from the API Key page.
3. Store the clientId and consumerKey securely.

Your Personal API key represents you. Do not register a separate SnapTrade user, and do not send a userId or userSecret in Personal API requests.

3. Connect a Brokerage With Your API Key

If you already connected your brokerage account in the Dashboard, you can skip this step. To add another connection programmatically:

1. Open
   Generate Connection Portal URL

   post
   and select Personal API Key authentication.
2. Enter your Personal clientId and consumerKey. Leave userId and userSecret unset.
3. If you intend to trade, set connectionType to trade-if-available. The default read connection type supports data access only.
4. Send the request and open the returned Connection Portal URL.
5. Complete the Connection Portal flow for your brokerage.

A connection represents a linked set of brokerage credentials. Completing the portal flow makes the brokerage accounts under that connection available through SnapTrade.

For more ways to open and configure the portal, see Methods to Integrate the Connection Portal into Your Application.

4. Retrieve Accounts and Positions

1. Call
   List user accounts

   get
   using Personal API Key authentication to list your accounts.
2. Choose the accountId for the account you want to inspect.
3. Call
   List all account positions

   get
   with that accountId.

You can also retrieve balances with

List account balances

get

and orders with

List account orders

get

.

5. Place an Equity Trade

Personal users can trade their own accounts when trading is enabled for the API key, brokerage, connection, and account.

1. Build the order using the account ID and the brokerage ticker in the symbol field.
2. Validate the order details and confirm them before submission.
3. Call
   Place equity order

   post
   to submit the order to the brokerage.

Use Personal API Key authentication throughout and continue to omit userId and userSecret.

For order types, brokerage support, and other asset classes, see Trading with SnapTrade.

Personal Next Steps

• Learn more about retrieving Account Data.
• Learn how to manage and repair Connections.
• Configure Webhooks.
• Access your data through AI assistants with the SnapTrade MCP Server.

Back to customer models

Commercial Quickstart

Use this path when you are building an application for your own end users. Choose how your app accesses their brokerage data:

• Build with OAuth
• Build with a Commercial API key

Option 1: Build With OAuth

With OAuth, users bring the brokerage accounts they already manage in SnapTrade, and a single connection can be shared with every app they use. Your app does not register SnapTrade users, store userSecret values, sign requests, or embed the Connection Portal.

1. Register an OAuth App

1. Create a Commercial account in the SnapTrade Dashboard.
2. Select OAuth Apps in the left sidebar, create a Test app, and add your redirect URIs. Production redirects must use HTTPS; local testing can use a loopback address such as http://127.0.0.1.
3. Save the client_id and client_secret on a secure backend. The secret is shown only once.
4. When you are ready for production, complete the Production Access Application and register a Production app.

Test OAuth apps are limited to 5 users. To test the consent flow, use a SnapTrade Personal account with at least one brokerage connection.

2. Send the User Through Authorization

1. Read the authorization server metadata from https://api.snaptrade.com/.well-known/oauth-authorization-server to find the authorization, token, and revocation endpoints.
2. Generate a fresh state and PKCE code_verifier for the attempt, and derive an S256 code_challenge.
3. Redirect the user to the authorization endpoint with response_type=code, your client_id, redirect_uri, state, code_challenge, code_challenge_method=S256, and scope=read. Add trade if your app places orders and webhook if it needs event notifications.

The user signs in to SnapTrade, reviews the requested access, and approves or denies your app.

3. Exchange the Code for Tokens

1. In your callback, reject the response if state does not match, and handle any error without exchanging a code.
2. From your backend, exchange the code and code_verifier at the token endpoint using HTTP Basic client authentication.
3. Store the returned access_token and refresh_token encrypted and associated with the signed-in user.

Access tokens are valid for 10 hours. Refresh tokens rotate: each successful refresh returns a new refresh token that replaces the old one.

4. Retrieve Accounts and Positions

Send the access token as a Bearer token. Do not include clientId, consumerKey, userId, userSecret, timestamp, or Signature on OAuth requests.

GET https://api.snaptrade.com/accounts
Authorization: Bearer ACCESS_TOKEN
Accept: application/json

1. Call
   List user accounts

   get
   to list the accounts the user shared.
2. Choose the accountId for the account you want to inspect.
3. Call
   List all account positions

   get
   with the accountId.

You can also retrieve balances with

List account balances

get

and orders with

List account orders

get

. Users add, repair, and remove brokerage connections in the SnapTrade Dashboard.

5. Place an Equity Trade

OAuth trading is in beta. Your app can trade when the user granted the trade scope and their brokerage connection supports trading.

1. Build the order using the account ID and the brokerage ticker in the symbol field.
2. Show the user the order details and have them confirm it.
3. Call
   Place equity order

   post
   with the Bearer token to submit the order to the brokerage.

Users who authorized your app without trade must go through the authorization flow again to grant it.

For token refresh, revocation, OpenID Connect sign-in, webhooks, and a production checklist, see Build an OAuth App.

Option 2: Build With a Commercial API Key

Use a Commercial API key when your app needs to create and manage SnapTrade users and their brokerage connections itself.

1. Create a Commercial API Key

1. Create a Commercial account in the SnapTrade Dashboard.
2. Verify your email.
3. Enable two-factor authentication.
4. Create a test API key from the API Key page.
5. When you are ready for production, complete the required approval and billing steps in the Dashboard and create a production key.
6. Store the clientId and consumerKey on a secure backend.

For plan limits and production requirements, see Billing.

2. Register a SnapTrade User

A Commercial integration creates one SnapTrade user for each end user in the application.

1. Call
   Register user

   post
   with a stable, immutable userId from your system. Avoid using an email address.
2. Store the returned userSecret securely. SnapTrade returns it only when the user is registered.

The userId and userSecret identify this app user in subsequent user-scoped requests.

3. Connect a Brokerage

1. Call
   Generate Connection Portal URL

   post
   using Commercial API Key authentication.
2. Provide the app user's userId and userSecret.
3. If the user intends to trade, set connectionType to trade-if-available. The default read connection type supports data access only.
4. Open the returned Connection Portal URL and send the end user through the portal flow.

After the user completes the flow, the connection and its brokerage accounts are available through SnapTrade.

For more ways to open and configure the portal, see Methods to Integrate the Connection Portal into Your Application.

4. Retrieve Accounts and Positions

1. Call
   List user accounts

   get
   with the user's userId and userSecret.
2. Choose the accountId for the account you want to inspect.
3. Call
   List all account positions

   get
   with the accountId, userId, and userSecret.

You can also retrieve balances with

List account balances

get

and orders with

List account orders

get

.

5. Place an Equity Trade

Commercial integrations can trade when trading is enabled for the API key, brokerage, connection, and account.

1. Build the order using the account ID and the brokerage ticker in the symbol field.
2. Validate the order details in your application and have the end user confirm them.
3. Call
   Place equity order

   post
   to submit the order to the brokerage.

Include the user's userId and userSecret in each user-scoped request.

For order types, brokerage support, and other asset classes, see Trading with SnapTrade.

Commercial Next Steps

• Complete your OAuth integration with Build an OAuth App.
• Configure Webhooks.
• Finish integrating the Connection Portal.
• Prepare your integration for production with Launching Your Application.
• Review Commercial pricing and limits in Billing.

Back to customer models

For troubleshooting, see the FAQ. If you still need help, contact us through Discord.