  Getting Started with SnapTrade     Introduction  Welcome to SnapTrade  This is intended to be one of the first documents you read when learning how to use the SnapTrade API and will answer many questions you might have while getting started  This document when read from top to bottom is also a guide for making your first connection  and will get you set up to start pulling account data and placing trades   Please see the FAQ of each section  as any questions you might have should be answered there   If after reading this document you still have questions or need help  please do not hesitate to contact us through our  Discord  https   discord gg rkYWBxb8Qu    For a live demo  see the  Getting Started Demo  https   docs snaptrade com demo getting started            API Keys    image png    assets 250312 apikey png    Your  API key  consists of a  clientId  and  consumerKey   Please note that your  consumerKey  is sensitive information and should be kept secure at all times  This  API key  is used to make any requests to the SnapTrade API  and is the first thing required to get started       How to  Create a new API Key  When you are ready to get started with SnapTrade and want to start making requests to our API  you will need to create your free and paid  API keys   You may create only your free key if preferred   1  Create a SnapTrade account at the  SnapTrade Dashboard  https   dashboard snaptrade com home   2  Verify your email  You cannot create any  API Keys  until your account is verified   3  Generate your free  API Key  through the  SnapTrade Dashboard  https   dashboard snaptrade com api key   4   OPTIONAL  Add a payment method through the Settings   Billing page of the  SnapTrade Dashboard  https   dashboard snaptrade com settings billing   5   OPTIONAL  Upgrade to Pay as you Go through Settings   Billing page of the  SnapTrade Dashboard  https   dashboard snaptrade com settings billing   6   OPTIONAL  Generate your paid  API Key  through the  SnapTrade Dashboard  https   dashboard snaptrade com api key    After completing these steps  you will have two SnapTrade  API Keys      A free  API Key  that limits the number of concurrent connections    Optionally  a paid  API Key  that allows for unlimited connections   These two  API keys  are essentially the same in terms of functionality  and the core difference between them is that the free  API key  is limited in terms of the number of concurrent connections you can have  You can use these  API keys  to make requests to the SnapTrade API       How to  Make a request to the SnapTrade API  When you have an  API Key  and want to start using the SnapTrade API  you will need to use your  API Key  to make requests to the SnapTrade API   1  With your Free  API Key   enter your  clientId  and  consumerKey  into the corresponding fields of  api ApiStatus check   2  Press  Send    In the box below the  request  you should receive a response from the SnapTrade API  The  api ApiStatus check  endpoint is the most basic request you can make to the SnapTrade API   You can also make this request with any of the SnapTrade SDKs  While we don t officially support custom setups without an SDK  you can copy the signature generation logic from any of our SDKs if you want to go that route       SnapTrade SDKs      Language       SDK Link                     Python      https   pypi org project snaptrade python sdk    https   pypi org project snaptrade python sdk      TypeScript      https   www npmjs com package snaptrade typescript sdk    https   www npmjs com package snaptrade typescript sdk      Java      https   central sonatype com artifact com snaptrade snaptrade java sdk    https   central sonatype com artifact com snaptrade snaptrade java sdk      Ruby      https   rubygems org gems snaptrade    https   rubygems org gems snaptrade      C       https   nuget org packages SnapTrade Net    https   nuget org packages SnapTrade Net      PHP      https   packagist org packages konfig snaptrade php sdk    https   packagist org packages konfig snaptrade php sdk      Go      https   pkg go dev github com passiv snaptrade sdks sdks go    https   pkg go dev github com passiv snaptrade sdks sdks go          API Keys FAQ  https   docs snaptrade com docs faq faq api keys           Users    image png    assets 250312 apikey2users png   Your  API key  will be used to manage a set of SnapTrade  users   A SnapTrade  user  consists of a  userId  and a  userSecret   The  userSecret  is a randomly generated string and is sensitive information  It should be kept secure at all times   Typically if you have an application that manages end users  each end user of your application will get one SnapTrade  user  that will be used to manage that end user s  connections   This way  SnapTrade  users  will be one to one with the end users of your application       How to  Create a new SnapTrade User  When you have a working  API Key  and want to create a new  connection  for a  user   you will first need to register a SnapTrade  user    1  Using your API Key  create a request to the  api Authentication registerSnapTradeUser  endpoint  You will need to provide a unique SnapTrade  userId    This can be anything that is immutable  For this reason  it is recommended to NOT use email addresses for a SnapTrade  userId   2  The response you receive from the SnapTrade API will contain the  userId  you provided and the  userSecret  generated by SnapTrade  The  userSecret  is a randomly generated string and is sensitive information   You can list your created users by using the  api Authentication listSnapTradeUsers  endpoint  and you can delete created users by using the  api Authentication deleteSnapTradeUser  endpoint  If needed  you may reset a user s userSecret by using the  api Authentication resetSnapTradeUserSecret  endpoint  Now that you have one or more SnapTrade  users  under your  API Key   you are ready to create  connections  under these  users         Users FAQ  https   docs snaptrade com docs faq faq users           Connections    image png    assets 250312 users2connections png   Each  user  under your SnapTrade API key will be used to create and manage  connections  associated with that user  Each connection is associated one to one with a set of credentials to an institution      info The terms  Connections  and  Brokerage Authorizations  are interchangeable  In most documents  the term  connection  is used           How to  Create a new connection for a user  When you have a SnapTrade user and want to get access to their account data and or place trades for an account  you will need to create a  connection  for that user   1  Generate a new redirectURI for the SnapTrade Connection Portal using  api Authentication loginSnapTradeUser  3  Open the generated link  Depending on your application  there are different ways to open this link  See  Methods to Integrate the Connection Portal into Your Application  https   docs snaptrade com docs implement connection portal    Once you have successfully completed the Connection Portal Flow  you should have an active connection to work with  and should have access to the accounts under that connection        Connections FAQ  https   docs snaptrade com docs faq faq connections           Accounts    image png    assets 250312 connections2accounts png   When you create a  connection   SnapTrade will automatically sync all  accounts  under the set of credentials to the brokerage  For example  if you made a new  connection  to Questrade  a Canadian brokerage  and that  connection  had a TFSA  an RRSP and an FHSA account under those credentials  SnapTrade would make all these  accounts  accessible over the SnapTrade API   Once you have a connected  account   you are ready to move on to pulling account data  and placing trades for that account       How to  Get positions for an account  When you have at least one connected  account  and want to start making use of the  positions   you will first need to get the  accountId    1  You can find the  accountId  anywhere over the API where the  account  object is returned  In this example  use the  api AccountInformation listUserAccounts  endpoint to get the  accountId  of the account you wish to pull  positions  for  2  With the  accountId   call  api AccountInformation getUserAccountPositions   This will return a list of positions in the specified account   Once you have  positions  returned  you re able to make use of the data in analysis  monitoring  or another use case you might be interested in  Other core endpoints for retrieving account information include  api AccountInformation getUserAccountBalance  and  api AccountInformation getUserAccountOrders        How to  Place a checked trade for an account  When you have at least one connected  account  and want to place a trade in the account  you will need to follow these steps to place a checked order  Note that you may also place an order without checking it   1  You need to get the  universalSymbolId  for the instrument that you wish to place an order for  You can find this using  api Trading getUserAccountQuotes   2  Validate the order with  api Trading getOrderImpact   This is a safe way to check the impact that the trade will have on the account if it is executed  and this is recommended to show on a screen to your user to have them confirm the order  Save the  tradeId  returned by this endpoint  it will be used in the next step  This  tradeId  will expire after a few minutes  3  Using the  tradeId  returned from  api Trading getOrderImpact   place the checked order using  api Trading placeOrder   This will place the order at the brokerage for the account  and return the response given by the broker   The order will now show over the  api AccountInformation getUserAccountOrders  endpoint  If it does not  you may need to trigger a refresh for the connection using  api Connections refreshBrokerageAuthorization         Accounts FAQ  https   docs snaptrade com docs faq faq account information          image png    assets 250312 model png      Next Steps    To get started with Webhooks  see  Webhooks  https   docs snaptrade com docs webhooks    To get started with implementing the SnapTrade Connection Portal  see  Methods to Integrate the Connection Portal into Your Application  https   docs snaptrade com docs implement connection portal  

Getting Started with SnapTrade

  Connection Portal     Overview  The Connection Portal is the front end interface your users interact with to link their brokerage accounts to the SnapTrade API    img src    assets portal overview png  alt  connection portal overview  width  700         Introduction  The Connection Portal is a drop in UI that lets your users link brokerage accounts to the SnapTrade API  It handles credential entry  MFA  reconnects  and redirects  so your app only needs to open a connection portal link and and process the connection result when users are returned to your app   SnapTrade s connection portal is built to run smoothly on all modern browsers and platforms  including     Web apps   Native iOS   Native Android   React Native      Initializing  The SnapTrade connection flow begins when your user shows intent to connect their brokerage account to your app   1  User taps  Connect Account  in your app   Your app calls your backend to generate a SnapTrade connection portal login link and returns it to the client        2  Your app opens the SnapTrade connection portal login link for the user  see  Integration Methods for platform specific best practices   integration methods     They select their brokerage and go through the login flow        3  After successfully connecting  SnapTrade redirects the user back to your app        4  Your backend can now fetch and store the connection details and use them to make necessary API requests for the user       Login Link Parameters      connectionType  optional     Sets the level of access requested  Defaults to  read        read   Data access only      trade   Data   trading access      trade if available   Requests trading access if supported  otherwise falls back to  read       broker  optional    broker slug    If you display broker options in your own UI instead of using SnapTrade s built in selection screen  pass the broker slug here  This skips the integrations selection screen and goes directly into that brokerage s login flow  See the  integrations page  https   support snaptrade com brokerages table      customRedirect  optional     Override the default redirect URL for this session      immediateRedirect  optional  boolean     If true  skips the Connection Portal s success or error screen and sends the user straight back to your app after the connection attempt  using either the default or custom redirect URL      reconnect  required for reconnect flow     The UUID of a connection that needs to be re established  Leave this empty unless you are explicitly reconnecting a disabled connections      showCloseButton  optional  boolean     Set to  false  to hide the close  X  button  Useful for mobile implementations where the native WebView or browser already provides a close button  Defaults to  true       Integration Methods  You can display the Connection Portal in your application using one of the following methods  Pick one method depending on platform and UX needs       Embedded iframe  recommended for web apps   Displays the portal within your application using an iframe     Best for    Web apps   Keeping users within your app  better user experience  when you want full control over the flow     Example React snippet      jsx const ConnectionPortalModal      loginLink            Modal title  SnapTrade Connection Portal  visible footer  null        iframe       id  snaptrade connection portal        src  loginLink        title  SnapTrade Connection Portal        style    width   100    height   70vh   border  0          sandbox  allow forms allow scripts allow same origin allow popups        referrerPolicy  no referrer        allow  clipboard read  clipboard write        aria label  SnapTrade connection portal             Modal            Key Considerations      Find guidance on how to monitor window messages  here   implement connection portal window messages       Your application is responsible for closing the iframe modal post connections      If not using  snaptrade react  SDK  you must handle responsive sizing and closing the modal  The SDK simplifies this      info For React applications  we recommend using our  snaptrade react  SDK which offers a seamless integration process  For installation and setup instructions  refer to  SnapTrade React SDK on npm  https   www npmjs com package snaptrade react   The SDK provides built in callbacks that allow you to use client side window messages for monitoring successful connections or failures  ensuring a smoother user experience           New Browser Tab  Opens the portal in a separate browser tab or popup window     Best for    Web apps   Straightforward connection flows     Key Considerations      To determine the connection state  your application can use one of the following approaches          Option 1  Window messages           Open the Connection Portal in a new window using  window open   This is required to receive client side window messages          Refer to the documentation on how to listen for and handle these messages  here   implement connection portal window messages           Option 2  Query parameters in redirect           The portal will redirect back to your URL with query parameters              SUCCESS      your redirect url  status SUCCESS connection id  connection id               ERROR      your redirect url  status ERROR status code  status code  error code  error code               ABANDONED      your redirect url  status ABANDONED      You can provide a custom redirect to navigate the user back to a specific page in your app post connection      Set  immediateRedirect  to true in the login link to skip the connection portal s internal finish screens and redirect immediately       Mobile In app Browser  Recommended for mobile apps   Use  SFSafariViewController  on iOS   Chrome Custom Tabs  on Android  or the recommended in app browser library for React Native  This preserves browser features required by OAuth and Passkeys     Best for    Mobile applications  React Native  native iOS Android apps  etc      Implementation guides        React Native   implement connection portal react native     iOS   implement connection portal native ios     Android   implement connection portal native android      Window messages  We send these  window messages  https   developer mozilla org en US docs Web API Window message event  to notify your app about user actions and the status of the connection attempt   Your app should listen for these messages and respond accordingly  for example by showing toast notifications  performing redirects  or running any other app logic that makes sense for your use case     Messages       SUCCESS    Indicates successful institution connection  The message contains the authorization ID  same as connection id             status   SUCCESS   authorizationId   AUTHORIZATION ID                ERROR    Sent when a connection error occurs  including an error code  status code and description            status   ERROR   errorCode   ERROR CODE   statusCode   STATUS CODE   detail   DETAIL OF THE ERROR                CLOSED    Sent when the user manually closes the OAuth connection window that opens in a new tab        Note  This message is only emitted when the connection portal is loaded inside an iframe  In other integration methods  the OAuth flow opens in the same tab as the connection portal  so closing the OAuth window also ends the entire connection portal session         ABANDONED    Functions the same as  CLOSE MODAL  but only triggers for non iframe implementations        Example React snippet          jsx     useEffect               const handleMessageEvent    e               if  e data              const data   e data             if  data status      SUCCESS                 const authorizationId   data authorizationId                 close the connection portal modal and display success message to the user             else if  data status      ERROR                 const   errorCode  statusCode  detail     data                 close the connection portal modal and display error message to the user             else if               data      CLOSED                 data      CLOSE MODAL                 data      ABANDONED                               close the modal                                       window addEventListener  message   handleMessageEvent  false          return                 window removeEventListener  message   handleMessageEvent  false                                    React Native  Authentication Flow    Your App     In App Browser     SnapTrade Auth     Redirect     Your App        Redirect URL Parameters  SnapTrade redirects back to your app with these parameters       Success         status SUCCESS       connection id  string     The connection ID to use for API calls      Error         status ERROR       error code  string     Error code describing what went wrong      status code  number     HTTP status code      Expo  1  Configure URL scheme in  app config json  or  app json       js export default     expo        scheme   yourapp              other config              2  Install Dependencies     bash npx expo install expo web browser expo linking      3  Rebuild the app after adding URL schemes     bash npx expo prebuild   clean npx expo run ios npx expo run android      4  Basic implementation     tsx import   as WebBrowser from  expo web browser   import   as Linking from  expo linking   import   useEffect   from  react    function SnapTradeConnect          Handle incoming deep links   useEffect                Handle deep link when app is already open     const subscription   Linking addEventListener  url   handleDeepLink           Handle deep link when app opens from closed state     Linking getInitialURL   then  url             if  url  handleDeepLink   url                  return       subscription remove                 const handleDeepLink    event           const   url     event      const   queryParams     Linking parse url           Dismiss the in app browser     WebBrowser dismissBrowser            Handle the callback     if  queryParams status      SUCCESS           console log  Connection successful    queryParams connection id            Save connection id and proceed with your flow       else if  queryParams status      ERROR           console error  Connection failed    queryParams error code            Show error to user               const openSnapTrade   async             const snaptradeUrl    YOUR SNAPTRADE LOGIN LINK        try         await WebBrowser openBrowserAsync snaptradeUrl         catch  error          console error  Failed to open browser    error                 return  Button onPress  openSnapTrade  Connect Account  Button              Vanilla React Native  1  Configure URL scheme     iOS  Add to  Info plist        key CFBundleURLTypes  key   array     dict       key CFBundleURLSchemes  key       array         string yourapp  string        array      dict    array          Android  Add to  AndroidManifest xml        intent filter     action android name  android intent action VIEW        category android name  android intent category DEFAULT        category android name  android intent category BROWSABLE        data android scheme  yourapp       intent filter       2  Install Dependencies     bash npm install react native inappbrowser reborn       3  Basic Implementation     tsx import InAppBrowser from  react native inappbrowser reborn   import   Linking   from  react native   import   useEffect   from  react    function SnapTradeConnect       useEffect             const handleDeepLink    event             const url   event url        const params   parseUrl url          if  params status      SUCCESS             console log  Connection successful    params connection id           else if  params status      ERROR             console error  Connection failed    params error code                       const subscription   Linking addEventListener  url   handleDeepLink        Linking getInitialURL   then  url             if  url  handleDeepLink   url                  return       subscription remove                 const openSnapTrade   async             const snaptradeUrl    YOUR SNAPTRADE LOGIN LINK        try         if  await InAppBrowser isAvailable              await InAppBrowser open snaptradeUrl                 catch  error          console error  Failed to open browser    error                 const parseUrl    url           const urlObj   new URL url       const params           urlObj searchParams forEach  value  key             params key    value              return params          return  Button onPress  openSnapTrade  Connect SnapTrade Account  Button             Native iOS  Authentication Flow    Your App     In App Browser     SnapTrade Auth     Redirect     Your App        Redirect URL Parameters  SnapTrade redirects back to your app with these parameters       Success         status SUCCESS       connection id  string     The connection ID to use for API calls      Error         status ERROR       error code  string     Error code describing what went wrong      status code  number     HTTP status code      Implementation  1  Configure URL scheme in  Info plist        swift  key CFBundleURLTypes  key   array     dict       key CFBundleURLSchemes  key       array         string yourapp  string        array      dict    array        2  Basic implementation     swift import SafariServices  class ViewController  UIViewController        func openSnapTrade             guard let url   URL string   YOUR SNAPTRADE LOGIN LINK   else   return            let safariVC   SFSafariViewController url  url           present safariVC  animated  true              In AppDelegate swift or SceneDelegate swift func application   app  UIApplication                   open url  URL                   options   UIApplication OpenURLOptionsKey   Any            Bool           Dismiss Safari View Controller     if let presented   UIApplication shared windows first  rootViewController  presentedViewController as  SFSafariViewController           presented dismiss animated  true                Parse URL     guard let components   URLComponents url  url  resolvingAgainstBaseURL  true             let queryItems   components queryItems else           return false            let params   queryItems reduce into   String  String       result  item in         result item name    item value               Handle callback     if params  status       SUCCESS          let connectionId   params  connection id             print  Connection successful     connectionId               Save connection id and proceed       else if params  status       ERROR                 let errorCode   params  error code             print  Connection failed     errorCode               Show error to user            return true       For iOS 13  with SceneDelegate func scene   scene  UIScene             openURLContexts URLContexts  Set UIOpenURLContext         guard let url   URLContexts first  url else   return          Handle URL same as above           Native Android  Authentication Flow    Your App     In App Browser     SnapTrade Auth     Redirect     Your App        Redirect URL Parameters  SnapTrade redirects back to your app with these parameters       Success         status SUCCESS       connection id  string     The connection ID to use for API calls      Error         status ERROR       error code  string     Error code describing what went wrong      status code  number     HTTP status code      Implementation  1  Configure URL scheme in  AndroidManifest xml   add to your main Activity      kotlin  activity android name   MainActivity        intent filter           action android name  android intent action VIEW              category android name  android intent category DEFAULT              category android name  android intent category BROWSABLE              data android scheme  yourapp           intent filter    activity       2  Basic implementation     kotlin import android net Uri import androidx browser customtabs CustomTabsIntent  class MainActivity   AppCompatActivity          override fun onCreate savedInstanceState  Bundle             super onCreate savedInstanceState              Handle incoming deep link         handleIntent intent             override fun onNewIntent intent  Intent             super onNewIntent intent          intent  let   handleIntent it               private fun handleIntent intent  Intent            val data  Uri    intent data          data  let   uri                val status   uri getQueryParameter  status               val connectionId   uri getQueryParameter  connection id               val errorCode   uri getQueryParameter  error code                when  status                     SUCCESS                           println  Connection successful   connectionId                          Save connection id and proceed                                    ERROR                           println  Connection failed   errorCode                          Show error to user                                                      fun openSnapTrade              val url    YOUR SNAPTRADE LOGIN LINK           CustomTabsIntent Builder              build              launchUrl this  Uri parse url                   Troubleshooting      Coinbase Mobile Authentication Issues    Problem  Coinbase uses OAuth and supports Passkeys  Google  and Apple sign in  When the portal runs inside a mobile WebView  Passkey and Google sign in often fail  WebViews impose restrictions on third party cookies  credential delegation  and embedded authentication flows  This breaks modern auth flows    Solution  We recommend using in app browser for all integrations  It s more secure and avoids problems like this    img src    assets coinbase passkey png  alt  coinbase mobile authentication  width  400        Brokerage Connectivity Issue Screen    What it looks like  Users see a connectivity warning before reaching the login page for a specific brokerage     Why it happens  SnapTrade detects degraded connectivity to that brokerage  Some users may still connect  but analytics show an unhealthy success rate    How to handle      For users  Recommend trying again later if they cannot connect      For developers  No code changes are required  This is an automatic protection against poor user experience      Brokerage Under Maintenance Screen    What it looks like  A warning that the selected brokerage is temporarily unavailable and the connection cannot proceed right now      img src    assets brokerage maintenance png  alt  brokerage maintenance screen  width  400       Why it happens      The brokerage is in scheduled or unscheduled maintenance      SnapTrade is experiencing degraded connectivity to the broker  preventing the creation of any new connections     How to handle      For users  Recommend trying again later when the maintenance window is over      For developers  No code changes required  SnapTrade automatically re enables connections when the brokerage or our service recovers  

Connection Portal

  Trading with SnapTrade  SnapTrade supports trading workflows for stocks  ETFs  other equities  options  and crypto  The exact feature set depends on the connected brokerage or exchange  so you should always  verify support  https   support snaptrade com brokerages table v e7bbcbf9f272441593f93decde660687  for the account you are about to trade with          Soft Rate Limit       We recommend limiting trade requests to   1 trade per second per account   to maximize execution success      Trading Overview  Most trading integrations with SnapTrade follow the same high level flow   1  Create or upgrade a trading enabled connection  2  Choose the brokerage account that will place the order  3  Build the order payload for the asset class you want to trade  4  Validate the order details in your application  5  Submit the order to the brokerage or exchange  6  Monitor execution status   The sections below explain how that flow differs for equities  options  and crypto      Set Up Trading Access      Create a Trading Connection  By default  connections are created with read only permissions  To create a trading enabled connection  set the  connectionType  body parameter to  trade  when calling  api Authentication loginSnapTradeUser    If you want to request trading access when it is supported  but still allow the user to connect read only accounts elsewhere  use  connectionType trade if available  instead       Enable Trading for an Existing Connection  To enable trading for an existing read only connection  ask the user to re authorize access   1  Set the  reconnect  body parameter to the ID of the existing connection  2  Set  connectionType trade  when calling  api Authentication loginSnapTradeUser   3  Direct the user to the re authorization URL that SnapTrade returns      Stocks  ETFs  and Other Equities  Use the standard trading endpoints for single leg equity orders       Typical Equity Workflow  1  Identify the account that will place the order  2  Identify the instrument using its brokerage  symbol   This is the recommended identifier when placing orders  3  Build the order details        action    BUY  or  SELL        order type   for example  Market    Limit    Stop   or  StopLimit        time in force   for example  Day  or  GTC        units  for share quantity  or  notional value  when supported 4  Validate the order details in your application before submission  5  Submit the order with  api Trading placeForceOrder    For most use cases  it is better to validate the order in your own application and then place it directly with  api Trading placeForceOrder   If you need SnapTrade to simulate the order impact before submission  you can use  api Trading getOrderImpact  and then submit the returned  tradeId  with  api Trading placeOrder   but this is usually not the primary workflow we recommend       Extended Hours Equity Trading  Extended hours trading is brokerage specific and only available when both the account and the instrument support it   To request extended hours execution     Set  trading session  EXTENDED   in the order payload    Use a  LIMIT  order with an appropriate time in force    Expect brokerage specific restrictions  Many brokerages only allow  DAY  orders for extended hours trading  while some also allow  GTC       Options  SnapTrade supports both single leg option orders and multi leg option strategies  but support is narrower than it is for equities       Single Leg Option Orders  Single leg option orders use the same endpoint as multi leg option orders  but with a single leg   1  Build the order for  api Trading placeMlegOrder   providing only a single leg  2  Provide  instrument symbol  with an  OCC format  https   en wikipedia org wiki Option symbol OCC format   3  Use an option action such as  BUY TO OPEN    BUY TO CLOSE    SELL TO OPEN   or  SELL TO CLOSE   4  Set  units  to the number of option contracts  5  Validate the order details in your application and submit the order with  api Trading placeMlegOrder    This is the right workflow for straightforward option buys and sells where the order has only one leg       Multi Leg Option Strategies  For spreads  condors  and other multi leg strategies  use  api Trading placeMlegOrder    The multi leg payload lets you submit     an  order type    a  time in force    a  price effect  such as debit or credit   a  legs  array containing the option instruments  actions  and contract quantities  Because brokerages often report each leg separately  downstream order history can appear as multiple records for a single multi leg submission      Crypto  SnapTrade supports specialized crypto trading endpoints for some exchanges such as Kraken  Binance  and Coinbase   Crypto trading uses tradable asset pairs represented as  BASE QUOTE   The action determines the direction of the trade     On a  BUY   the base asset is what you are buying and the quote asset is what you are spending    On a  SELL   the base asset is what you are selling and the quote asset is what you are receiving       Typical Crypto Workflow  1  Use  api Trading searchCryptocurrencyPairInstruments  to find the tradable pairs for the connected account  2  If needed  filter by  base  or  quote  because exchanges can support different pairs and sometimes different tickers for the same asset  3  Use  api Trading getCryptocurrencyPairQuote  to retrieve a quote for the pair  Quote values are returned in units of the quote asset  4  Validate the order details in your application  5  Submit the order with  api Trading placeCryptoOrder    When placing a crypto order  set the  instrument symbol  to the trading pair and the  instrument type  to  CRYPTOCURRENCY PAIR   The  amount  is the quantity of the base asset to buy or sell   For most crypto integrations  validating the request in your own application is simpler than relying on the preview endpoint  If you need an exchange side preview   api Trading previewCryptoOrder  is available      json      account id      accountId        instrument          symbol    ETH EUR        type    CRYPTOCURRENCY PAIR          side    BUY      type    MARKET      amount    0 01      time in force    GTC      post only   false        In this example  the order buys  0 01  ETH with EUR      Brokerage Support and Reconciliation  Not every brokerage supports every trading workflow  Extended hours sessions  multi leg options  and crypto trading are all institution specific  Review the  SnapTrade Brokerage Support Matrix  https   support snaptrade com brokerages table v e7bbcbf9f272441593f93decde660687  before enabling a feature in production   After placing an order  we recommend you reconcile the latest state by pulling a list of recent orders with  api AccountInformation getUserAccountRecentOrders   

Trading with SnapTrade

  Best practices to serve up real time data  SnapTrade offers the ability to get real time data on both real time  including Pay as you go  and cached plans  Real time requests are enabled by default on all non custom plans  See  our pricing page  https   snaptrade com pricing  for more information on plans      Real time Plan  Pay as you go   The best practice for showing users accurate data on a real time plan is to update your user s state when they log in to your app  You can do this by making API calls to the resources you need  commonly   positions  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountPositions     options  https   docs snaptrade com reference Options Options listOptionHoldings     balances  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountBalance   Repeat this process every 5 minutes while the user remains active in your application      Cached Plan  On the cached plan  SnapTrade will update your data once a day  To get real time data we recommend calling  the manual refresh endpoint  https   docs snaptrade com reference Connections Connections refreshBrokerageAuthorization  to update the data  SnapTrade will begin a sync and notify you via  ACCOUNT HOLDINGS UPDATED  https   docs snaptrade com docs webhooks webhooks account holdings updated  webhooks when each account has finished syncing  at which point you can call   positions  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountPositions     options  https   docs snaptrade com reference Options Options listOptionHoldings     balances  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountBalance  for each account  If you expect your users to want intraday updates  it is a good idea to give the option of a refresh button that lets the user refresh their data in the same way  Note that calls to the Refresh endpoint will incur additional charges according to your plan      Get notified when users place trades at their broker  If you need to know when a trade has been placed by a specific user  the recommendation is to poll the  Recent Orders endpoint  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountRecentOrders   only during market hours  This endpoint defaults to returning the last day of executed orders  Keep a copy of this list on your end  and check if a new order is present in the polling responses  To avoid SnapTrade and institution rate limits  we recommend polling once every 10 seconds per account      Transactions Please see  our guide on Syncing and Data Freshness  https   docs snaptrade com docs syncing  for more information about transactions     Relevant Endpoints    List account positions  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountPositions    List account option positions  https   docs snaptrade com reference Options Options listOptionHoldings    List account balances  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountBalance    List account orders  all   https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountOrders    List account recent orders  for polling   https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountRecentOrders    Get account detail  total account value   https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountDetails  

Best practices to serve up real-time data

  Webhooks  The SnapTrade API can be configured to send you webhook notifications when certain events happen   To get started with webhooks  visit the webhook tab of the SnapTrade Dashboard to configure a webhook listener     Verifying Webhook Authenticity    Note  Webhook secrets are deprecated   You can verify the authenticity of any SnapTrade webhook by using the  Signature  header contained in the webhook headers  and comparing that to the expected signature generated using your   client secret    Note that the client secret is different from the webhook secret that is being deprecated   The  Signature  header contains an HMAC SHA256 hash of the request body  using your client secret as the key   Here s an example implementation of a Flask webhook handler that verifies the authenticity of incoming webhooks      python from base64 import b64encode from hashlib import sha256 import datetime import hmac import json import os from flask import Flask  request  jsonify  app   Flask   name     SECRET   os getenv  SNAPTRADE CLIENT SECRET     app route      methods   POST    def webhook listener          Extract the payload     payload   request get json          Extract the Signature header     signature   request headers get  Signature          Verify the signature     sig content   json dumps payload  separators             sort keys True      sig digest   hmac new SECRET encode    sig content encode    sha256  digest       calculated signature   b64encode sig digest  decode        if calculated signature    signature          raise Exception  Signature verification failed               Prevent replay attacks by checking the timestamp and making sure it was sent recently     timestamp   datetime datetime fromisoformat payload  eventTimestamp        if  datetime datetime now datetime timezone utc    timestamp  total seconds     300          raise Exception  Payload is too old         print  Signature verified successfully           Log the received data     print  Received payload    payload         Respond with a success message     return jsonify      200  if   name         main         app run host  0 0 0 0   port 5123       Aside from signature verification     SnapTrade supports custom webhook request headers  which are useful if your webhook handler is protected by Cloudflare    SnapTrade does not support IP whitelisting at this time    Handling Undeliverable Webhooks  When your webhook handler responds to our requests with a status code that is not 200  201  202  or 204  we mark that webhook as undelivered in our system   We will attempt to resend an undeliverable webhook notification with an exponential backoff  starting at 30 minutes  until it is either delivered successfully  or 3 retry attempts have been made     Webhook Types  The different webhook event types are outlined below      USER REGISTERED  Sent when a new user is successfully registered through the   registerUser   endpoint   Example payload is below      json      webhookId    dbaee13a 1184 4677 9741 b6845e60ee3a      clientId    phjBdpKfpN      eventTimestamp    2022 05 31T11 16 54 658533 00 00      userId    qQYISR9xcmR8ZtVHNgg1lbYgSQcxafPqPW0ZbE0yaA6ham6n54      eventType    USER REGISTERED      webhookSecret    lgCQWztweEFcHvjdLhHc            USER DELETED  Sent when a user is successfully deleted through the   deleteUser   endpoint   Example payload is below      json       userId   TOD1ACWHxnO9cnpq9XgNmFaRwXRMRu2taaFPpvYi6ng3uD2UN9       clientId   phjBdpKfpN       eventType   USER DELETED       webhookId   dbaee13a 1184 4677 9741 b6845e60ee3a       webhookSecret   lgCQWztweEFcHvjdLhHc       eventTimestamp   2025 01 08T14 32 59 979214 00 00            CONNECTION ATTEMPTED  Sent when a user a user attempts to make a brokerage connection  will also report the result of the attempt   Example payload is below      json      webhookId    6594d898 7377 453b 989e 03545ebde8bf      clientId    kqLsLciREm      eventTimestamp    2022 05 31T11 17 17 804976 00 00      userId    TOD1ACWHxnO9cnpq9XgNmFaRwXRMRu2taaFPpvYi6ng3uD2UN9      eventType    CONNECTION ATTEMPTED      connectionAttemptedResult    SUCCESS      brokerageId    c8153291 0761 43a8 8ed0 4642103c2cb8      webhookSecret    PajFGRsWwxgckkOZwteW         Possible values for the  connectionAttemptedResult  field are      SUCCESS     AUTH EXPIRED     INVALID AUTH CODE     AUTH NOT IN PROGRESS     DIFFERENT ACCOUNT     UNCAUGHT ERROR     INVALID CREDENTIALS     INVALID MFA CODE     NO DATA      CONNECTION ADDED  Sent when a new brokerage connection is created using the SnapTrade connection portal   Example payload is below      json      webhookId    7467e5e4 4b59 4514 9d04 d05dbc10dea9      clientId    cJEQQgtDIb      eventTimestamp    2022 05 31T11 13 37 269120 00 00      userId    oWbLZ3OWsO3Nt8DKJnYxM32wLLD6h6SVj0ywkDmypUlkWkqsI5      eventType    CONNECTION ADDED      brokerageId    c8153291 0761 43a8 8ed0 4642103c2cb8      brokerageAuthorizationId    a0231bd2 9b77 4732 ba78 f9c6af6a1a62      webhookSecret    ZSDkaLCRJndeZGgeaJnV            CONNECTION DELETED  Sent when a user deletes an existing connection using the SnapTrade connection portal   Example payload is below      json      webhookId    85a63984 6fb6 45fb bc3b 18582a89ab3c      clientId    gxKWQEIXGS      eventTimestamp    2022 05 31T11 35 33 753881 00 00      userId    a053epCMsmII9goant5wdQH7CaT0M00HgQiRaxWnK0MncDUF2c      eventType    CONNECTION DELETED      brokerageId    c8153291 0761 43a8 8ed0 4642103c2cb8      brokerageAuthorizationId    a0231bd2 9b77 4732 ba78 f9c6af6a1a62      webhookSecret    lbTycRhXwzVRJPovdNSN            CONNECTION BROKEN  Sent when a user s connection is broken  also referred to as disabled  for some reason  usually an inability to handshake with the brokerage s API  To resolve this state  see  Fix Disabled Connections  https   docs snaptrade com docs fix broken connections    Example payload is below      json      webhookId    434d23af 5f89 44f8 9415 5029557e64c7      clientId    yLNANjmwau      eventTimestamp    2022 05 31T11 37 50 590720 00 00      userId    DbjLqtPsj6G1MlDLtZaps4YhtckD0jWOuLQjl6GPW4FmpUa8eo      eventType    CONNECTION BROKEN      webhookSecret    SCNsZYmJcuXRiznplDdL      brokerageAuthorizationId    dc90a844 367b 4120 8b56 21040bfa6525            CONNECTION FIXED  Sent when a broken  disabled  connection is fixed   Example payload is below      json      webhookId    ae73c055 2308 4de4 bf0e d828bbac8c91      clientId    BVmifPEScc      eventTimestamp    2022 05 31T11 52 26 803063 00 00      userId    EKDO7W7YSWEZkOZUN5v1iMGF7ipEmOGjc6bMEm89y6vCrtnebH      eventType    CONNECTION FIXED      webhookSecret    zNKlROkqSEXjXBxfTsAu      brokerageAuthorizationId    5e942e13 2b39 47b2 b524 858b9d9849ed            CONNECTION UPDATED  Sent when a brokerage connection is updated   Example payload is below      json      webhookId    57a293e4 f7eb 49ad 92e2 80ac16e01af7      clientId    IZtBuuKXEA      eventTimestamp    2022 05 31T11 53 09 437310 00 00      userId    sXQQcRdQEmGSMizpv45gBlBANBeCWgEn9uSmLlEpa1YsZ7oAW8      eventType    CONNECTION UPDATED      webhookSecret    oHdlCBoExKtosDtTLVDc      brokerageAuthorizationId    7ed55083 7128 46ff 9317 43cd788f43ff            CONNECTION FAILED  Sent when a user s attempt to connect to a brokerage has failed   Example payload is below      json      webhookId    57a293e4 f7eb 49ad 92e2 80ac16e01af7      clientId    IZtBuuKXEA      eventTimestamp    2022 05 31T11 53 09 437310 00 00      userId    sXQQcRdQEmGSMizpv45gBlBANBeCWgEn9uSmLlEpa1YsZ7oAW8      eventType    CONNECTION FAILED      webhookSecret    oHdlCBoExKtosDtTLVDc            NEW ACCOUNT AVAILABLE  Sent when a new account is detected through a brokerage connection   Example payload is below      json      webhookId    6fe03e8c 201a 4c3f 92d0 acb825fc89cf      clientId    SjWLDemQUF      eventTimestamp    2022 05 31T12 37 18 630476 00 00      userId    hmznAjmLezKPaSnLIiNQweSGsf7MIlEvm9dcTao3gwjgBtulLK      eventType    NEW ACCOUNT AVAILABLE      webhookSecret    HZRnYEhLPgwyUXitkJBd      accountId    ec20134b 72e7 4e72 9b4c 9c7ddd1c479c      brokerageAuthorizationId    795de4e6 260e 45b3 815b 8f601c4cf448            ACCOUNT TRANSACTIONS INITIAL UPDATE  Sent when we complete the initial transactions sync after a new account is connected  The duration needed for the first sync can vary by brokerage and by how many historical transactions the user has  but usually takes between 1 60 seconds   Example payload is below      json      webhookId    aa7a7d5a 4a12 40df a329 feedc738eee9      clientId    rmCZBUGAXP      eventTimestamp    2022 05 31T12 39 47 182403 00 00      userId    7jN22b2AWHMOqOeujjaiU5kKOM8iITt11ENcUMftx6LBg9GTn2      eventType    ACCOUNT TRANSACTIONS INITIAL UPDATE      webhookSecret    gQNuZIBwPYUVAsXvCfOA      accountId    d9f55a48 5dc6 4100 acee 24e5dfd8ec26      brokerageAuthorizationId    d28affae f918 4ecd 8128 e5438e861706            ACCOUNT TRANSACTIONS UPDATED  Sent when account transactions are incrementally updated  After the initial sync has already completed  account will be checked for new transactions daily  If new transactions are found they will be saved and this webhook will be sent  Only ACCOUNT TRANSACTIONS INITIAL UPDATE gets sent upon first connection   Example payload is below      json      webhookId    4eb13e1c 5778 44c2 968d 813d81cb73a1      clientId    JELZRJPqui      eventTimestamp    2022 05 31T12 40 05 944481 00 00      userId    4XTxw0mZhffRCdrgPHBG1VqdklkVJdEz5Uor0hq29hwPYlLS7s      eventType    ACCOUNT TRANSACTIONS UPDATED      webhookSecret    DDAVBuPPGgqwADXgbcOE      accountId    6e30be12 4ab0 4ec0 8d4d 0dfdce509e36      brokerageAuthorizationId    8105b33e 3dd6 4189 b93e 31ccaa9d3b69            ACCOUNT REMOVED  Sent when an account is removed from a connection   Example payload is below      json      webhookId    60b9ad5f 9e78 43b2 af5a 8ce8412b1cd6      clientId    PARTNERAPP      eventTimestamp    2024 05 31T12 40 05 944481 00 00      userId    4XTxw0mZhffRCdrgPHBG1VqdklkVJdEz5Uor0hq29hwPYlLS7s      eventType    ACCOUNT REMOVED      webhookSecret    DDAVBuPPGgqwADXgbcOE      accountId    6e30be12 4ab0 4ec0 8d4d 0dfdce509e36      brokerageAuthorizationId    8105b33e 3dd6 4189 b93e 31ccaa9d3b69            ACCOUNT HOLDINGS UPDATED  Gets sent when holdings for an account has been updated  Updated does not necessarily mean that the holdings have changed  instead it means that updating holdings with new data has been attempted  In the rare case that a holdings update fails  for example when a brokerage s API is down for maintenance   the webhook will still be sent and details on what failed will be included as part of the details field in the body   This webhook will be sent when we run our daily account syncs  as well as if a manual account refresh has been requested via  https   docs snaptrade com reference Connections Connections refreshBrokerageAuthorization  Account Holdings in this context refers to     Positions    Balances    Orders    Total Account Value    Account Detail  Historical transactions will be polled for  but will not fetch transactions from the current day  Example payload is below     json      userId    60b9ad5f 8e78 43b2 af5a 8ce8412b1cd6      clientId    PARTNERAPP      accountId    45a3g56a eef6 4904 a68e d3f90c3e07c5      eventType    ACCOUNT HOLDINGS UPDATED      webhookId    312a13f3 3929 46dd a70f ade6aaefc100      brokerageId    905872ac a7b1 4031 a31f 790cba1bfc94      webhookSecret    yfqvPlWrTFILBcjCERPh      eventTimestamp    2024 03 01T14 38 13 111991 00 00      brokerageAuthorizationId    6bb1ahb0 b8c8 4b59 8bf9 7841d7a89c63      details          total value      success   true   error   null         positions      success   true   error   null         balances      success   true   error   null         orders      success   true   error   null             

Webhooks

  Ratelimiting  The SnapTrade API uses a number of safety mechanisms to protect against bursts of incoming traffic and help maximize its stability   Sending many requests in quick succession might trigger error responses that show up as HTTP status code 429   Every SnapTrade client is ratelimited to 250 requests per minute by default  If you have a large number of users and would like to request a higher ratelimit  please contact your Customer Success Manager      Keeping Track of Your Ratelimit  The SnapTrade API returns several helpful response headers that you can use to keep track of your ratelimit usage      X RateLimit Limit   the maximum number of requests you can make in a given minute    X RateLimit Remaining   the number of requests remaining in the current minute    X RateLimit Reset   the number of seconds until the next minutely ratelimit resets  These are rolling limits that look at the trailing 60 seconds      Common Causes and Mitigations  There are a number of situations that may cause your ratelimiting to kick in  Here are a few scenarios and suggested mitigations       Aggressive syncs    syncing user portfolios all at once will increase the chance that you hit your ratelimit threshold  To avoid 429s  these data syncs should be spaced out over a period of time      Increased user signup volumes    for example if you make an announcement to your users that a new integration is available with SnapTrade  To prevent hitting ratelimits  it is prudent to space out these requests so users onboard over a period of time      Best Practices for Handling 429s  You should add logic to your integration to watch for  429  responses from our API  and handle them with a retry mechanism   The retry mechanism should use exponential backoff  and ideally have some randomness to prevent  thundering herd problems  https   en wikipedia org wiki Thundering herd problem   

Ratelimiting

  Launching your Application  Before you launch to production with the SnapTrade API  you should conduct a pre production implementation review  This ensures you ll have a successful launch and provide a great end user experience   The goal of this review is to     Enhance both your experience as a SnapTrade user and your end users  app experience   Prevent and minimize common pitfalls   Understand and optimize your needs and use cases  while identifying potential product gaps   Ensure a smooth product launch     The Pre Launch Checklist      1  SnapTrade Compliance Policy  You have read the  SnapTrade Compliance Policy  https   snaptrade com compliance policy  and your application is in compliance       2  App Profile  In order to generate your paid keys  you will need to have your app profile filled in the SnapTrade Dashboard  This app profile will add your logo to the connection portal also be used to get you access to certain OAuth integrations like Fidelity       3  API polling patterns  You don t call the Holdings API more than 4 times per day per user in the background  or more frequently than once per end user login and at set intervals while the user is actively using your app    You don t call the activities  transactions  endpoint more than once per account every 24 hours for an account   If you run a daily job to pull data  you spread the calls out as much as possible over the period     If your app uses webhooks  you poll the API correctly  using the proper endpoint and payload data  in response to the specific webhook type received       4  User Onboarding  You should have a user onboarding flow that handles registering a SnapTrade user and storing the generated user secret    SnapTrade allows read only access or trading access for brokerage connections  Making the user explicitly decide as part of the authentication flow helps them understand the nature of the connection they re creating  and ensures a good user experience       5  Users can View and Delete their Connections  The ability to view and delete existing connections is critical to allow users to manage their authorizations  and to stay compliant with GDPR and privacy guidelines   The following endpoints have the information you need for this      api Connections listBrokerageAuthorizations     api Connections removeBrokerageAuthorization       6  Handle Disabled Connections  You have a system for detecting disabled end user brokerage connections  via webhook  and a defined re connection flow to fix broken connections  This includes at least one method of detection and one way to notify users  such as in app notifications or emails    See  How to Fix Broken Connections  https   docs snaptrade com docs fix broken connections       7  New Integrations  You have a strategy for handling newly released integrations  If you are making use of the  broker  parameter when calling  api Authentication loginSnapTradeUser   you will need to manually add any new brokerage integrations that are released  If you are not using this parameter  newly released integrations will appear automatically in the Connection Portal  You can call  api ReferenceData getPartnerInfo  to stay up to date  This returns the configuration for your Clint ID  including allowed brokerage integrations and data access       8  Rate limiting  You are aware of the general rate limit and have a way of gracefully handling rate limit 429 errors in your app  If you re using trading functionality  you re not executing trades faster than 1 trade per connected account per second   See  Ratelimiting  https   docs snaptrade com docs ratelimiting        9  Trading  If you re using trading functionality  you must have either clear user consent for automated trading or a trade preview flow that shows all expected fees and commissions  Users must also have the ability to opt out of SnapTrade functionality and delete their brokerage connection at any time  It s recommended to not execute trades faster than 1 trade per connected account per second   See  Trading with SnapTrade  https   docs snaptrade com docs trading with snaptrade        10  Webhooks  You have set your webhook listener URL in the  SnapTrade Dashboard  https   dashboard snaptrade com       Next Steps    Get your Production Keys through the  SnapTrade Dashboard  https   dashboard snaptrade com    Reach out to us at  support snaptrade com  mailto support snaptrade com  or over  Discord  https   discord gg UDwzZUuQ  

Launching your Application

  Sending Requests  When sending requests to SnapTrade  we recommend using an SDK  You can also send requests directly through the API reference on this site  this is especially useful for managing users and connections during development      SDKs  It is possible to integrate without an SDK  but will require you to lift the signing code from one of our SDKs for making requests  SnapTrade provides the following SDKs for you to use       Language       SDK Link                     Python      https   pypi org project snaptrade python sdk    https   pypi org project snaptrade python sdk      TypeScript      https   www npmjs com package snaptrade typescript sdk    https   www npmjs com package snaptrade typescript sdk      Java      https   central sonatype com artifact com snaptrade snaptrade java sdk    https   central sonatype com artifact com snaptrade snaptrade java sdk      Ruby      https   rubygems org gems snaptrade    https   rubygems org gems snaptrade      C       https   nuget org packages SnapTrade Net    https   nuget org packages SnapTrade Net      PHP      https   packagist org packages konfig snaptrade php sdk    https   packagist org packages konfig snaptrade php sdk      Go      https   pkg go dev github com passiv snaptrade sdks sdks go    https   pkg go dev github com passiv snaptrade sdks sdks go        Ratelimiting  The SnapTrade API uses a number of safety mechanisms to protect against bursts of incoming traffic and help maximize its stability   Sending many requests in quick succession might trigger error responses that show up as HTTP status code 429      Response Headers      x request id  Each SnapTrade API request has an associated request identifier  If you need to contact us about a specific request  providing the request identifier is helpful to ensure the fastest possible resolution       x ratelimit limit  With each request  you will receive your ratelimit as a header  This denotes how many requests you can make in one minute before being throttled       x ratelimit remaining  Within each request  you will receive how many requests are remaining until SnapTrade begins throttling your requests         See also     Ratelimiting  https   docs snaptrade com docs ratelimiting     Request IDs  https   docs snaptrade com docs request ids  

Sending Requests

  Brokerage Integrations  SnapTrade supports opening connections to 20  financial institutions around the world  Sometimes a single institution can have multiple integrations depending on geography or account type  For example we support Webull USA and Webull Canada as two distinct integrations  Similarly  Alpaca and Alpaca Paper are two distinct integrations despite belonging to the same company  For in depth information on each brokerage that we support  please refer to  SnapTrade Brokerage Integrations  https   support snaptrade com brokerages   

Brokerage Integrations

  Connections  A connection is an open channel for you to access the account data of your end users  Each connection is associated one to one with a set of credentials to an institution  If the access token for the connection is no longer valid  the connection will become disabled and the end user will need to go through the connection portal again to enable the connection      Connection Portal  The Connection Portal is a UI widget designed to allow end users to securely connect their brokerage accounts to your app  It handles brokerage selection  OAuth redirects  username password authentication  and multi factor auth verification in one flow      Disabled Connections  Connections can break for a variety of reasons  which are usually related to security needs  Access tokens usually have some sort of expiry associated with them  so that users occasionally need to reauthorize access in order to show that they still approve of the connection  Access tokens typically expire after a few weeks and need to be reauthorized occasionally   When an access token is no longer valid  SnapTrade considered this to be a  disabled connection  which will no longer provide live data until it is repaired by the user        See also     Fix Broken Connections  https   docs snaptrade com docs fix broken connections     Integrate the Connection Portal into Your Application  https   docs snaptrade com docs implement connection portal implement connection portal integrate the connection portal into your application  

Connections

  Account Data  An account represents a unique account at a brokerage  like an individual account  or a 401k retirement account  A connection can have multiple accounts  The same brokerage account can also belong to multiple connections  For example a joint account between two individual account holders are visible under each account holder s connection  With a connected account  you can call any SnapTrade account data API to get information about the account  its holdings  and its history      Account Details   api AccountInformation getUserAccountDetails   The account object contains information such as the institution name  the sync status of the account and the total market value of the account      Positions   api AccountInformation getUserAccountPositions   api Options listOptionHoldings   Positions are the current holdings of the account excluding cash  This includes many asset classes such as stocks  ETFs  and fixed income      Balances   api AccountInformation getUserAccountBalance   Balances are the current cash holdings and buying power of the account  In some cases  brokerages will allow holding many currencies in an account and these will be returned as separate balances      Orders   api AccountInformation getUserAccountOrders   api AccountInformation getUserAccountRecentOrders   Orders are how a broker keeps track of trading activity in an account  This differs from account activities in the following ways     Is updated intraday   Contains all orders placed at the broker regardless if they resulted in a change in position  including cancelled orders and pending orders   Often has more granular timestamps than account activities   Only looks back a few months at most     Activities   api AccountInformation getAccountActivities   Activities record the transaction history for the account  Each activity documents a change in position for the account  including deposits  withdrawals  fees  dividends  buys and sells  This differs from Orders in the following ways     Activities are updated once daily   Activities may not have timestamps of when the transaction occurred  only the date    Activities only contain transactions that resulted in a change of position to the account  no pending or cancelled orders   Often has years of history for the account  sometimes the entire account history since inception  SnapTrade classifies common transactions under the predefined types  with extra focus on what we consider the most important types  buys  sells  contributions  dividends  withdrawals  etc   When we encounter a transaction with a type that doesn t fit into one of our common types  we will return the type that the brokerage uses to identify it   We usually recommend you try not to individually handle every type beyond the most common ones  and instead rely on the other fields  amount  units  price  symbol  option symbol  etc  If amount is positive it represents gaining cash  if amount is negative it represents spending cash  Same with units  so a BUY for instance would have positive units and negative amount  a sell would be negative units positive amount   Check  our API Spec  https   docs snaptrade com reference Account 20Information AccountInformation getAccountActivities  for some of the most common transaction types        See also     Webhooks  https   docs snaptrade com docs webhooks     Getting Started with SnapTrade  https   docs snaptrade com docs getting started  

Account Data

  Syncing and Data Freshness  It s first important to understand whether you are on the realtime or cached data plan which you can find in  the dashboard  https   dashboard snaptrade com settings billing   Note that  if the connection is disabled  https   docs snaptrade com docs fix broken connections   fresh data cannot be fetched on either plan until the connection is fixed  SnapTrade syncs account data at least once per connection per day  these syncs are spread over 24 hours and update transactions as well as holdings data   Real Time Plan  holdings  positions  balances  orders  are fetched with every API request   Cached Plan  holdings are updated once per day with the daily sync   For both plans  transactions are cached  updated once per day with the daily sync  and delayed by one day  no intraday transactions   compare orders to transactions here  https   docs snaptrade com docs account data account data orders  if you need realtime trades    If you need to know when transactions  and holdings data on cached plans  are synced  there are two methods   Webhooks     ACCOUNT TRANSACTIONS UPDATED  https   docs snaptrade com docs webhooks webhooks account transactions updated  webhook will be sent when we create a new transaction for an account  Note that no webhook will be sent if we sync transactions and no new data is found     ACCOUNT HOLDINGS UPDATED  https   docs snaptrade com docs webhooks webhooks account holdings updated  will be sent once per day when holdings are updated  regardless of if data changes or not   This is only really helpful for cached plans since realtime plans will update brokerage data with each request   API Account Status     List accounts endpoint  https   docs snaptrade com reference Account 20Information AccountInformation listUserAccounts  will return a  sync status  object which will tell you when the daily sync last ran for holdings  as well as the last day that transactions   have been fully synced    transactions have been pulled from 00 00 to 23 59           sync status            transactions              initial sync completed   true           last successful sync    2022 01 24            first transaction date    2022 01 24                  holdings              initial sync completed   true           last successful sync    2024 06 28 18 42 46 561408 00 00                        If on the cached plan and a holdings update is needed  you can call  the Refresh connection endpoint  https   docs snaptrade com reference Connections Connections refreshBrokerageAuthorization   Please note that additional charges may apply to each of these calls  you can find pricing information in  the dashboard  https   dashboard snaptrade com settings billing    If looking to control at what time of day transactions are updated  please reach out to the team about  a custom plan  https   snaptrade com pricing   

Syncing and Data Freshness

  Request IDs  Each SnapTrade API request has an associated request identifier   You can find this value in the response headers  under  X Request ID   For example  running a simple  curl  request and glancing at the headers for the response will give something like this       curl  v https   api snaptrade com api v1         date  Fri  13 Oct 2023 00 32 06 GMT   content type  application json   content length  71   server  gunicorn   vary  Accept  DNT  origin  Cookie   allow  GET  HEAD  OPTIONS   x frame options  DENY   x request id  27fcf193c58c4a646aa9fd90e833ab29   x content type options  nosniff   referrer policy  same origin   cross origin opener policy  same origin      If you need to contact us about a specific request  providing the request identifier will ensure the fastest possible resolution  

Request IDs

  Fix Disabled Connections  A SnapTrade connection provides direct access to a user s trading account  When an access token is no longer valid  SnapTrade considered this to be a  disabled connection  which will no longer provide live data until it is repaired by the user     Required Functionalities  It is important that users are directed to  fix connections  rather than they create new ones  This allows you to provide a better experience to the user  minimize the number of disabled connections you are managing  and retain historical session data  Using the Connection Portal in the normal manner will create new connections  which will have a different connection id and different account ids if successful  as well as will leave the disabled connection to remain   It is a requirement to implement the ability to reconnect so that connections can be fixed  There are mechanisms available to be notified when connections break  either through a   webhooks   docs webhooks  as described below  or b  by polling the brokerage authorizations endpoint   api Connections listBrokerageAuthorizations   for each user and checking the  disabled  status  When  disabled    true   the connection is disabled and the user must take an action to fix it     How to fix a disabled connection  SnapTrade s Connection Portal has a special mode that s designed for fixing connections  rather than creating new ones  To use the reconnect mode  you simply pass along the connection id  also known as brokerage authorization id  in the  reconnect  field as part of the request to generate a login link  See  api Authentication loginSnapTradeUser    When the Connection Portal is accessed with the  reconnect  parameter  it will immediately take the user into the appropriate reconnection flow for that connection  When successful  the disabled connection will be updated with a new access token and start working again   Note  It is important that the user logs into the same brokerage connection when attempting to reconnect  Changing the connection in a reconnect is not permitted and will return an error  If the user wishes to change the connection  they should delete the old connection and create a new one to the new trading account     Webhooks  SnapTrade provides webhooks to notify when new connections are     Attempted   Added   Updated   Deleted   Broken   Fixed  If you have a webhook listener URL associated with your SnapTrade account  you will automatically receive webhook events to let you know when any of those events take place  This is especially useful for noticing when connections break so that you can inform the user that they need to reconnect   Review the documentation on  SnapTrade Webhooks   docs webhooks  for more detail  sample payloads  etc  

Fix Disabled Connections

  Frequently Asked Questions     API Keys      I have lost the consumerKey to my API Key  What should I do   You should reach out to SnapTrade support  If it is compromised  your users are still safe due to also requiring a user secret to get account data or place trades           Requests      I am getting a  Unable to verify signature sent  error when making a request to the API  What should I do   The API call is failing when comparing the expected signature to the signature provided by your client  This can happen for many reasons  but is likely caused by attempting to configure the signature without an SDK  or an invalid consumerKey  If you need to reset your consumerKey  reach out to someone in SnapTrade staff           Users      What is a  Connected User    A connected user is a user who has at least one connection  If someone connects both a Wealthsimple Trade and Questrade account  then that person will be counted as one connected user  Similarly if they have multiple accounts  IRA and margin  at one broker  then that s also counted as one connected user   A user is considered a connected user from the moment they successfully complete the first connection process to when you or the user deletes their last connection  some times users have multiple brokers connected   You can handle this on your end or let the users delete the connections from your platform       What should I do if I lose the userSecret of one of my users   If you lose the userSecret the easiest thing to do is create a new user and ask the end user to reconnect         The userSecret to one of my SnapTrade users has been compromised  What should I do     The best thing to do in this case is to rotate the user secret using  api Authentication resetSnapTradeUserSecret            Connections      What is the format of   disabled date     All of our timestamp fields return datetime in ISO 8601 format       What is the difference between an account and a connection     image png    assets 250312 model png   The accounts live under the connection to the brokerage  Each connection is associated one to one with a set of credentials to the brokerage  When you create a connection  SnapTrade will automatically sync all accounts under the set of credentials to the brokerage  For example  if you made a new connection to Questrade  a Canadian brokerage  and that connection had a TFSA  an RRSP and an FHSA account under those credentials  SnapTrade would make all these accounts accessible over the SnapTrade API       If I want to remove an account do I need to delete the connection   If you want to remove an account  you will need to delete the corresponding connection  You can do this using  api Connections removeBrokerageAuthorization        If I delete connection  will it delete all accounts from that Connection  Can I delete only one account   Deleting the connection will remove all accounts under that connection  Instead of deleting individual accounts  you could mark them as hidden on your end and only pull information from accounts that are not hidden       How can I force a connection to become disabled for testing   You can do this with the  api Connections disableBrokerageAuthorization  endpoint       How do I enable connecting to  X  broker on my API Key   By default  all brokers which can be enabled for you are enabled  For now  broker configuration is done manually on our end  Certain brokers require an application to enable the integration  Alpaca  Tradier  Tradestation  Questrade  Fidelity   Please reach out if you need access to one of these           Account Information      What kind of accounts does SnapTrade support   We support all kinds of accounts and it is brokerage dependent  In general  if the brokerage returns it to us  we will return it over the API  You can refer to the  SnapTrade Broker Support Matrix  https   support snaptrade com brokerages  and the field will be returned over the  raw type  on the account object       How do I determine if an activity indicates the position was bought or sold   If the activity resulted in a gain in position to the account  long   the activity will have a positive unit  If the activity resulted in a loss of position to the account  short   the activity will have a negative unit       Is it possible to know a stock s first purchase date   Determining a stock s first purchase date varies by brokerage  Two key requirements must be met   1  The brokerage must provide activities or transaction data that includes historical buy sell records  2  The brokerage must include complete transaction history in the account data   Some brokerages have data retention limits for example  Schwab only provides up to 4 years of historical data  You can check this here  SnapTrade Broker Support Matrix  https   support snaptrade com brokerages       When does account data get synced daily   It is not consistent at the same time every day  but guarunteed once per day       My account data is stale  why is my account not syncing every day   The connection is probably disabled  this happens when the access token is no longer valid  Please check using the  api Connections detailBrokerageAuthorization  and follow  this guide  https   docs snaptrade com docs fix broken connections  to repair the connection       How can I tell the difference between asset classes   Each symbol will have a  type  property  This will contain a short code representing the security type  For example   cs  for Common Stock  Here are some common values    ad    ADR  bnd    Bond  cs    Common Stock  cef    Closed End Fund  crypto    Cryptocurrency  et    ETF  oef    Open Ended Fund  ps    Preferred Stock  rt    Right  struct    Structured Product  ut    Unit  wi    When Issued  wt    Warrant          Trading      Is there a comprehensive list of symbol IDs that I can use for submitting trades   A symbol is not guaranteed to be stable  Since a stock is able to be traded on multiple exchanges  you should get the symbol with  api Trading getUserAccountQuotes  at the time you want to place the trade       

Frequently Asked Questions

Check whether the API is operational and verify timestamps.

Get API Status

Returns a list of all registered user IDs. Please note that the response is not currently paginated.

List all users

Registers a new SnapTrade user under your Client ID. A user secret will be automatically generated for you and must be properly stored in your system.
Most SnapTrade operations require a user ID and user secret to be passed in as parameters.


Register user

Deletes a registered user and all associated data. This action is irreversible. This API is asynchronous and will return a 200 status code if the request is accepted. The user and all associated data will be queued for deletion. Once deleted, a `USER_DELETED` webhook will be sent.

Delete user

Authenticates a SnapTrade user and returns the Connection Portal URL used for connecting brokerage accounts. Please check [this guide](/docs/implement-connection-portal) for how to integrate the Connection Portal into your app.

Please note that the returned URL expires in 5 minutes.


Generate Connection Portal URL

Rotates the secret for a SnapTrade user. You might use this if `userSecret` is compromised. Please note that if you call this endpoint and fail to save the new secret, you'll no longer be able to access any data for this user, and your only option will be to delete and recreate the user, then ask them to reconnect.


Rotate user secret

Returns configurations for your SnapTrade Client ID, including allowed brokerages and data access.

Get Client Info

**Deprecated, please use the account-specific holdings endpoint instead.**

List all accounts for the user, plus balances, positions, and orders for each
account.


List all accounts for the user, plus balances, positions, and orders for each account.

Returns a list of balances, positions, and recent orders for the specified account. The data returned is similar to the data returned over the more fine-grained [balances](/reference/Account%20Information/AccountInformation_getUserAccountBalance), [positions](/reference/Account%20Information/AccountInformation_getUserAccountPositions) and [orders](/reference/Account%20Information/AccountInformation_getUserAccountOrders) endpoints. __The finer-grained APIs are preferred. They are easier to work with, faster, and have better error handling than this coarse-grained API.__

Check your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing) to see if you have real-time data access:
  - If you do, this endpoint returns real-time data.
  - If you don't, the data is cached and refreshed once a day. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://support.snaptrade.com/brokerages-table?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. If you need real-time, use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint.

If the connection has become disabled, it can no longer access the latest data from the brokerage, but will continue to return the last available cached state. Please see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.


List account holdings

Returns all brokerage accounts across all connections known to SnapTrade for the authenticated user.

Please note that this data is cached and only refreshed once a day.

Check your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing) to see if you have real-time data access:
  - If you do, real-time data can be fetched using the [update account details endpoint](/reference/Account%20Information/AccountInformation_getUserAccountDetails).
  - If you don't, the data is cached and refreshed once a day. If you need real-time, use the [manual refresh endpoint](/reference/Connections/Connections_refreshBrokerageAuthorization).


List accounts

Returns account detail known to SnapTrade for the specified account.

Check your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing) to see if you have real-time data access:
  - If you do, this endpoint returns real-time data.
  - If you don't, the data is cached and refreshed once a day. If you need real-time, use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint.

If the connection has become disabled, it can no longer access the latest data from the brokerage, but will continue to return the last available cached state. Please see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.


Get account detail

Updates various properties of a specified account.

Update details of an investment account

Returns a list of balances for the account. Each element of the list has a distinct currency. Some brokerages like Questrade [allows holding multiple currencies in the same account](https://www.questrade.com/learning/questrade-basics/balances-and-reports/understanding-your-account-balances).

Check your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing) to see if you have real-time data access:
  - If you do, this endpoint returns real-time data.
  - If you don't, the data is cached and refreshed once a day. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://support.snaptrade.com/brokerages-table?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. If you need real-time, use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint.

If the connection has become disabled, it can no longer access the latest data from the brokerage, but will continue to return the last available cached state. Please see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.


List account balances

Returns a list of stock/ETF/crypto/mutual fund positions in the specified account. For option positions, please use the [options endpoint](/reference/Options/Options_listOptionHoldings).

Check your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing) to see if you have real-time data access:
  - If you do, this endpoint returns real-time data.
  - If you don't, the data is cached and refreshed once a day. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://support.snaptrade.com/brokerages-table?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. If you need real-time, use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint.

If the connection has become disabled, it can no longer access the latest data from the brokerage, but will continue to return the last available cached state. Please see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.


List account positions

Returns a list of recent orders in the specified account.

Check your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing) to see if you have real-time data access:
  - If you do, this endpoint returns real-time data.
  - If you don't, the data is cached and refreshed once a day. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://support.snaptrade.com/brokerages-table?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. If you need real-time, use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint.

If the connection has become disabled, it can no longer access the latest data from the brokerage, but will continue to return the last available cached state. Please see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.


List account orders

Returns a list of recent orders in the specified account.

The V2 order response format will include all legs of each order in the `legs` list field. If the order is single legged, `legs` will be a list of one leg.

If the connection has become disabled, it can no longer access the latest data from the brokerage, but will continue to return the last available cached state. Please see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.


List account orders v2

An experimental endpoint that returns estimated historical total account value for the specified account. Total account value is the sum of the market value of all positions and cash in the account at a given time. This endpoint is experimental, disabled by default, and only available for certain brokerages with a maximum lookback of 1 year.


List historical account total value

A lightweight endpoint that returns the latest page of orders placed in the last 24 hours in the specified account. For most brokerages, the default page size is 100 meaning the endpoint will return a max of 100 orders.
This endpoint is realtime and can be used to quickly check if account state has recently changed due to an execution, or check status of recently placed orders
Differs from /orders in that it is always realtime, and only checks the last 24 hours
By default only returns executed orders, but that can be changed by setting *only_executed* to false


List account recent orders (last 24 hours only)

A lightweight endpoint that returns a list of orders executed in the last 24 hours in the specified account using the V2 order format.
This endpoint is realtime and can be used to quickly check if account state has recently changed due to an execution, or check status of recently placed orders.
Differs from /orders in that it is realtime, and only checks the last 24 hours as opposed to the last 30 days.
By default only returns executed orders, but that can be changed by setting *only_executed* to false.
**Because of the cost of realtime requests, each call to this endpoint incurs an additional charge. You can find the exact cost for your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing)**


List account recent orders (V2, last 24 hours only)

Returns a list of rate of return percents for a given account. Will include timeframes available from the brokerage, for example "ALL", "1Y", "6M", "3M", "1M"


List account rate of returns

Returns all historical transactions for the specified account.

This endpoint is paginated with a default page size of 1000. The endpoint will return a maximum of 1000 transactions per request. See the query parameters for pagination options.

Transaction are returned in reverse chronological order, using the `trade_date` field.

The data returned here is always cached and refreshed once a day.

If the connection has become disabled, it can no longer access the latest data from the brokerage, but will continue to return the last available cached state. Please see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.


List account activities

Returns a list of rate of return percents for a given connection. Will include timeframes available from the brokerage, for example "ALL", "1Y", "6M", "3M", "1M"


List connection rate of returns

Returns quotes from the brokerage for the specified symbols and account.

The quotes returned can be delayed depending on the brokerage the account belongs to. It is highly recommended that you use your own market data provider for real-time quotes instead of relying on this endpoint.

**This endpoint is not a substitute for a market data provider. Frequent polling of this endpoint may result in the disabling of your keys**

This endpoint does not work for options quotes.

This endpoint is disabled for free plans by default. Please contact support to enable this endpoint if needed.


Get equity symbol quotes

Returns a real-time quote for a single option contract. The option contract is specified using in the 21 character OCC format. For example `AAPL  251114C00240000` represents a call option on AAPL expiring on 2025-11-14 with a strike price of $240. For more information on the OCC format, see [here](https://en.wikipedia.org/wiki/Option_symbol#OCC_format)


Get option quote

**This endpoint is deprecated. Please switch to [the new cancel order endpoint](/reference/Trading/Trading_cancelOrder) **
Attempts to cancel an open order with the brokerage. If the order is no longer cancellable, the request will be rejected.


Cancel equity order

Returns a list of Universal Symbol objects that match the given query. The matching takes into consideration both the ticker and the name of the symbol. Only the first 20 results are returned.

The search results are further limited to the symbols supported by the brokerage for which the account is under.


Search account symbols

Returns a list of option positions in the specified account. For stock/ETF/crypto/mutual fund positions, please use the [positions endpoint](/reference/Account%20Information/AccountInformation_getUserAccountPositions).

Check your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing) to see if you have real-time data access:
  - If you do, this endpoint returns real-time data.
  - If you don't, the data is cached and refreshed once a day. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://support.snaptrade.com/brokerages-table?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. If you need real-time, use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint.


List account option positions

Returns a list of all connections for the specified user. Note that `Connection` and `Brokerage Authorization` are interchangeable, but the term `Connection` is preferred and used in the doc for consistency.

A connection is usually tied to a single login at a brokerage. A single connection can contain multiple brokerage accounts.

SnapTrade performs de-duping on connections for a given user. If the user has an existing connection with the brokerage, when connecting the brokerage with the same credentials, SnapTrade will return the existing connection instead of creating a new one.


List all connections

Deletes the SnapTrade connection specified by the ID. This will also remove the accounts and holdings data associated with the connection from SnapTrade. This action is irreversible. This endpoint is synchronous, a 204 response indicates that the data has been successfully deleted.

Delete connection

Returns a single connection for the specified ID.

Get connection detail

Deletes the SnapTrade connection specified by the ID. This will also remove the accounts and holdings data associated with the connection from SnapTrade. This action is irreversible. This endpoint is asynchronous, a 200 response indicates that a task has been queued to delete the connection. Listen for the [`CONNECTION_DELETED` webhook](https://docs.snaptrade.com/docs/webhooks#webhooks-connection_deleted) webhook to know when the deletion has been completed and the data has been removed.

Trigger a holdings update for all accounts under this connection. Updates will be queued asynchronously. [`ACCOUNT_HOLDINGS_UPDATED` webhook](/docs/webhooks#webhooks-account_holdings_updated) will be sent once the sync completes for each account under the connection.
This endpoint will also trigger a transaction sync for the past day if one has not yet occurred.

**Because of the cost of refreshing a connection, each call to this endpoint incurs an additional charge. You can find the exact cost for your API key on the [Customer Dashboard billing page](https://dashboard.snaptrade.com/settings/billing)**


Refresh holdings for a connection

Manually force the specified connection to become disabled. This should only be used for testing a reconnect flow, and never used on production connections.
Will trigger a disconnect as if it happened naturally, and send a [`CONNECTION_BROKEN` webhook](/docs/webhooks#webhooks-connection_broken) for the connection.

This endpoint is available on test keys. If you would like it enabled on production keys as well, please contact support as it is disabled by default.


Force disable connection

Returns a list of session events associated with a user.

Get all session events for a user

Returns a list of all defined Brokerage objects.

Get brokerages

Returns a list of all brokerage instruments available for a given brokerage. Not all brokerages support this. The ones that don't will return an empty list.

Get brokerage instruments

Returns a list of all defined Brokerage authorization Type objects.

Get all brokerage authorization types

Returns a list of all defined Currency objects.

Get currencies

Returns a list of all Exchange Rate Pairs for all supported Currencies.

Get currency exchange rates

Returns an Exchange Rate Pair object for the specified Currency Pair.

Get exchange rate of a currency pair

Returns a list of all supported Exchanges.

Get exchanges

Return all available security types supported by SnapTrade.

List security types

Returns a list of Universal Symbol objects that match the given query. The matching takes into consideration both the ticker and the name of the symbol. Only the first 20 results are returned.


Search symbols

Returns the Universal Symbol object specified by the ticker or the Universal Symbol ID. When a ticker is specified, the first matching result is returned. We largely follow the [Yahoo Finance ticker format](https://help.yahoo.com/kb/SLN2310.html)(click on "Yahoo Finance Market Coverage and Data Delays"). For example, for securities traded on the Toronto Stock Exchange, the symbol has a '.TO' suffix. For securities traded on NASDAQ or NYSE, the symbol does not have a suffix. Please use the ticker with the proper suffix for the best results.


Get symbol detail

Places a brokerage order in the specified account. The order could be rejected by the brokerage if it is invalid or if the account does not have sufficient funds.

This endpoint does not compute the impact to the account balance from the order and any potential commissions before submitting the order to the brokerage. If that is desired, you can use the [check order impact endpoint](/reference/Trading/Trading_getOrderImpact).

It's recommended to trigger a manual refresh of the account after placing an order to ensure the account is up to date. You can use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint for this.


Place equity order

Places a bracket order (entry order + OCO of stop loss and take profit). Disabled by default please contact support for
use. Only supported on certain brokerages


Place bracket order

Replaces an existing pending order with a new one. The way this works is brokerage dependent, but usually involves cancelling
the existing order and placing a new one. The order's brokerage_order_id may or may not change, be sure to use the one
returned in the response going forward. Only supported on some brokerages


Replace order

Simulates an order and its impact on the account. This endpoint does not place the order with the brokerage. If successful, it returns a `Trade` object and the ID of the object can be used to place the order with the brokerage using the [place checked order endpoint](/reference/Trading/Trading_placeOrder). Please note that the `Trade` object returned expires after 5 minutes. Any order placed using an expired `Trade` will be rejected.

Check equity order impact

Places the previously checked order with the brokerage. The `tradeId` is obtained from the [check order impact endpoint](/reference/Trading/Trading_getOrderImpact). If you prefer to place the order without checking for impact first, you can use the [place order endpoint](/reference/Trading/Trading_placeForceOrder).

It's recommended to trigger a manual refresh of the account after placing an order to ensure the account is up to date. You can use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint for this.


Place checked equity order

Returns the detail of a single order using the external order ID provided in the request body.

This endpoint only works for single-leg orders at this time. Support for multi-leg orders will be added in the future.

This endpoint is always realtime and does not rely on cached data.

This endpoint only returns orders placed through SnapTrade. In other words, orders placed outside of the SnapTrade network are not returned by this endpoint.


Get account order detail

Returns the detail of a single order using the brokerage order ID provided as a path parameter.

The V2 order response format includes all legs of the order in the `legs` list field.
If the order is single legged, `legs` will be a list of one leg.

This endpoint is always realtime and does not rely on cached data.

This endpoint only returns orders placed through SnapTrade. In other words, orders placed outside of the SnapTrade network are not returned by this endpoint.


Get account order detail (V2)

Places an order in the specified account.
This endpoint does not compute the impact to the account balance from the order before submitting the order.


Place crypto order

Cancels an order in the specified account. Accepts order IDs for all asset types.


Cancel order

Previews an order using the specified account.


Preview crypto order

Searches cryptocurrency pairs instruments accessible to the specified account. Both `base` and `quote` are optional. Omit both for a full list of cryptocurrency pairs.


Get crypto pairs

Get crypto pair quote

Simulates an option order with up to 4 legs and returns the estimated cost and transaction fees without placing it.
Only supported for certain brokerages. Please refer to the [brokerage trading support page](https://snaptrade.notion.site/brokerages) for more information on which brokerages support this endpoint.


Get option order impact

Places a multi-leg option order. Only supported on certain option trading brokerages. https://support.snaptrade.com/brokerages has information on brokerage trading support


Place option order

This endpoint is being deprecated but will continue to be available for use via SDKs, please use [the account level endpoint](/reference/Account%20Information/AccountInformation_getAccountActivities) if possible

Returns all historical transactions for the specified user and filtering criteria. It's recommended to use `startDate` and `endDate` to paginate through the data, as the response may be very large for accounts with a long history and/or a lot of activity. There's a max number of 10000 transactions returned per request.

There is no guarantee to the ordering of the transactions returned. Please sort the transactions based on the `trade_date` field if you need them in a specific order.

The data returned here is always cached and refreshed once a day.


Get transaction history for a user

Returns performance information (contributions, dividends, rate of return, etc) for a specific timeframe. Please note that Total Equity Timeframe and Rate of Returns are experimental features. Please contact support@snaptrade.com if you notice any inconsistencies.

Get performance information for a specific timeframe

A webhook that is sent whenever a new connection is added.

/connectionAdded

A webhook that is sent whenever an existing connection is deleted.

/connectionDeleted

A webhook that is sent whenever a user is newly registered.

/userRegistered

A webhook that is sent whenever an existing user is deleted.

/userDeleted

A webhook that is sent whenever a new account is added to an existing brokerage authorization.

/accountAdded

A webhook that is sent whenever an existing account under a brokerage authorization is deleted.

/accountDeleted

A webhook that is sent whenever transactions have been updated for an account.

/transactionsUpdated

  Getting Started  This is an interactive demo to help you get started with the SnapTrade API  You can run the code snippets directly in your browser to see the API in action  By the end of this demo  you will have created a new user  connected a brokerage account  and retrieved account details and positions  Let s get started      1  Initialize a client with your clientId and consumerKey  You can get your SnapTrade  clientId  and  consumerKey  by  registering for a new account  https   dashboard snaptrade com signup   Once you have your credentials  please enter them below to initialize the SnapTrade client  Please note that your  consumerKey  is sensitive information and should be kept secure at all times       form    input name SNAPTRADE CLIENT ID label  Client ID  placeholder  YOUR CLIENT ID      input name SNAPTRADE CONSUMER KEY label  Consumer Key  placeholder  YOUR CONSUMER KEY  type  password       code     python import json from snaptrade client import SnapTrade import uuid import os  snaptrade   SnapTrade  consumer key SNAPTRADE CONSUMER KEY  client id SNAPTRADE CLIENT ID     print  Successfully initiated client           typescript import   Snaptrade   from  snaptrade typescript sdk   const snaptrade   new Snaptrade     consumerKey  process env SNAPTRADE CONSUMER KEY    clientId  process env SNAPTRADE CLIENT ID      console log  Successfully initiated client             csharp Configuration configuration   new Configuration    string clientId   System Environment GetEnvironmentVariable  SNAPTRADE CLIENT ID    string consumerKey   System Environment GetEnvironmentVariable  SNAPTRADE CONSUMER KEY    configuration ApiKey Add  clientId   clientId   configuration ConsumerKey   consumerKey  apiStatusApi   new APIStatusApi configuration   authenticationApi   new AuthenticationApi configuration   accountInformationApi   new AccountInformationApi configuration   transactionsAndReportingApi   new TransactionsAndReportingApi configuration   referenceDataApi   new ReferenceDataApi configuration   optionsApi   new OptionsApi configuration   Console WriteLine  Successfully initiated clients                 button Initialize SDK Client            2  Create a new user on SnapTrade  To create a secure brokerage connection  we first need to register a SnapTrade user  Call the  a href  https   docs snaptrade com reference Authentication Authentication registerSnapTradeUser  target   blank  Register User  a  endpoint with a unique ID for an end user in your system  Upon success  you should receive a system generated user secret  You can think of the user secret like a per user API key that provides an additional layer of security for protecting user data  The user id and user secret need to be passed along to all SnapTrade API endpoints that involve access to user data      form    input name SNAPTRADE USER ID label  SnapTrade User ID  placeholder  YOUR SNAPTRADE USER ID       python user id   SNAPTRADE USER ID register response   snaptrade authentication register snap trade user  user id user id   print json dumps register response body  indent 2      Note  A user secret is only generated once  It s required to access   resources for certain endpoints   user secret   register response body  userSecret          button Register User           3  Connect a brokerage account  Now that the user is created  we are ready to connect their brokerage accounts to SnapTrade  This is done via the SnapTrade Connection Portal  Each Connection Portal session is unique to the user and is generated by calling the  a href  https   docs snaptrade com reference Authentication Authentication loginSnapTradeUser  target   blank  Generate Connection Portal URL  a  endpoint passing in the user ID and user secret      form     python redirect uri   snaptrade authentication login snap trade user  user id user id  user secret user secret    print json dumps redirect uri body  indent 2          button Generate Connection Portal URL        From the response  open the redirect URL in a new browser tab to complete the connection  and close it after you re done   If you don t have a live brokerage account to test with  you can create a Paper Trading account with  Alpaca  https   app alpaca markets signup  and select  Alpaca Paper  as the instituion in the Connection Portal when prompted       4  List connected accounts  Once the end user makes a successful connection  SnapTrade will retrieve all the brokerage accounts that the user has granted access to  You can use the  a href  https   docs snaptrade com reference Account 20Information AccountInformation listUserAccounts  target   blank  List Accounts  a  endpoint to retrieve all connected accounts  For each account  the  id  field uniquely identifies the account within SnapTrade and needs to be passed in for all subsequent account related API calls      form     python accounts   snaptrade account information list user accounts      user id user id      user secret user secret   print json dumps accounts body  indent 2    for account in accounts body      print    SAVE ACCOUNTS      format account  id            button List User Accounts           5  Get account detail  The  a href  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountDetails  target   blank  Account Detail  a  endpoint gives you a detailed view of the account  including account number  name  total market value  and more   Select a connected account below to retrieve the account detail      form skippable     enum name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  savedData ACCOUNTS description  The SnapTrade account ID       python account id   ACCOUNT ID account detail   snaptrade account information get user account details      account id account id  user id user id  user secret user secret   print json dumps account detail body  indent 2          button Get Account Detail           6  Get account positions  The  a href  https   docs snaptrade com reference Account 20Information AccountInformation getUserAccountPositions  target   blank  Account Positions  a  endpoint give you a list of stock ETF crypto mutual fund positions in the account       form skippable      python positions   snaptrade account information get user account positions      account id account id  user id user id  user secret user secret   print json dumps positions body  indent 2          button Get Equity Positions        Option positions are currently returned via a separate  a href  https   docs snaptrade com reference Options Options listOptionHoldings  target   blank  Options Positions  a  endpoint      form skippable      python option positions   snaptrade options list option holdings      account id account id  user id user id  user secret user secret   print json dumps option positions body  indent 2          button Get Option Positions           7  Deleting a user  You ve reached the end of this demo  If you want to delete the user you created  you can do so by calling the  a href  https   docs snaptrade com reference Authentication Authentication deleteSnapTradeUser  target   blank  Delete User  a  endpoint  This will delete the user and all associated data  connections  accounts  positions  etc  permanently      form     python deleted response   snaptrade authentication delete snap trade user  user id user id   print json dumps deleted response body  indent 2          button Delete User       

Getting Started

  Get Historical Transactions          info You need an existing SnapTrade user with a connected brokerage account for this demo  Please finish the  Getting Started  https   docs snaptrade com demo getting started  demo first       Use this interactive demo to retrieve historical transactions from a specific connected account for a SnapTrade user           1  Initialize SnapTrade client and the connected SnapTrade user  Please copy the values from the  Getting Started  https   docs snaptrade com demo getting started  demo and paste them below      form    input name SNAPTRADE CLIENT ID label  Client ID  placeholder  YOUR CLIENT ID      input name SNAPTRADE CONSUMER KEY label  Consumer Key  placeholder  YOUR CONSUMER KEY  type  password      input name USER ID label  User ID  placeholder  YOUR USER ID      input name USER SECRET label  User Secret  placeholder  YOUR USER SECRET  type  password       python from snaptrade client import SnapTrade import json import uuid import os  snaptrade   SnapTrade    consumer key SNAPTRADE CONSUMER KEY    client id SNAPTRADE CLIENT ID     user id   USER ID user secret   USER SECRET  print  Successfully initiated client          button Initialize SDK Client                2  Get user s accounts  First  let s get a list of the user s connected accounts to select one for fetching transactions      form     python accounts   snaptrade account information list user accounts    user id user id    user secret user secret   print json dumps accounts body  indent 2          button Get Accounts                3  Retrieve historical transactions  Once you have the account ID from the previous step  you can retrieve historical transactions using the  Account Activities  https   docs snaptrade com reference Account 20Information AccountInformation getAccountActivities  endpoint  This endpoint is paginated with a default page size of 1000 transactions and returns them in reverse chronological order   Please note for accounts with a large number of transactions  it could take a significant amount of time for SnapTrade to initially retrieve and index the data  If you don t see any transactions now  please try again later      form skippable     input name ACCOUNT ID label  Account ID  placeholder  YOUR ACCOUNT ID  description  The ID of the account to fetch transactions for      date name START DATE label  Start Date  placeholder  START DATE  description  The start date  inclusive  of the transaction history to retrieve  valueFormat  YYYY MM DD  optional    date name END DATE label  End Date  placeholder  END DATE  description  The end date  inclusive  of the transaction history to retrieve  valueFormat  YYYY MM DD  optional    enum name TYPE label  Type  searchable nothingFound  No type  placeholder  TYPE  data  BUY SELL DIVIDEND CONTRIBUTION WITHDRAWAL REI INTEREST FEE OPTIONEXPIRATION OPTIONASSIGNMENT OPTIONEXERCISE  description  Optional comma seperated list of types to filter transactions by  optional    input name OFFSET label  Offset  placeholder  0  description  Starting point for pagination  default  0   optional    input name LIMIT label  Limit  placeholder  1000  description  Maximum number of transactions to return  default  1000   optional      python activities   snaptrade account information get account activities    account id ACCOUNT ID    user id user id    user secret user secret    start date START DATE if  START DATE  in globals   else None    end date END DATE if  END DATE  in globals   else None    type TYPE if  TYPE  in globals   else None    offset OFFSET if  OFFSET  in globals   else None    limit LIMIT if  LIMIT  in globals   else None   print json dumps activities body  indent 2          button Get Transactions       

Get Historical Transactions

  Placing Orders          info You need an existing SnapTrade user with a connected brokerage account for this demo  Please finish the  Getting Started  https   docs snaptrade com demo getting started  demo first       In this interactive demo  you ll learn how to place equity order using the SnapTrade API  Trading is only available to certain brokerages  See  here  https   support snaptrade com brokerages table v e7bbcbf9f272441593f93decde660687  for a complete list of supported brokerages and their capabilities           1  Initialize SnapTrade client and the connected SnapTrade user  Please copy the values from the  Getting Started  https   docs snaptrade com demo getting started  demo and paste them below      form    input name SNAPTRADE CLIENT ID label  Client ID  placeholder  YOUR CLIENT ID      input name SNAPTRADE CONSUMER KEY label  Consumer Key  placeholder  YOUR CONSUMER KEY  type  password      input name USER ID label  User ID  placeholder  YOUR USER ID      input name USER SECRET label  User Secret  placeholder  YOUR USER SECRET  type  password       python from snaptrade client import SnapTrade import json import uuid import os  snaptrade   SnapTrade    consumer key SNAPTRADE CONSUMER KEY    client id SNAPTRADE CLIENT ID     user id   USER ID user secret   USER SECRET  print  Successfully initiated client          button Initialize SDK Client                2  Create a trade enabled connection  By default  SnapTrade connections are read only  To enable trading for a specific connection  you need to pass in  connection type  trade   when generating the Connection Portal URL      form     python redirect uri   snaptrade authentication login snap trade user    user id user id  user secret user secret  connection type  trade    print json dumps redirect uri body  indent 2          button Generate Trade Enabled Connection Portal URL        From the response  open the redirect URL in a new browser tab to complete the connection  and close it after you re done   If you don t have a live brokerage account to test with  you can create a Paper Trading account with  Alpaca  https   app alpaca markets signup  and select  Alpaca Paper  as the instituion in the Connection Portal when prompted      3  List connected accounts  Once the end user makes a successful connection  SnapTrade will retrieve all the brokerage accounts that the user has granted access to  You can use the  a href  https   docs snaptrade com reference Account 20Information AccountInformation listUserAccounts  target   blank  List Accounts  a  endpoint to retrieve all connected accounts  For each account  the  id  field uniquely identifies the account within SnapTrade and needs to be passed in for all subsequent account related API calls      form     python accounts   snaptrade account information list user accounts      user id user id      user secret user secret   print json dumps accounts body  indent 2    for account in accounts body      print    SAVE ACCOUNTS      format account  id            button List Accounts           4  Identify the instrument to trade  To identify the instrument you want to trade  you need to know the Universal Symbol ID of the instrument  A Universal Symbol is SnapTrade s way to uniquely describe a single security   exchange combination across all brokerages  You can use the  a href  https   docs snaptrade com reference Trading Trading getUserAccountQuotes  target   blank  Symbol Quote  a  endpoint to find the Universal Symbol ID along with the latest market quote of the instrument you want to trade      form    enum name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  savedData ACCOUNTS description  The ID of the account to submit the order to      input name TICKER label  Ticker  defaultValue  AAPL  description  The ticker symbol of the instrument to get quote for        python quotes   snaptrade trading get user account quotes    user id user id    user secret user secret    symbols TICKER    account id ACCOUNT ID    use ticker True    print json dumps quotes body  indent 2    universal symbol id   quotes body 0   symbol    id          button Get Quotes           5  Submit an equity order  You can use the  a href  https   docs snaptrade com reference Trading Trading placeForceOrder  target   blank  Place Order  a  endpoint to submit an equity order under the connected brokerage account      warn If you connected a live brokerage account  please be cautious when submitting orders  SnapTrade is not responsible for any financial losses incurred from using the API          form    enum name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  savedData ACCOUNTS description  The ID of the account to submit the order to      enum name ACTION label  Action  data  BUY SELL  defaultValue BUY    enum name ORDER TYPE label  Order Type  data  Market Limit StopLimit StopLoss  defaultValue  Market     enum name TIME IN FORCE label  Time in Force  data  Day FOK GTC  defaultValue  Day     number name LIMIT PRICE label  Limit Price  step 0 01 precision 2 optional description  The limit price for Limit and StopLimit orders      number name STOP PRICE label  Stop Price  step 0 01 precision 2 optional description  The stop price for StopLimit and StopLoss orders      number name UNITS label  Units  defaultValue 1 step 0 05 precision 2 description  The number of shares to buy or sell  Can be decimal for fractional shares        python try      price LIMIT PRICE except NameError      price None  try      stop STOP PRICE except NameError      stop None  result   snaptrade trading place force order    user id user id    user secret user secret    action ACTION    account id ACCOUNT ID    universal symbol id universal symbol id    order type ORDER TYPE    time in force TIME IN FORCE    price price    stop stop    units UNITS    print json dumps result body  indent 2          button Place Order        If the order is successfully placed  you ll receive a response with the order details  You can use the  brokerage order id  in the response to track the order status  Please double check in your brokerage account to ensure the order was placed successfully  

Placing Orders

consumer_key

PartnerSignature

PartnerTimestamp

SnapTrade

userId

SnapTrade User ID. This is chosen by the API partner and can be any string that is a) unique to the user, and b) immutable for the user. It is recommended to NOT use email addresses for this property because they are usually not immutable.

userSecret

SnapTrade User Secret. This is a randomly generated string and should be stored securely. If compromised, please rotate it via the [rotate user secret endpoint](/reference/Authentication/Authentication_resetSnapTradeUserSecret).

accountId

Unique identifier for the connected brokerage account. This is the UUID used to reference the account in SnapTrade.

Inputs for placing a multi-leg order with the brokerage.

The limit price. Required if the order type is `LIMIT`, `STOP_LOSS_LIMIT`.

The stop price. Required if the order type is `STOP_LOSS_MARKET`, `STOP_LOSS_LIMIT`.

The Time in Force type for the order. This field indicates how long the order will remain active before it is executed or expires. Here are the supported values:
  - `Day` - Day. The order is valid only for the trading day on which it is placed.
  - `GTC` - Good Til Canceled. The order is valid until it is executed or canceled.
  - `FOK` - Fill Or Kill. The order must be executed in its entirety immediately or be canceled completely.
  - `IOC` - Immediate Or Cancel. The order must be executed immediately. Any portion of the order that cannot be filled immediately will be canceled.


Estimated cash change and fees for an option order before it is placed.

Not Implemented - option impact is not supported for this brokerage

The action describes the intent and side of a trade. For equities, this is either `BUY` or `SELL`. For options, this is one of `BUY_TO_OPEN`, `BUY_TO_CLOSE`, `SELL_TO_OPEN`, `SELL_TO_CLOSE`.

The quantity to trade. For options this represents the number of contracts. For equity this represents the number of shares.

The desired price_effect for `LIMIT` and `STOP_LOSS_LIMIT` orders. Values are `CREDIT`, `DEBIT`, `EVEN`

The security's trading ticker symbol. This currently supports stock symbols and Options symbols in the 21 character OCC format. For example `AAPL  251114C00240000` represents a call option on AAPL expiring on 2025-11-14 with a strike price of $240. For more information on the OCC format, see [here](https://en.wikipedia.org/wiki/Option_symbol#OCC_format)

Direction of the cash change. CREDIT means cash is received, DEBIT means cash is paid out, EVEN means no cash changes hands. UNKNOWN if the direction cannot be determined from the request.

Estimated cash change for the order, before fees.

Estimated total transaction fees and commissions for the order.

clientId

Signature

timestamp

Cannot perform action because connection is disabled

Example for a response that failed for unexpected reasons

Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format indicating when the account was created in SnapTrade. This is _not_ the account opening date at the brokerage.

Timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format indicating when the account was funded.

Unique identifier for the connected brokerage account. This is the UUID used to reference the account in SnapTrade. This ID should not change for as long as the connection stays active. If the connection is deleted and re-added, a new account ID will be generated.

A stable and unique account identifier provided by the institution. Will be set to null if not provided. When present, can be used to check if a user has connected the same brokerage account across multiple connections.

The name of the brokerage that holds the account.

Get option order impact

Execute an API Request

Response fields