  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       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 konfigthis snaptrade java sdk    https   central sonatype com artifact com konfigthis 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

  Integrate the Connection Portal into Your Application  This document outlines the various methods for integrating the connection portal with your application  You can choose from the following methods      1  Implementation via Regular Web Browser    Why use this method     This method is suitable for applications aiming to open external links in a separate browser window or tab  requiring minimal setup without additional SDKs or libraries  It s straightforward but does necessitate users temporarily leaving your platform     Example Flow     1  The user clicks on  Connect Institution  in your app  2  A new browser tab opens where the user completes the connection to their broker  3  After connecting  the user clicks  Done  to return to your app     Key Considerations       To monitor window messages for successful connections or failures  the connection portal must be opened in a new window using  window opener   otherwise  capturing client side window messages is not feasible  Find guidance on how to monitor window messages  here   implement connection portal window messages to monitor on the client side     You can provide a custom redirect to navigate the user back to a specific page in your app post connection    Enable  immediateRedirect  by setting it to  true  within the login link to automatically redirect users back to your application  either to the custom or default redirect page  upon   successfully connecting or in the case of a connection failure      2  Implementation Using React SDK  For React applications  the  snaptrade react  SDK offers a seamless integration process  For installation and setup instructions  refer to  SnapTrade React SDK on npm  https   www npmjs com package snaptrade react      Why use this method     This method is recommended for React applications because it offers a streamlined integration process that renders the connection portal in an iframe to keep the connection flow within your application  The SDK also provides built in callbacks that allow you to use client side window messages for monitoring successful connections or failures  ensuring a smoother user experience     Callbacks provided by the SDK        onSuccess   This function is executed when a user successfully connects their   institution  and it returns the authorization ID associated with the new connection     onError   This function is triggered when a user encounters an error while   attempting to connect to their institution  The function returns an   object containing error code  status code  and a detailed   description of the error     onExit   This function is triggered when a user opts to exit the connection flow or closes the second tab opened for making an oAuth connection      3  Implementation via an iFrame    Why use this method     This method is ideal if you want to keep the connection flow within your application  providing a more integrated user experience  It s especially useful if you re not using React for your frontend but still want to maintain the connection process within your app     Example Flow     1  Install a library that offers a Modal component or use your own  In this example  we will use the Modal component from Ant Design  https   ant design components modal 2  Import the Modal component in your React project  3  Load the generated login link within the iframe      jsx import   Modal   from  antd    const MyModal             const loginLink     LOGIN LINK       return        Modal title  SnapTrade Connection Portal  visible footer  null          iframe         id  snaptrade connection portal          src  loginLink          title  SnapTrade Connection Portal          allowfullscreen          iframe        Modal           export default MyModal         Key Considerations       Find guidance on how to monitor window messages  here   implement connection portal window messages to monitor on the client side     This method may require additional styling and layout considerations to ensure the iframe fits appropriately within your application s design      4  Implementation in a React Native WebView    Why use this method    This method is ideal for React Native applications that want to keep the connection flow within the app while leveraging the power of WebView     Example Flow     1  Install the  react native webview  library   npm install react native webview  2  Import the WebView component in your React Native project  3  Load the generated login link within the WebView component 4  Utilize the  onMessage  prop to handle window messages      jsx import   WebView   from  react native webview   const MyWebView             const loginLink     LOGIN LINK       return        WebView       source            uri  loginLink                 javaScriptEnabled  true        injectedJavaScript        window addEventListener  message   event            window ReactNativeWebView postMessage event data                       onMessage   event               const messageData   event nativeEvent data          if  messageData                Handle window messages here                                Key Considerations       Find guidance on how to monitor window messages  here   implement connection portal window messages to monitor on the client side       5  Implementation in an iOS WebView    Why use this method     This method is ideal for native iOS applications that want to keep the connection flow within the app while leveraging the power of WebView components     Example Flow     1  Import the necessary WebView component   UIWebView  or  WKWebView   in your iOS project  2  Load the generated login link within the WebView component  3  Set up appropriate delegates or handlers to manage events like successful connections or connection failures      swift import UIKit import WebKit  class MyWebViewController  UIViewController  WKNavigationDelegate      var webView  WKWebView    let loginLink     LOGIN LINK     override func loadView         let webConfiguration   WKWebViewConfiguration       webView   WKWebView frame   zero  configuration  webConfiguration      webView navigationDelegate   self     view addSubview webView         override func viewDidLoad         super viewDidLoad       let request   URLRequest url  URL string  loginLink        webView load request         func webView   webView  WKWebView  didFinish navigation  WKNavigation             Handle window messages here               Key Considerations       Find guidance on how to monitor window messages  here   implement connection portal window messages to monitor on the client side       6  Implementation in an Android WebView    Why use this method     This method is ideal for native Android applications that want to keep the connection flow within the app while leveraging the power of WebView components     Example Flow     1  Import the  WebView  component in your Android project  2  Load the generated login link within the  WebView  component  3  Set up appropriate listeners or handlers to manage events like successful connections or connection failures      java import android webkit WebView  import android webkit WebViewClient   public class MyWebViewActivity extends AppCompatActivity       private WebView webView      private String loginLink     LOGIN LINK         Override     protected void onCreate Bundle savedInstanceState            super onCreate savedInstanceState           setContentView R layout activity main            webView    WebView  findViewById R id webView           webView setWebViewClient new WebViewClient                  Override             public void onPageFinished WebView view  String url                     Handle window messages here                                   webView loadUrl loginLink                  Key Considerations       Find guidance on how to monitor window messages  here   implement connection portal window messages to monitor on the client side       Window Messages to Monitor on the client side      SUCCESS   Indicates successful institution connection  The message contains the authorization ID       Structure            status   SUCCESS   authorizationId   AUTHORIZATION ID              Note  Legacy string format  SUCCESS AUTHORIZATION ID  is for backward compatibility and it may be deprecated in the future  It is essential to use the object format      ERROR   Sent when a connection error occurs  including an error code  status code and description       Structure            status   ERROR   errorCode   ERROR CODE   statusCode   STATUS CODE   detail   DETAIL OF THE ERROR              Note  Legacy string format  ERROR STATUS CODE  is for backward compatibility and it may be deprecated in the future  It is essential to use the object format      CLOSED   Sent when the user closes the OAuth connection window that opens in a new tab       Note  This window message only triggers if connection portal is loading in an Iframe   3   implement connection portal 3 implementation via an iframe      CLOSE MODAL   Sent when the user opts to exit the connection flow or clicks  Done  after successful connection  if the portal is not already closed when listening for  SUCCESS        Note  This window message only triggers if connection portal is loading in an Iframe   3   implement connection portal 3 implementation via an iframe      ABANDONED   Functions the same as  CLOSE MODAL  but only triggers for non iframe implementations   aside       Note    When loading the connection portal in an iframe  your application is responsible for closing the modal and displaying success error messages post  u OAuth connections  u      aside     Example of how these events can be captured in a React app        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               if  data status      ERROR             const   errorCode  statusCode  detail     data             close the connection portal modal and display error message to the user               if  data      CLOSED                close the modal               if  data      CLOSE MODAL                close the modal               if  data      ABANDONED                close the connection portal                      return             window removeEventListener  message   handleMessageEvent  false                    

Integrate the Connection Portal into Your Application

  Trading with SnapTrade     To trade with SnapTrade        Soft Rate Limit     We recommend that you limit trade requests to 1 trade per second per account to maximize the chances that they are all executed without error     1  Find the universal symbol id of the security you want to trade using  api ReferenceData symbolSearchUserAccount  with the users account      This will lookup tradeable securities based on the account you want to place the trade in  You will need to use this id in step 2  2  Either       Use order impact to present the user with the information needed to confirm the trade  as well as check to make sure the trade is valid   api Trading getOrderImpact      After getting impact  you use this endpoint to place the trade with the trade id   api Trading placeOrder       OR    If you don t want to have any validation or impact check you can use this endpoint instead of impact place   api Trading placeForceOrder       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 the  api Authentication loginSnapTradeUser  endpoint       Enable trading for existing connections  To enable trading for an existing connection you will have to ask the user to re authorize access  To generate the re authorize redirect URL set the  reconnect  body parameter to the ID of the existing connection when calling the  api Authentication loginSnapTradeUser  along with  connectionType trade   

Trading with SnapTrade

  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  You can verify the authenticity of any SnapTrade webhook by verifying the  webhookSecret  field contained in the body of any webhook   The correct value of this secret can be found when you configure a webhook listener in the SnapTrade Dashboard   Aside from webhook secrets     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 deleted       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 for some reason  usually an inability to handshake with the brokerage s API   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 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 the first time that we collect transactions data from a brokerage account   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 updated   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            TRADES PLACED  Gets sent when new trades are detected in a user s account   On average  you ll receive a webhook within 30 minutes of activity occurring in the account  we poll once per hour    We send 1 webhook regardless of how many new trades are identified in your account  So if we identify 1 trade in the account  we ll send 1 webhook  and if we identify 10 trades in the account  we also only send 1 webhook   Please contact us in order to receive these webhooks as they are disabled by default   Example payload is below     json      userId    vAzgPrUHizYheZVi WEALTHSIMPLETRADE oiuzalkd      clientId    PARTNERAPP      accountId    45a2g56a eef6 4904 a68e d3f90c3e07c5      eventType    TRADES PLACED      webhookId    311a13f3 3929 46dd a70f ade6aaefc100      brokerageId    905872ac a7b1 4031 a31f 790cba1bfc94      webhookSecret    yfqvPlWrTFILBcjCERPh      eventTimestamp    2023 03 01T14 38 13 111991 00 00      brokerageAuthorizationId    6bb0ahb0 b8c8 4b59 8bf9 7841d7a89c63            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      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 konfigthis snaptrade java sdk    https   central sonatype com artifact com konfigthis 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   www notion so SnapTrade Brokerage Integrations f83946a714a84c3caf599f6a945f0ead pvs 21   

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

  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   snaptrade notion site 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   snaptrade notion site 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.__

The data returned here is cached. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://snaptrade.notion.site/66793431ad0b416489eaabaf248d0afb?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. **If you need real-time data, please use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint**.


List account holdings

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

The data returned here is always cached and refreshed once a day. **If you need real-time data, please use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint**.


List accounts

Returns account detail known to SnapTrade for the specified account.

The data returned here is always cached and refreshed once a day. **If you need real-time data, please use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint**.


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).

The data returned here is cached. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://snaptrade.notion.site/66793431ad0b416489eaabaf248d0afb?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. **If you need real-time data, please use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint**.


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).

The data returned here is cached. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://snaptrade.notion.site/66793431ad0b416489eaabaf248d0afb?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. **If you need real-time data, please use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint**.


List account positions

Returns a list of recent orders in the specified account.

The data returned here is cached. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://snaptrade.notion.site/66793431ad0b416489eaabaf248d0afb?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. **If you need real-time data, please use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint**.


List account orders

A lightweight endpoint that returns a list of orders executed in the last 24 hours in the specified account.
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
**Please contact support for access as this endpoint is not enabled by default.**


List account recent orders (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.


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 does not work for options quotes.

Get symbol quotes

Attempts to cancel an open order with the brokerage. If the order is no longer cancellable, the request will be rejected.


Cancel 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).

The data returned here is cached. How long the data is cached for varies by brokerage. Check the [brokerage integrations doc](https://snaptrade.notion.site/66793431ad0b416489eaabaf248d0afb?v=d16c4c97b8d5438bbb2d8581ac53b11e) and look for "Cache Expiry Time" to see the exact value for a specific brokerage. **If you need real-time data, please use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint**.


List account option positions

Returns the option chain for the specified symbol in the specified account.

Get the options chain for a symbol

Creates an option strategy object that will be used to place an option strategy order.


Create options strategy

Returns a Strategy Quotes object which has latest market data of the specified option strategy.


Get options strategy quotes

Places the option strategy order and returns the order record received from the brokerage.

Place an option strategy order

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 connection specified by the ID. This will also delete all accounts and holdings associated with the connection. This action is irreversible. This endpoint is synchronous, a 204 response indicates that the connection has been successfully deleted.

Delete connection

Returns a single connection for the specified ID.

Get connection detail

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.

**Please contact support before use. Because of the cost of refreshing a connection, each call to this endpoint incurs a additional charge of $0.05**


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 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 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 a 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


Replaces an order with a new one

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 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 order

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.


Cancels an order in the specified account.


Cancel an order.

Previews an order using the specified account.


Preview order

Searches cryptocurrency pairs instruments accessible to the specified account.


Search cryptocurrency pairs instruments

Get cryptocurrency pair quote

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 the connected accounts 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  Retrieve historical transactions  Once a user connects a brokerage account  you can retrieve historical transactions using the  a href  https   docs snaptrade com reference Transactions 20And 20Reporting TransactionsAndReporting getActivities  target   blank  Transaction History  a  endpoint  This demo retrieves transactions across all connected accounts for the user  To perform additional filtering  please check the API reference   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     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      python activities   snaptrade transactions and reporting get activities    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   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   snaptrade notion site 66793431ad0b416489eaabaf248d0afb v e7bbcbf9f272441593f93decde660687 pvs 4  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            4  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

Discover how to manage connections, enable the Connection Portal, and fix disabled connections on SnapTrade. Integrate the portal into your app for seamless user experience.

userId

userSecret

Bad Request. Could be caused by various reasons. Error message is provided in response

Failed authentication. Wrong clientId, userId or userSecret provided

Optional. Comma separated list of authorization IDs (only use if filtering is needed on one or more authorizations).

brokerage_authorizations

accountId

List of brokerage accounts across all connections.

Successfully updated details of an investment account

state

Number of days in the past to fetch the most recent orders. Defaults to the last 30 days if no value is passed in.

days

Defaults to true. Indicates if request should fetch only executed orders. Set to false to retrieve non executed orders as well

only_executed

The start date (inclusive) of the transaction history to retrieve. If not provided, the default is the first transaction known to SnapTrade based on `trade_date`.

startDate

The end date (inclusive) of the transaction history to retrieve. If not provided, the default is the last transaction known to SnapTrade based on `trade_date`.

endDate

An integer that specifies the starting point of the paginated results. Default is 0.

offset

An integer that specifies the maximum number of transactions to return. Default of 1000.

limit

Optional comma separated list of transaction types to filter by. SnapTrade does a best effort to categorize brokerage transaction types into a common set of values. Here are some of the most popular values:
  - `BUY` - Asset bought.
  - `SELL` - Asset sold.
  - `DIVIDEND` - Dividend payout.
  - `CONTRIBUTION` - Cash contribution.
  - `WITHDRAWAL` - Cash withdrawal.
  - `REI` - Dividend reinvestment.
  - `STOCK_DIVIDEND` - A type of dividend where a company distributes shares instead of cash
  - `INTEREST` - Interest deposited into the account.
  - `FEE` - Fee withdrawn from the account.
  - `OPTIONEXPIRATION` - Option expiration event.
  - `OPTIONASSIGNMENT` - Option assignment event.
  - `OPTIONEXERCISE` - Option exercise event.
  - `TRANSFER` - Transfer of assets from one account to another


type

authorizationId

List of Universal Symbol IDs or tickers to get quotes for. When providing multiple values, use a comma as separator

symbols

Should be set to `True` if `symbols` are comprised of tickers. Defaults to `False` if not provided.

use_ticker

Unable to cancel open order. Please verify status in brokerage account

A list of Universal Symbol objects that match the given query.

The ID of the account to get the options chain from.

symbol

List of all Options available for the brokerage symbol

The ID of the account to create the option strategy object in.

The ID of the account the strategy will be placed in.

Option strategy id obtained from response when creating option strategy object

optionStrategyId

The ID of the account to execute the strategy in.

A list of all connections for the specified user.

Unauthorized, invalid credentials for this resource

Unable to sync with brokerage account because the connection is disabled.

Customer or user does not have access to this feature

PartnerClientId

Optional comma separated list of user IDs used to filter the request on specific users

Optional comma separated list of session IDs used to filter the request on specific users