  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   Triggered when the user closes the OAuth connection window     CLOSE MODAL   Triggered when the user opts to exit the connection flow    aside       Note    Your application is responsible for closing the modal and displaying success error messages post OAuth connections     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 modal and display success message to the user               if  data status      ERROR             const   errorCode  statusCode  detail     data             close the modal and display error message to the user               if  data      CLOSED                close the modal               if  data      CLOSE MODAL                close the modal                      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      coffeescript 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      webookId    311a13f3 3929 46dd a70f ade6aaefc100      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  Please contact us in order to receive these webhooks as they are disabled by default   Example payload is below     json      userId    60b9ad5f 8e78 43b2 af5a 8ce8412b1cd6      clientId    PARTNERAPP      webookId    312a13f3 3929 46dd a70f ade6aaefc100      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 users you've registered over the SnapTrade API.

List SnapTrade users

Registers a new SnapTrade user under your ClientID.
Most SnapTrade operations require a user to be passed as a parameter.


Create SnapTrade user

Deletes a user you've registered over the SnapTrade API, and any data associated with them or their investment accounts.

Delete SnapTrade user

Logs in a SnapTrade user and returns an authenticated connection portal URL for them to use to connect a brokerage account.

Login user & generate connection link

This API is used to rotate the secret for a SnapTrade user. You might use this if a 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.


Obtain a new user secret for a user

Returns useful data related to the specified ClientID, including allowed brokerages and data access.

Get metadata related to Snaptrade partner

Lists balances, positions and orders for the specified account as well as
option_positions and account metadata. The data returned is similar to the
data returned over the more fine-grained **positions**, **orders** and **balances** endpoints.


List balances, positions and orders for the specified account

Get a list of all Account objects for the authenticated SnapTrade user.

List accounts

Returns an account object with details for the specified account,
including the total account market value.


Return details of a specific investment account

A list of account balances for the specified account (one per currency that the account holds).

List account balances

Returns a list of positions in the specified account.

List account positions

Fetch all recent orders from a user's account.

List account orders

Returns live quote(s) from the brokerage for the specified symbol(s).

Get symbol quotes

Sends a signal to the brokerage to cancel the specified order.
This will only work if the order has not yet been executed.


Cancel open order in account

Returns a list of universal symbols that are supported by
the specificied account. Returned symbols are based on the
provided search string, matching on ticker and name.


Search for symbols available in an account

Get account option holdings

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 Brokerage Authorization objects for the user

List all brokerage authorizations for the User

Deletes a specified brokerage authorization given by the ID.

Delete brokerage authorization

Returns a single brokerage authorization object for the specified ID.

Get brokerage authorization details

Trigger a holdings update for all accounts under this authorization. Updates will be queued asynchronously. ACCOUNT_HOLDINGS_UPDATED webhook will be sent once the sync completes

Refresh holdings for a connection

Manually disable a connection. 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 for the connection. Please contact us in order to use this endpoint as it is disabled by default.

Manually disable a connection for testing

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

List security types available on SnapTrade.

List of all security types

Returns a list of Universal Symbol objects that match a defined string.

Matches on ticker or name.


Search for symbols

Returns the Universal Symbol object specified by the ticker or the universal_symbol_id.

Get details of a symbol

Places a specified trade in the specified account.

Place a trade with NO validation.

Return the trade object and it's impact on the account for the specified order.

Check the impact of a trade on an account

Places the specified trade object. This places the order in the account and
returns the status of the order from the brokerage.


Place order

Returns activities (transactions) for a user. Specifying start and end date is highly recommended for better performance

Get transaction history for a user

  Getting Started      1  Initialize a client with your clientId and consumerKey  You can get your  clientId  and  consumerKey  by contacting  api snaptrade com  mailto api snaptrade com       form    input name SNAPTRADE CLIENT ID label  Client ID  placeholder  YOUR CLIENT ID  type  password      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  Check that the client is able to make a request to the API server  Call the API Status 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      form     python api response   snaptrade api status check   print json dumps api response body  indent 2          button Check API Status            3  Create a new user on SnapTrade  To create a secure brokerage authorization  we first need to register a test user  Call the Register user 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 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  type  password       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 Create a new user on SnapTrade            4  Get a redirect URI  SnapTrade partners need to generate a redirect URI for a user so they can securely log in to the SnapTrade Connection portal and connect their accounts  The redirect URI can be generated by sending a POST request to the Login 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      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 Get Redirect URI            5  List accounts  After connecting an account to snaptrade  you can see the account IDs by calling  list user accounts       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            6  Get account holdings data for a user  In order to retrieve user holdings for a specific account  you can call the Holdings 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      form skippable     enum name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  savedData ACCOUNTS description  The ID of the account to pull holdings for       python holdings   snaptrade account information get user holdings      account id ACCOUNT ID      user id user id      user secret user secret   print json dumps holdings body  indent 2          button Get Account Holdings            7  Deleting a user  Disabling all brokerage authorizations and permanently deleting all data associated with the user     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       

  Registering Users      1  Initialize a client with your clientId and consumerKey  You can get your  clientId  and  consumerKey  by contacting  api snaptrade com  mailto api snaptrade com      form    input name SNAPTRADE CLIENT ID label  Client ID  placeholder  YOUR CLIENT ID  type  password      input name SNAPTRADE CONSUMER KEY label  Consumer Key  placeholder  YOUR CONSUMER KEY  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     print  Successfully initiated client          button Initialize SDK Client            2  Check that the client is able to make a request to the API server  Call the API Status 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      form     python api response   snaptrade api status check   print json dumps api response body  indent 2          button Check API Status            3  Register User  To create a secure brokerage authorization  we first need to register a test user  Call the Register user 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 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  type  password       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 Create a new user on SnapTrade            4  Login User  SnapTrade partners need to generate a redirect URI for a user so they can securely log in to the SnapTrade Connection portal and connect their accounts  The redirect URI can be generated by sending a POST request to the Login 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      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 Login User            5  List Users     form     python users   snaptrade authentication list snap trade users   print json dumps users body  indent 2          button List Users            6  Deleting a user  Disabling all brokerage authorizations and permanently deleting all data associated with the user     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       

Registering Users

  Get Account Holdings for a User      1  Initialize a client with your clientId and consumerKey  You can get your  clientId  and  consumerKey  by contacting  api snaptrade com  mailto api snaptrade com      form    input name SNAPTRADE CLIENT ID label  Client ID  placeholder  YOUR CLIENT ID  type  password      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  type  password      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     print  Successfully initiated client    user id   USER ID user secret   USER SECRET  print  Initialized user id and user secret          button Initialize SDK Client            2  List accounts  You can see the account IDs by calling  list user accounts       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            3  Get account holdings data for a user  In order to retrieve user holdings for a specific account  you can call the Holdings 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      form    enum name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  savedData ACCOUNTS description  The ID of the account to pull holdings for  The available values are pulled from the  List User Accounts  step        python holdings   snaptrade account information get user holdings      account id ACCOUNT ID      user id user id      user secret user secret   print json dumps holdings body  indent 2          button Get Account Holdings       

Get Account Holdings for a User

  Handling Users     info This demo is for after a user is created and connected  See  Getting Started   snaptrade snaptrade demos getting started  or  Registering Users   snaptrade snaptrade demos registering users  for creating and connecting a user to SnapTrade           1  Initialize SnapTrade client   user id   and  user secret      form    input name SNAPTRADE CLIENT ID label  Client ID  placeholder  YOUR CLIENT ID  type  password      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  type  password      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  List accounts  You can see the account IDs by calling  list user accounts       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            3  Get account holdings data for a user  In order to retrieve user holdings for a specific account  you can call the Holdings 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      form    enum name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  savedData ACCOUNTS description  The ID of the account to pull holdings for  The available values are pulled from the  List User Accounts  step        python holdings   snaptrade account information get user holdings      account id ACCOUNT ID      user id user id      user secret user secret   print json dumps holdings body  indent 2          button Get Account Holdings            4  Get Transactions   Historical Activities  Returns activities  transactions  for a user  Specifying start and end date is highly recommended for automatic calls for better performance  This uses the TransactionsAndReporting API      form skippable     date name START DATE label  Start Date  placeholder  START DATE  valueFormat  YYYY MM DD  optional    date name END DATE label  End Date  placeholder  END DATE  valueFormat  YYYY MM DD  optional    input name ACCOUNTS label  Account s   placeholder  YOUR ACCOUNT IDS  description  Optional comma seperated list of account IDs used to filter the request on specific accounts  optional    input name BROKERAGE AUTHORIZATIONS label  Brokerage Authorizations  placeholder  YOUR BROKERAGE AUTHORIZATION  description  Optional comma seperated list of brokerage authorization IDs used to filter the request on only accounts that belong to those authorizations  optional    enum name TYPE label  Type  searchable nothingFound  No type  placeholder  TYPE  data  DIVIDEND BUY SELL CONTRIBUTION WITHDRAWAL EXTERNAL ASSET TRANSFER IN EXTERNAL ASSET TRANSFER OUT INTERNAL CASH TRANSFER IN INTERNAL CASH TRANSFER OUT INTERNAL ASSET TRANSFER IN INTERNAL ASSET TRANSFER OUT INTEREST REBATE GOV GRANT TAX FEE REI FXT  description  Optional comma seperated list of types to filter activities 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    accounts ACCOUNTS if  ACCOUNTS  in globals   else None    brokerage authorizations BROKERAGE AUTHORIZATIONS if  BROKERAGE AUTHORIZATIONS  in globals   else None    type TYPE if  TYPE  in globals   else None   print json dumps activities body  indent 2          button Get Activities            5  Get Quotes  Get symbol quotes for a user  these are account and thus brokerage specific  That means if you have a US only account  you cannot get quotes for international exchanges  This uses the Trading API      form    input name SYMBOLS label  Symbols  placeholder  AAPL  description  List of universal symbol id or tickers to get quotes for     input name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  description  The ID of the account to get quotes     input name USE TICKER type  checkbox  defaultValue true label  Use Ticker  description  Should be set to True if providing tickers  optional      python activities   snaptrade trading get user account quotes    user id user id    user secret user secret    symbols SYMBOLS    account id ACCOUNT ID    use ticker USE TICKER if  USE TICKER  in globals   else None    print json dumps activities body  indent 2          button Get Quotes       

Handling Users

  Placing Trades      1  Create user and Get redirect URL for a trading connection  You can get your  clientId  and  consumerKey  by contacting  api snaptrade com  mailto api snaptrade com      form    input name SNAPTRADE CLIENT ID label  Client ID  placeholder  YOUR CLIENT ID  type  password      input name SNAPTRADE CONSUMER KEY label  Consumer Key  placeholder  YOUR CONSUMER KEY  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   f konfigdemo  uuid uuid4     register response   snaptrade authentication register snap trade user    user id user id   user secret   register response body  userSecret    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 Create User and Get Redirect URL            2  List accounts  After connecting an account you can see the account IDs by calling  list user accounts       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            3  Get Order Impact  Check the account has enough cash to place trades      form skippable     enum name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  savedData ACCOUNTS description  The ID of the account to pull holdings for      input name UNIVERSAL SYMBOL label  Universal Symbol  defaultValue  c15a817e 7171 4940 9ae7 f7b4a95408ee     enum name ACTION label  Action  data  BUY SELL  defaultValue BUY    enum name ORDER TYPE label  Order Type  data  Limit Market StopLimit StopLoss  defaultValue  Limit     enum name TIME IN FORCE label  Time in Force  data  Day FOK GTC  defaultValue  Day     number name PRICE label  Price  defaultValue 10  step 0 01 precision 2    number name UNITS label  Units  defaultValue 1 step 0 05 precision 2      python result   snaptrade trading get order impact    user id user id    user secret user secret    action ACTION    account id ACCOUNT ID    universal symbol id UNIVERSAL SYMBOL    order type ORDER TYPE    time in force TIME IN FORCE    price PRICE    units UNITS    print json dumps result body  indent 2          button Get Order Impact            4  Place the order  Place the order     form skippable     input name TRADE ID label  Trade Id  description  The ID of the trade created at the previous step        python result   snaptrade trading place order    user id user id    user secret user secret    trade id TRADE ID   print json dumps result body  indent 2          button Place Order            Alternative   Place Order without checking impact  If you don t need to check the impact of an order before placing it use  place force order      form    enum name ACCOUNT ID label  Account ID  placeholder  ACCOUNT ID  savedData ACCOUNTS description  The ID of the account to pull holdings for      input name UNIVERSAL SYMBOL label  Universal Symbol  defaultValue  c15a817e 7171 4940 9ae7 f7b4a95408ee     enum name ACTION label  Action  data  BUY SELL  defaultValue BUY    enum name ORDER TYPE label  Order Type  data  Limit Market StopLimit StopLoss  defaultValue  Market     enum name TIME IN FORCE label  Time in Force  data  Day FOK GTC  defaultValue  Day     number name PRICE label  Price  step 0 01 precision 2 optional    number name UNITS label  Units  defaultValue 1 step 0 05 precision 2      python try      price PRICE except NameError      price 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    order type ORDER TYPE    time in force TIME IN FORCE    price price    units UNITS    print json dumps result body  indent 2          button Place Force Order       

Placing Trades

consumer_key

PartnerSignature

PartnerTimestamp

SnapTrade

Response when register user is successful

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.

SnapTrade User Secret randomly generated by SnapTrade. This is privileged information and if compromised, should be rotated via the SnapTrade API.

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

Failed authenticaion. Wrong clientId, userId or userSecret provided

Example for a response that failed for unexpected reasons

clientId

Signature

timestamp

Request body to signed. Include it under "content"

Cannot perform action because connection is disabled

Total value of this account (includes cash, equity, fixed income, etc)

Trade Action potential values include (but are not limited to) - BUY - SELL - BUY_COVER - SELL_SHORT - BUY_OPEN - BUY_CLOSE - SELL_OPEN - SELL_CLOSE

Total value of the account, as reported by the brokerage

A display-friendly name of the brokerage.

List of exchange ID supported by brokerage

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

Comma seperated list of brokerage authorization IDs

Array of trades to make to rebalance portfolio

Cash restriction rules that apply to this account when undergoing portfolio rebalance calculations.

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

The ticker of the symbol that the dividend came from

The exchange rate of a pair of currencies

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

JWT Token. Used to acess resources in private endpoints available only through the Passiv app

Enum definitions -> [-1: Unassigned, 0: Security Model Portfolio, 1: Asset Class Portfolio]

Object representing total dividends received during a timeframe

Dollar amount to trade. Cannot work with units. Can only work for market order types and day for time in force. **Only available for Alpaca, Alpaca Paper, and Robinhood.**

Obtained from calling options chain endpoint (option_id)

Order Type potential values include (but are not limited to) - Limit - Market - StopLimit - StopLoss

Brokerages that can be accessed by partners

Shows if Snaptrade partners can get users account history data

Shows if Snaptrade partners can get user holdings data

Shows if Snaptrade partners can get users account order history

Shows if users Snaptrade partners can access portfolio group management features

Shows if Snaptrade partners can get users holdings data

Shows if users of Snaptrade partners can access trade endpoints

Shows if pin is required by users to access connection page

URI to redirect user back to after user is done adding brokerage connections

list of tickers which may not be supported or may not have accurate price data

commissions incurred during the timeframe

Number of months in the timeframe with contributions

Current streak of cosecutive months where contributions were made

Whether the user has detailed mode enabled (more frequent data points for totalEquity and contribution timeframes)

Total dividends received over the timeframe

Average dividends received per month over the timeframe

The return rate over the timeframe. Annualized if timeframe is longer than 1 year

Summary of all relevant information about a portfolio group.

Average purchase price for this position. Either returned by the underlying broker or calculated using historical transactions.

Deprecated, use the units field for both fractional and integer units going forward

Date used to specify timeframe for a reporting call (in YYYY-MM-DD format)

Optional frequency for the rate of return chart (defaults to monthly). Possible values are weekly, monthly, quarterly, yearly.

Steps to generate a signature
  * Prepare signed content (see SignedContent schema)
  * Sign content prepared above with HMAC-SHA256 using the UTF-8 encoding
  * Return base64 encoding of sign content along with headers
 Note: Use the shared consumer key provided by SnapTrade to signed the request
Example python code
```
import hmac
import json
from base64 import b64encode
from hashlib import sha256
from urllib.parse import urlencode
consumer_key = "UxrFb4cHdRWlmJKNuJjA6hoaN8uVa6jPGFVUl2UKHuKmurCnaU".encode()
request_data = {'userId': 'snaptrade-user-123', 'userSecret': 'CHRIS.P.BACON'}
request_path = "/api/v1/snapTrade/mockSignature"
request_query = "clientId=SNAPTRADETEST&timestamp=1635790389"
sig_object = {"content": request_data, "path": request_path, "query": request_query}
sig_content = json.dumps(sig_object, separators=(",", ":"), sort_keys=True)
sig_digest = hmac.new(consumer_key, sig_content.encode(), sha256).digest()
signature = b64encode(sig_digest).decode()
```


Signed content requires 3 key-value pairs
* content -> Content included in request body, set to null if no content is included. Sort keys in content alphabetically
* path -> Url path of request submitted
* query -> Query params included in requests
After preparing the key-value pairs, sort them alphabetically and convert them
into a string.
Note:
Remove any extra whitespace characters and delimiters from the signed content.
For example, some JSON rendering engines will produce output like this:
  -- `{"blue": "moon", "hello": "world"}`
To produce the correct signature, the JSON should be processed to look like this:
  -- `{"blue":"moon","hello":"world"}`


Status of user acceptance of SnapTrade API disclaimer

Calculated based on the sum of the values of account positions and cash balances

Data to login a user via SnapTrade Partner

Slug of the brokerage to connect the user to

Sets the version of the connection portal to render, with a default to 'v2'

Sets whether the connection should be read or trade

URL to redirect the user to after the user connects their brokerage account

When set to True, user will be redirected back to the partner's site instead of the connection portal

The UUID of the brokerage connection to be reconnected. This parameter should be left empty unless you are reconnecting a disabled connection. See ‘Reconnecting Accounts’ for more information.

SnapTrade Partner brokerage api credentials

client id of snaptrade's partner brokerage app

Redirect uri for snaptrade's partner brokerage app

Data required to register a user via SnapTrade Partner

Stop Price. If stop loss or stop limit order, the price to trigger the stop

Trade time in force examples:
  * FOK - Fill Or Kill
  * Day - Day
  * GTC - Good Til Canceled
  * GTD - Good Til Date


Trade time in force examples:
  * FOK - Fill Or Kill
  * Day - Day
  * GTC - Good Til Canceled


Total estimated commissions across all trades to make

Estimated forex fees to pay to excute trades

Remaining balance after executing all trades

Trade Units. Cannot work with notional value.

A transaction or activity from an institution

Reference ID from brokerage used to identify related transactions. For example if an order comprises of several transactions (buy, fee, fx), they can be grouped if they share the same external_reference_id

The forex conversion rate involved in the transaction if provided by the brokerage. Used in cases where securities of one currency are purchased in a different currency, and the forex conversion is automatic. In those cases, price, amount and fee will be in the top level currency (activity -> currency)

If an option transaction, then it's type (BUY_TO_OPEN, SELL_TO_CLOSE, etc), otherwise empty string

Potential values include (but are not limited to) - DIVIDEND - BUY - SELL - CONTRIBUTION - WITHDRAWAL - EXTERNAL_ASSET_TRANSFER_IN - EXTERNAL_ASSET_TRANSFER_OUT - INTERNAL_CASH_TRANSFER_IN - INTERNAL_CASH_TRANSFER_OUT - INTERNAL_ASSET_TRANSFER_IN - INTERNAL_ASSET_TRANSFER_OUT - INTEREST - REBATE - GOV_GRANT - TAX - FEE - REI - FXT

An API error log for a specific SnapTrade user.

SnapTrade User Secret (generated when registering user)

Optional, defaults to true. Determines if a wait is performed to check on order status. If false, latency will be reduced but orders returned will be more likely to be of status PENDING as we will not wait to check on the status before responding to the request

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()
  ```


Connect brokerage accounts to your app for live positions and trading

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

Information about the newly added account

Return a 200 status to indicate that the account was added successfully

Return a 201 status to indicate that the account was added successfully

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

Return a 200 status to indicate that the account was deleted successfully

Return a 201 status to indicate that the account was deleted successfully

userId

userSecret

A list of all Account objects for the authenticated user.

Obtain a new user secret for a user

Execute an API Request

Response fields