  Getting Started  Welcome to the SnapTrade developer hub  You ll find comprehensive documentation for all our endpoints  as well as detailed guides to help you in your build   If you need further assistance or have any questions  please send us an email at api snaptrade com   If you already have API Keys  you can use  our demo tool  demo   to start making requests           API Status  Call the  api ApiStatus check  endpoint to make sure the API is live and that you can make the most basic request  You should receive a response indicating the API status  current server timestamp  and internal API minor version number   Example      json    version   151   timestamp    2022 01 24T19 02 46 440074Z    online   true                Developer SDKs  Easily integrate with SnapTrade in your programming language of choice by using one of our SDKs     Language       SDK Link                                                                                                                        Python       https   pypi org project snaptrade python sdk                               TypeScript   https   www npmjs com package snaptrade typescript sdk                      Java         https   central sonatype com artifact com konfigthis snaptrade java sdk     Ruby         https   rubygems org gems snaptrade                                         C            https   nuget org packages SnapTrade Net                                    PHP          https   packagist org packages konfig snaptrade php sdk                            Register a test user  To create a secure brokerage authorization  you first need to register a user   Call the  api Authentication registerSnapTradeUser  endpoint with a  userId  which can be any string as long as it s unique to a user  Upon receiving a 200 response  the user is registered successfully and you should receive a response with a user id and a randomly generated user secret    You can think of the user secret as a password that you will store on your users  behalf  This  combined with your consumerKey provides additional security for your users  data  The user id and user secret need to be passed along to all SnapTrade API endpoints that involve access to user data   Example      json    userId    USERID123    userSecret    AYSEY8726837292873                 Generate a login link  To initiate a brokerage authorization for one of your users  you first create a redirect URI for that user to securely login to the SnapTrade Connection Portal and make brokerage connections   The redirect URI can be generated by sending a  POST  request to the  api Authentication loginSnapTradeUser  endpoint   userId  and  userSecret   previously generated through calling the  registerUser  endpoint  have to be in the query parameters of the POST request   The response includes a redirectURI to be used to login a user to the connection portal   Example      json      redirectURI    https   app snaptrade com snapTrade redeemToken token TOKEN clientId PASSIVTEST                 Connect an account through the Connection Portal  Once a user successfully logs into the connection portal  they can select their brokerage and go through the connection flow to connect their brokerage accounts      note For the initial connection  partners can pass in a broker name in the URI so users can go directly to the selected brokerage and make a connection   Example  https   app snaptrade com snapTrade redeemToken token TOKEN clientId PASSIVTEST broker Questrade              Pull user holdings  In order to retrieve user holdings for a specific account  you can call the  api AccountInformation getUserHoldings  endpoint by passing the  clientId    timestamp    userId  and list of account numbers   accounts   to filter the holdings   In the response  you should get an array of objects containing each account holdings data   Example      json            account            id    908192          brokerage    X          number    123456          name    Y              balances                      currency                id    123              code    CA              name    Canadian dollar                      cash   1200                     positions                      symbol                symbol    SYMBL              name    Symbol name              currency                  id    123                code    CA                name    Canadian dollar                          exchange                  code    123123                name    X                                  units    1            price   12                                  Place a limit order  To place an order through SnapTrade API  you need to go through the following two steps   1  To receive information on how a specific order will impact an account  send a  POST  request to  api Trading getOrderImpact  endpoint  The following example is how the body of the request should look like      json      account id    123456      universal symbol id    78910      order type    Limit      time in force    Day      action    BUY      units   1     price   12 9        Example of the response      json      trade          id    0987654321        account    ACCOUNTID        order type    Limit        time in force    Day        symbol            brokerage symbol id    1234567          universal symbol id    8912345          currency              id    012345            code    USD                  local id    121314          description    SYMBOL          symbol    SYMBL              action    BUY        units   1       price   12 9         trade impacts                  account    778899          currency    023901          remaining cash    466 0569         estimated commissions   0 0         forex fees   0 0                     account    12132214          currency    f123123          remaining cash   667 8219         estimated commissions   0 0         forex fees   0 0               combined remaining balance          account    99881882        currency    57fs1223        cash   64 5564               warn An order impact request can fail with a 400 response code due to reasons such as  Markets are not open    Not enough cash to place trades    Exchange does not support market orders   etc  The reason for a failed request would be in the body of the response       Example of the response for a failed request      json      detail    Not enough cash to place trades      status code   400     code    1068              2  To place the order you need to send in the trade id  received through calling the  Trade Impact  endpoint  as a query parameter to the  api Trading placeOrder  endpoint  The successful request would indicate the status of the order   EXECUTED    ACCEPTED    FAILED    REJECTED    PENDING   etc   along with other information related to the order placed   Example of the response      json      brokerage order id    123456      status    ACCEPTED      symbol    7891011      universal symbol          id    123456        symbol    SYMBL        description    Symbol        currency            id    1021993          code    USD          name    US Dollar              currencies            type            id    ceb92399          code    code          is supported   true               action    BUY      total quantity    1 00000000      open quantity    1 00000000      canceled quantity    0 00000000      filled quantity    0 00000000      execution price    0 0000      limit price    12 9000      stop price   null     order type    Limit      time in force    Day      time placed    2022 01 01T10 08 09 044000 05 00      time updated    2022 01 01T10 08 09 113000 05 00      expiry date   null                Delete an open order  To cancel an open order  you need to  POST  to the  api Trading cancelUserAccountOrder  endpoint with the  account id  in the query params and the  brokerage order id  in the body of the request  

Getting Started

  Essential Functionalities  This section describes required functionalities for your implementation of SnapTrade to avoid product issues and ensure that your users have the best possible experience       Ability to reconnect  There are a number of situations that may break a user s brokerage connection  such as brokerage API maintenance windows  unscheduled brokerage downtime  users  credentials changes  etc   Because of this  it is critical to ensure that you include a flow to reconnect a user s brokerage connection   We make this easy by notifying you of broken connections via webhooks  See our related section on  How to Fix Broken Connections   docs fix broken connections  for more information      Ability to edit trade permissions  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      View and Delete Existing 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  

Essential Functionalities

  Recommended endpoints to get started    Holdings   api AccountInformation getUserHoldings   Used to return holdings for a specific account a user has connected in the following format      Text JSON      account   account info     balances   balance info     positions   position info     option positions   option position info     orders   recent order info     errors   error encountered if any     total value   total value of the account         Use for  Fetch Account Metadata  Positions  Balances and Orders with one API call   Note that this endpoint can provide a slower response compared to calling only what you need individually  If looking to instead fetch only Positions  Balances or Orders separately  you can split up the calls with the endpoints listed below  These endpoints are meant to be used independently and don t require to call the holdings endpoint in addition to them  The information returned from the holdings endpoint is also available in these endpoints     api AccountInformation listUserAccounts   Returns a list of all the accounts a user has connected as well as the associated Metadata   Use for  Quickest way to get info on that brokerage accounts a user has access to     api AccountInformation getUserAccountBalance   Returns a list of all cash balances associated with the account id supplied  as well as what currency the balance is in   Use for  Fetching only the cash balances in a user s account     api AccountInformation getUserAccountPositions   Returns a list of all positions associated with the account id supplied  as well as information on the security  current price  ticker  exchange  average purchase price  etc   Use for  Quickest way to see what positions a user s account currently has      Orders  Transactions  Activities   api AccountInformation getUserAccountOrders   Returns a list of recent orders  buys  sells  from the brokerage  Pros     Implemented for all brokerages   Realtime data    Includes all orders  not just executed orders    Has timestamps in addition to the date  Cons     Limited history  brokerage dependent    api TransactionsAndReporting getActivities   Returns a list of transactions activities for the given user  Activities will include at minimum buys  sells  dividends  contributions  withdrawals  Some brokerages will also provide transactions for things like forex transactions  share splits  and more   Pros     Includes all types of transactions  not just trades   History goes all the way back to the date the account was opened  Cons     Only includes executed trades   Gets updated end of day   Not all brokerages support this feature   Some brokerages only include date  not time of transaction  Tips     Syncing may not be instant upon initial brokerage connection for some brokerages  make use of the ACCOUNT TRANSACTIONS INITIAL UPDATE webhook to be notified exactly when all transactions have been loaded for an account  See  our docs on webhooks   docs webhooks  for more information  

Recommended endpoints to get started

  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

  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

  How to Fix Broken Connections  A SnapTrade connection provides direct access to a user s trading account  Users choose to make a brokerage connection  and the connection is established in one of the following ways     The user enters an OAuth connection flow and grants access to their account s     The user enters their brokerage credentials in SnapTrade  which are used to login and generate an access token   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  It is important to understand that SnapTrade works with live trading accounts  which contain real money and real investments  Since the potential damages associated with any form of unauthorized access are high  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  broken connection  which will no longer provide live data until it is fixed 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 broken 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 broken and the user must take an action to fix it     How to fix a broken 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 broken 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  

How to Fix Broken Connections

  Methods to 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   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   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   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   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   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   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   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                    

Methods to 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  contact your Customer Success Manager  They will need the URL of your webhook handler for webhook notifications to begin to be sent     Verifying Webhook Authenticity  You can verify the authenticity of any SnapTrade webhook by verifying the  webhookSecret  field contained in the body of any webhook   Contact your customer success manager to get the correct value of this secret   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 or 201  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 10 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            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

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

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

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 recent orders

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
Differs from /orders in that it only returns orders that have been *executed* in the last 24 hours as opposed to pending or cancelled orders up to 30 days old
*Please contact support for access as this endpoint is not enabled by default.*


List account recent executed orders

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

*Please contact support for access as this endpoint is not enabled by default.*


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.

*Please contact us in order to use this endpoint as it is disabled by default.*


Force disable connection

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

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

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. **If you need real-time data, please use the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint**.


Get transaction history for a user

  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       

  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

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

Data to login a user via SnapTrade Partner

Slug of the brokerage to connect the user to. See [the integrations page](https://snaptrade.notion.site/66793431ad0b416489eaabaf248d0afb?v=3cfea70ef4254afc89704e47275a7a9a&pvs=4) for a list of supported brokerages and their slugs.

Sets the connection portal version to render. Currently only v4 is supported and is the default. All other versions are deprecated and will automatically be set to v4.

Sets whether the connection should be read-only or trade-enabled. Defaults to read-only if not specified.

URL to redirect the user to after the user connects their brokerage account. This parameter is ignored if the connection portal is loaded inside an iframe. See the [guide on ways to integrate the connection portal](/docs/implement-connection-portal) for more information.

When set to `true`, user will be redirected back to the partner's site instead of the connection portal. This parameter is ignored if the connection portal is loaded inside an iframe. See the [guide on ways to integrate the connection portal](/docs/implement-connection-portal) for more information.

The UUID of the brokerage connection to be reconnected. This parameter should be left empty unless you are reconnecting a disabled connection. See the [guide on fixing broken connections](/docs/fix-broken-connections) for more information.

This response consists of 2 different components that must be decrypted to obtain the decrypted message

* Decrypting the encryptedSharedKey

  The encrypted shared key is a shared key that was randomly generated by SnapTrade and encrypted using the users SSH public key provided when registering the user
  It is needed to decrypt the message in step 2.

  To decrypt the shared key, the user should have access to their SSH private key stored locally in their device

  An example Python code on how to decrypt the shared key is shown below

  ```
  def decrypt_rsa_message(self, encrypted_message):
      from Crypto.Cipher import PKCS1_OAEP
      from Crypto.PublicKey import RSA
      from base64 import b64decode

      f = open('private.pem', 'r')
      private_key = RSA.import_key(f.read())
      cipher = PKCS1_OAEP.new(private_key)

      return cipher.decrypt(b64decode(encrypted_message.encode())).decode()
  ```

* Decrypting the encryptedMessageData

   The data meant to be returned by an endpoint can be obtained by decrypting the encrypted message

   An encrypted message is a message that is encrypted using AES - MODE OCB with the shared key obtained in step one

  An example code to decrypt the encrypted message is shown below

  ```
  def decrypt_aes_message(self, shared_key, encrypted_message):
      from Crypto.Cipher import AES
      from base64 import b64decode

      encrypted_msg = b64decode(encrypted_message["encryptedMessage"].encode())
      tag = b64decode(encrypted_message["tag"].encode())
      nonce = b64decode(encrypted_message["nonce"].encode())
      cipher = AES.new(shared_key.encode(), AES.MODE_OCB, nonce=nonce)

      return cipher.decrypt_and_verify(encrypted_msg, tag).decode()
  ```


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.

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.

The name of the brokerage that holds the account.

A display name for the account. Either assigned by the user or by the brokerage itself. For certain brokerages, SnapTrade appends the brokerage name to the account name for clarity.

The account number assigned by the brokerage. For some brokerages, this field may be masked for security reasons.

Contains balance related information for the account.

Total market value of this account (includes cash, equity, fixed income, etc). This value is directly obtained from the brokerage and should reflect the most accurate value of the account.

Total value denominated in the currency of the `currency` field.

The ISO-4217 currency code for the amount.

A wrapper object containing holdings information for a single account.

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

List of recent orders in the account, including both pending and executed orders. Note that option orders are included in this list. Option orders will have a null `universal_symbol` field and a non-null `option_symbol` field.

List of stock/ETF/crypto/mutual fund positions in the account.

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

Describes a single recent order in an account. Each record here represents a single order leg. For multi-leg orders, there will be multiple records.

The number of shares or contracts that have been canceled. Can be a decimal number for fractional shares.

The price at which the order was executed.

The time the order expires. This value is not always available from the brokerage.

The number of shares or contracts that have been filled. Can be a decimal number for fractional shares.

The limit price is maximum price one is willing to pay for a buy order or the minimum price one is willing to accept for a sell order. Should only apply to `Limit` and `StopLimit` orders.

The number of shares or contracts that are still open (waiting for execution). Can be a decimal number for fractional shares.

Contains information about the option contract that the order is for. This field is only present for option orders. For stock/ETF/crypto/mutual fund orders, this field will be null and the `universal_symbol` field will be populated.

The type of order placed. The most common values are `Market`, `Limit`, `Stop`, and `StopLimit`. We try our best to map brokerage order types to these values. When mapping fails, we will return the brokerage's order type value.

The stop price is the price at which a stop order is triggered. Should only apply to `Stop` and `StopLimit` orders.

The time the order was executed in the brokerage system. This value is not always available from the brokerage.

The Time in Force type for the order. This field indicates how long the order will remain active before it is executed or expires. We try our best to map brokerage time in force values to the following. When mapping fails, we will return the brokerage's time in force value.
  - `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.
  - `GTD` - Good Til Date. The order is valid until the specified date.
  - `MOO` - Market On Open. The order is to be executed at the day's opening price.
  - `EHP` - Extended Hours P.M. The order is to be placed during extended hour trading, after markets close.


The time the order was placed. This is the time the order was submitted to the brokerage.

The time the order was last updated in the brokerage system. This value is not always available from the brokerage.

The total number of shares or contracts of the order. This should be the sum of the filled, canceled, and open quantities. Can be a decimal number for fractional shares.

Contains information about the security that the order is for. This field is only present for stock/ETF/crypto/mutual fund orders. For option orders, this field will be null and the `option_symbol` field will be populated.

Indicates the status of an order. SnapTrade does a best effort to map brokerage statuses to statuses in this enum.

Contains status update for the account sync process between SnapTrade and the brokerage.

The action describes the intent or side of a trade. This is usually `BUY` or `SELL` but can include other potential values like the following depending on the specific brokerage.
  - BUY
  - SELL
  - BUY_COVER
  - SELL_SHORT
  - BUY_OPEN
  - BUY_CLOSE
  - SELL_OPEN
  - SELL_CLOSE


The action describes the intent or side of a trade. This is either `BUY` or `SELL`.

The action describes the intent or side of a trade. This is either `BUY` or `SELL` for Equity symbols or `BUY_TO_OPEN`, `BUY_TO_CLOSE`, `SELL_TO_OPEN` or `SELL_TO_CLOSE` for Options.

Holds balance information for a single currency in an account.

Buying power only applies to margin accounts. For non-margin accounts, buying power should be the same as cash. Please note that this field is not always available for all brokerages.

The amount of available cash in the account denominated in the currency of the `currency` field.

The currency of the balance. This applies to both `cash` and `buying_power`.

Describes a brokerage that SnapTrade supports.

This field is deprecated. Please contact us if you have a valid use case for it.

Whether the brokerage allows trading through SnapTrade.

URL to the brokerage's logo in square format.

A display-friendly name of the brokerage.

Whether the brokerage is enabled in SnapTrade. A disabled brokerage will not be available for new connections.

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

Whether the brokerage is currently in maintenance mode. A brokerage in maintenance mode will not be available for new connections.

A short, unique identifier for the brokerage. It is usually the name of the brokerage in capital letters and will never change.

Unique identifier for the connection. This is the UUID used to reference the connection in SnapTrade.

Comma separated list of brokerage authorization IDs

A single connection with a brokerage. 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.


Timestamp of when the connection was established in SnapTrade.

Whether the connection is disabled. A disabled connection can no longer access the latest data from the brokerage, but will continue to return the last cached state. A connection can become disabled for many reasons and differs by brokerage. Here are some common scenarios:

- The user has changed their username or password at the brokerage.
- The user has explicitly removed the access grant at the brokerage.
- The session has expired at the brokerage and now requires explicit user re-authentication.

Please see [this guide](/docs/fix-broken-connections) on how to fix a disabled connection.


Timestamp of when the connection was disabled in SnapTrade.

A short, human-readable name for the connection.

Whether the connection is read-only or trade-enabled. A read-only connection can only be used to fetch data, while a trade-enabled connection can be used to place trades. Valid values are `read` and `trade`.

Timestamp of when the connection was last updated in SnapTrade. This field is deprecated. Please let us know if you have a valid use case for this field.

Confirmation that the connection has been disabled.

Confirmation that the syncs have been scheduled.

A unique identifier for that brokerage. It is usually the name of the brokerage in capital letters and will never change.

Order ID returned by brokerage. This is the unique identifier for the order in the brokerage system.

A unique ID for the security within SnapTrade, scoped to the brokerage account that the security belongs to. This is a legacy field and should not be used. Do not rely on this being a stable ID as it can change.

Type of brokerage. Currently supports traditional brokerages and crypto exchanges.

SnapTrade Client ID (generated and provided to partner by SnapTrade)

The ISO-4217 currency code for the currency.

Unique identifier for the currency. This is the UUID used to reference the currency in SnapTrade.

Human friendly message about the deletion status.

This is always `deleted` when a user is queued for deletion.

The ticker of the symbol that the dividend came from

Describes a single stock or crypto exchange.

The time when the exchange closes for trading.

A short name for the exchange. For standardized exchange code, please us the `mic_code` field.

The [Market Identifier Code](https://en.wikipedia.org/wiki/Market_Identifier_Code) (MIC) for the exchange.

The time when the exchange opens for trading.

The suffix to be appended to the symbol when trading on this exchange. For example, the suffix for the Toronto Stock Exchange is `.TO`. See `UniversalSymbol->symbol` and `UniversalSymbol->raw_symbol` for more detail.

The timezone for the trading hours (`start_time` and `close_time`) of the exchange.

The exchange rate of a pair of currencies

Financial Instrument Global Identifier (FIGI) information for the security. See [OpenFIGI](https://www.openfigi.com/) for more information.

This identifier is unique per security per trading venue. See section 1.4.1 of the [FIGI Standard](https://www.openfigi.com/assets/local/figi-allocation-rules.pdf) for more information.

This enables users to link multiple FIGIs for the same security in order to obtain an aggregated view across all countries and all exchanges. For example, `AAPL` has a different FIGI for each exchange/trading venue it is traded on. The `figi_share_class` is the same for all of these FIGIs. See section 1.4.3 of the [FIGI Standard](https://www.openfigi.com/assets/local/figi-allocation-rules.pdf) for more information.

Status of account holdings sync. SnapTrade syncs holdings from the brokerage under the following conditions:
1. Initial connection - SnapTrade syncs all holdings (positions, balances, recent orders, and transactions) immediately after the connection is established.
2. Daily sync - Once a day SnapTrade refreshes all holdings from the brokerage.
3. Manual sync - You can trigger a refresh of holdings with the [manual refresh](/reference/Connections/Connections_refreshBrokerageAuthorization) endpoint.


Indicates if the initial sync of holdings has been completed. For accounts with a large number of positions/orders/transactions, the initial sync may take a while to complete.

The last time holdings were successfully synced by SnapTrade.

Date in ISO 8601 format or null (YYYY-MM-DD HH:MM:SS.mmmmmmTZ)

Connection Portal link to redirect user to connect a brokerage account.

ID to identify the connection portal session.

Contains the details of a submitted order.

List of impacts of the trade on the account. The list always contains one value at the moment.

Estimated remaining balance of the account after the trade is executed.

Estimated amount of cash remaining in the account after the trade. At the moment this is the same as `remaining_cash` under `trade_impacts`.

Inputs for placing an order with the brokerage.

The limit price for `Limit` and `StopLimit` orders.

The price at which a stop order is triggered for `Stop` and `StopLimit` orders.

The security's trading ticker symbol. This currently only support Options symbols in the 21 character OCC format. For example "AAPL  131124C00240000" represents a call option on AAPL expiring on 2024-11-13 with a strike price of $240. For more information on the OCC format, see [here](https://en.wikipedia.org/wiki/Option_symbol#OCC_format). If 'symbol' is provided, then 'universal_symbol_id' must be 'null'.

For Equity orders, this represents the number of shares for the order. This can be a decimal for fractional orders. Must be `null` if `notional_value` is provided. If placing an Option order, this field represents the number of contracts to buy or sell. (e.g., 1 contract = 100 shares).

The universal symbol ID of the security to trade. Must be 'null' if `symbol` is provided, otherwise must be provided.

Estimated foreign transaction fees for the trade.

Generate Connection Portal URL

Execute an API Request

Response fields