Get started


If you have any questions along the way, please head to the Help Center or refer to the API documentation.

With this quickstart we’ve tried to make it as easy as possible to get up-and-running with TradeIt.

We’ll start with an overview of TradeIt and then jump start your integration with step-by-step guides and code samples. If you’d like to follow along (and test it out!), clone the guides repository for the complete example apps. You’ll want to sign up for free API keys to get started.

TradeIt Products

TradeIt enables you to integrate portfolio data and trading with most online US brokers in minutes. Link your users' brokerage accounts easily and securely on web or mobile:

  • TradingTicket

    Supports Equities, ETFs, FX, and Options
    Supports all order types
    Supports retrieving and canceling orders

  • PortfolioView

    Access data in real time
    Supports balances, positions, and transactions
    Supports all asset classes

Platform Overview


In order to user our Simulation Broker use Dummy as the Broker, dummy as the username and dummy for the password. See the docs for more.

To help you get oriented with TradeIt’s API and what it can help you do, let’s start by defining some basics:

• API Key: Before using the API, you will need to sign up for an TradeIt developer account and have an API key issued to you.

Your API keys is different for each of our API environments. Always make sure you are using the correct key depending on your environment.

Use our Test Broker and Sandbox environments to build out and test your integration with simulated and live users, respectively. You’ll move over to our Production environment once you’re ready to go live!

• Sandbox: Test your integration with our test broker or live credentials

• Production: Production API environment

Simulation Broker


Not ready to dive into the full documenttion yet, we suggest you try our step by step guides in the section below.

Build and test your entire application logic with our Simulation Broker. In order to use our SImulation Broker use Dummy as the Broker, dummy as the username and dummy for the password. See the docs for more.

Most API requests interact with a session token and an account number. In order to get a session token your end users must first link their broker by going through an oauth flow: a web module that handles the credential and MFA validation process.

After succesfully linking their broker, TradeIt generates a user_token and user_id that uniquely identify a Linked User. You application needs to use the user_token and user_id along with your api_key to authenticate a Linked User and get a 30 minute session token.

Each Linked User can have many associated Accounts. For each Account, TradeIt returns then name, balance, positions and transactions information and enable placing new orders.

A single end-user of your application might have accounts at different brokers, which means they would have multiple different Linked Users with TradeIt.

Read on for more information about each of our products and how you place orders and access data for a Linked User.


We give you different ways to integrate with the TradeIt products

• In your website or desktop app: Start enabling Portfolio & Trading with our JSON API

• In your mobile app: Integrate our native mobile Ios and Android SDKs, which seamlessly bring PortfolioView and TradingTicket in your existing experience.


Explore step by step guides and some sample projects built by the trading team.


Web guide

Get the Code

Getting Started

First you will need to obtain an API key from TradeIt. Send an email to to request a key.

This guide will demonstrate how to create a sample Node.js application using the TradeIt JSON API. Alternatively you can also check out the source code from Github and work through the steps presented here.

The sample app will enable a user to:
• Link their broker
• Authenticate a session
• View their portfolio
• Place a trade

The sample app does NOT:
• Handle errors
• Persist sensitive tokens

These are important and will eventually need to be handled by your application where necessary.

Linking a broker

A user’s broker is linked via an OAuth flow.

Available brokers

Use the /getBrokerList endpoint to get the list of supported brokers and then render it in the page:

router.get('/', function(req, resp, next) {
    postData.apiKey = 'tradeit-test-api-key';
    options.url = '
    function callback(err, res, body) {
        if (err) {
            throw err
        resp.render('index', { list: body.brokerList });
    request(options, callback)


OAuth allows a user to link their brokerage accounts to your application. Successfully linking a user’s broker via OAuth will result in a userId and userToken. These are used to grant 15-minute sessions that can be used to take action on behalf of the user via the TradeIt API.

A diagram of the full OAuth flow:


The popup URL expires in 5 minutes.

Getting oAuth login URL

Make a request to the /getOAuthLoginPopupUrlForWebApp endpoint and pass in your API key and the user’s selected broker.


The URL should be opened in a popup window instead of embedding it in an iFrame. Most brokers consider popups a standard security protocol, and an iFrame is not obvious to the user that they are submitting credentials to another domain.

var getPopUpURL = function(broker) {
            data: {apiKey: "tradeit-test-api-key", broker: broker},
            dataType: "json",
            method: "POST",
            url: "",
            success: parseResult

When you’ve successfully retrieved the URL, open the login form in a popup window.

Retrieving the OAuth verifier

After the user has successfully submitted the login form, the popup window will send a javascript post message back to the parent page. You will need a Javascript event listener to handle capturing the OAuth verifier.


The oAuth-Verifier expires in 30 seconds.

var receiveMessage = function(e) {
        var data = JSON.parse(;
        var oAuthVerifier = data.oAuthVerifier;

if (window.addEventListener) {
    addEventListener("message", receiveMessage, false
} else {
    attachEvent("onmessage", receiveMessage);

Completing linking

Once you have received the OAuth verifier, you can use it to call /getOAuthAccessToken to get the userId/userToken.


userId and userToken expire in 30 days and can be re-linked.

var getTradeItTokens = function(oAuthVerifier) {
        data: {apiKey: "tradeit-test-api-key", oAuthVerifier: oAuthVerifier},
        dataType: "json",
        method: "POST",
        url: "
        success: authenticate

On success, userId and userToken are returned. Use them to call the /authenticate endpoint in order to establish a session for the user.

Important: The userId/userToken must be encrypted if persisted and never transmitted without using SSL.



Session token expires after 15 minutes of inactivity. Once expired, authenticate again to get a new session token.

Authenticating uses the userId/userToken to establish a 15-minute session that can be used to take action on behalf of the user via the TradeIt API. Pass the userId/userToken from the previous step to the /authenticate endpoint. If successful, the endpoint will return a session token that is used for subsequent API calls to retrieve portfolio data and place trades.


The srv query parameter that must be passed in the URL, not as a JSON field in the request payload. It can be a timestamp or UUID. It will be used in the event of a security question so it must be unique.

    data: {apiKey: "tradeit-test-api-key", userId: result.userId, userToken: result.userToken},
    dataType: "json",
    method: "POST",
    url: "",
    success: processAuthResult

Security questions

Some brokers may require a security question to be answered in order to complete authentication. If the status of the response from the /authenticate endpoint is “INFORMATION_NEEDED” instead of “SUCCESS”, you will have to show the security question and prompt the user for an answer.


The srv value must be the exact same as the value passed to the original authentication request.

var authWithSecurityQuestion = function(answer, token) {
            data: {apiKey: "tradeit-test-api-key", token: token, securityAnswer: answer},
                dataType: "json",
                method: "POST",
                url: "",
                success: processAuthResult

Upon submitting the user’s answer, you will receive either: •Another security question response (status: “INFORMATION_NEEDED”)
•A success response with a session token and a list of the user’s accounts. Now you can proceed to use the other API endpoints.


To fetch account overview data (/getAccountOverview) and positions data ( /getPositions) for a specific account, the following are needed:
• Session token: from the successful authentication call
• Account number: the list of account numbers for the linked broker is also returned in the successful authentication call

    data: {apiKey: "tradeit-test-api-key", token: sessionToken,
    accountNumber: account},
    dataType: "json",
    method: "POST",
    url: "",
    success: parseResult


An order must be previewed by the user before being submitted for execution. (see full documentation).

When we preview the order, we will make a request to /previewStockOrEtfOrder, passing in the order details and session token. See the following sample code:


Make sure to display the order details from the response for user to confirm.


orderId can only be used once to place an order. Even if you want to place an identical order, you must first preview the order to generate a new orderId and use it to place the order.

var getPreviewOrder = function() {
        var postData = {}
        postData.token = "{{data.sessionToken}}"
        postData.orderSymbol = $('#orderSymbol').val();
        postData.accountNumber = $('#accountNumber').val();
        postData.orderQuantity = $('#orderQuantity').val();
        postData.orderAction = $('select[name=orderAction]').val();
        postData.orderPriceType = $('select[name=orderPriceType]').val();
        postData.orderExpiration = $('select[name=orderExpiration]').val();

        data: postData,
        dataType: "json",
        method: "POST",
        url: "
        success: parseResult

On success, you will receive an orderId and see that the response’ status field is “REVIEW_ORDER”.

When user place an order, the /placeStockOrEtfOrder endpoint needs:
• The orderId generated from previewOrder
• Session token

On success, you will receive a confirmation message.

Error Handling

All requests can potentially return a standard error message:

    "longMessages": [
        "(00906A) The limit price you have entered is too far away from
        the Ask Price for this security. Please use the following
        guidelines when entering your limit price: For buy limit orders in
        which your limit price is below the current Ask Price, your limit
        price can be no more than 50% away from the Ask Price. "
    "shortMessage": "Could Not Review Your Order",
    "status": "ERROR",
    "token": "daeb18efb16c4c5fa798c25e95fcd54b"

The status field of the response is “ERROR”, while shortMessage, code and longMessages field provide details about the type of error.

It is important that the application handles different types of error. For instance:
• Session token expired, code 600: need to reauthenticate
userId/userToken expired, code 700: need to relink

See here for more errors


The dummy broker is a simulated broker that we created to test many use cases:

‘dummy’ - Test everything without error
‘dummyMultiple’ - Test multiple accounts without error
‘dummySecurity’ - Test the security question flow
‘dummyOptionLong’ - Test only a longer security question flow
‘dummyCompleteApplication’ - Trigger an authentication error.
Trade order error - Trigger a trading error by entering invalid data to field such as -1 in the quantity field.
Session expired - Close a session and all subsequent requests will fail and display an error message.

See here for more testing options


iOS guide

The TradeIt iOS SDK provides an easy way to integrate TradeIt services into an iOS app. This guide will walk through setting up and integrating the SDK with your app. There is also a runnable example app included with the SDK. Run the "Example App" target to try it out.

Example App

The SDK includes an example Swift app target, which provides the basic TradeIt services using the pre-built screens. To run, switch to the "Example App" target in Xcode and click run.

Getting Started


We support 2 choices of dependency manager:
• CocoaPods (Preferred)
• Carthage

If you have never used Cocoapods before, you can follow the Cocoapods: Getting started guide and Cocoapods: Using Cocoapods guide.

In your Podfile Add the TradeIt spec repo as a source and the Ticket SDK pod as a dependency of the project target:

source ''
source ''

target 'YourProjectTargetName' do
    pod 'TradeItIosTicketSDK2', '~> 1.1.0'

Then in the terminal run:

pod repo update
pod install

To integrate the TradeIt SDK into your Xcode project using Carthage, specify it in your Cartfile:

github "tradingticket/TradeItIosTicketSDK2" ~> 1.1.0



Both the QA and Production environments use the brokers' production environments!







Using the SDK

There are 2 ways to use the TradeIt iOS SDK:
• The SDK includes pre-built screens and UI workflows that minimize the effort required to integrate TradeIt OAuth, trading and portfolio with the TradeIt API trading workflow and users’ portfolio data.
• The SDK also includes a set of classes that allow developers to build custom screens and UI work. See Custom Integration

Configuring the SDK

This must occur before using any functionality of the SDK. If it is not called first, subsequent calls will cause the app to terminate!

    apiKey: API_KEY, // obtained by emailing
    oAuthCallbackUrl: URL(string: "yourAppScheme://completeOAuth")!, // Use the existing deep link scheme for your app
or register a new one
    environment: TradeItEmsTestEnv

Linked Broker Persistence

Linked brokers (and the associated trading account info) are persisted on the device between uses of your app so that users only need to link their broker with your app once. The linked brokers will be reloaded when your app is relaunched and the TradeItSDK is re-instantiated with the call to TradeItSDK.configure(). Persistence is implemented using the secure iOS keychain.


Launching TradeIt Screens

Almost all TradeIt functionalities can be quickly and easily integrated just by launching the pre-built TradeIt screens from the SDK as shown in the ExampleViewController file of the example app.

Linking a user’s broker

The broker linking UI flow can be launched like this:

TradeItSDK.launcher.launchBrokerLinking(fromViewController: self)

If the user has no previously linked broker, launching any of the pre-built TradeIt screens will result in the user first being prompted to link a broker with the following screen:

When a user has successfully authorized the linking, the SDK will deep link back into your app using the OAuth callback URL specified when you initialized the TradeItSDK. Your app should intercept the deep link and pass the callback URL and the top most currently presented view controller to TradeItSDK.launcher.handleOAuthCallback to complete the OAuth flow like this:

// In AppDelegate func application(
    _ application: UIApplication,
    open url: URL,
    sourceApplication: String?,
    annotation: Any) -> Bool {
// Make sure to verify the deep link URL is the one you   
specified for the TradeItSDK before proceeding with launching 

// Get the top view controller to pass to the launcher. The 
below example works in the general case, but your app may need to 
implement custom logic to get the top-most presented view 

    if var topViewController = UIApplication.shared.keyWindow?.rootViewController {
    while let presentedViewController = topViewController.presentedViewController {
            topViewController = presentedViewController

        if let navController = topViewController as?UINavigationController,
        let navTopViewController = navController.topViewController {
            topViewController = navTopViewController

    topViewController, oAuthCallbackUrl: url)
    return true

Launch Portfolio

By default the first valid account is preselected.

TradeItSDK.launcher.launchPortfolio(fromViewController: self)

Launch Portfolio with a specific account pre-selected

let  linkedBroker =
let  account = linkedBroker.accounts.first

TradeItSDK.launcher.launchPortfolio(fromViewController: self,
forLinkedBrokerAccount: account)

Launch Trading

TradeItSDK.launcher.launchTrading(fromViewController: self)

Launch Trading with a pre-configured order

If a TradeItOrder is passed when launching trading, the trading ticket screen inputs will be pre-populated from the provided order.

let  order = TradeItOrder()
order.symbol = "SYMB"
order.quantity = 100
order.action = .buyToCover
order.expiration = .goodForDay
TradeItSDK.launcher.launchTrading(fromViewController: self,
withOrder: order)

Launch Account Management

TradeItSDK.launcher.launchAccountManagement(fromViewController: self)

Launch Account Linking

TradeItSDK.launcher.launchBrokerLinking(fromViewController: self, 
onLinked: { linkedBroker in
    print("Newly linked broker: \(linkedBroker)")
}, onFlowAborted: {
    print("User aborted linking")

Disabling Portfolio

To configure whether the Portfolio screen is accessible from the Trading flow use:

TradeItSDK.isPortfolioEnabled = false


In order to visually integrate the TradeIt screens in to your app, you can create a TradeItTheme object. The SDK includes a light and dark theme which you can modify as needed.

// Set light theme
TradeItSDK.theme = TradeItTheme.light()

// Set dark theme
TradeItSDK.theme = TradeItTheme.dark()

Error Handling

The TradeItTheme object has the following properties to let you customize further:

let theme = TradeItTheme()

theme.textColor // standard text color
theme.warningTextColor // warning text color

theme.backgroundColor // background color used on most screens
including trading and linking screens
theme.alternativeBackgroundColor // background color used on the
portfolio screen

theme.tableHeaderBackgroundColor // table header background color
theme.tableHeaderTextColor // table header text color

theme.interactivePrimaryColor // standard background color for 
theme.interactiveSecondaryColor // standard text color for buttons

theme.warningPrimaryColor // warning background color for buttons
theme.warningSecondaryColor // warning text color for buttons

theme.inputFrameColor // color used to frame input elements like

TradeItSDK.theme = theme

Custom Integration

Custom integration refers to using the TradeItSDK.linkedBrokerManager object as a programmatic workflow upon which you can build your own workflow and screens or use the user's raw balance/positions data in your app. The linkedBrokerManager can be used to link/relink/unlink a user's broker logins. It holds the list of linked brokers in TradeItSDK.linkedBrokerManager.linkedBrokers. Each of these TradeItLinkedBroker objects can be used to authenticate an active session with the broker. Once this has been done, the list of trading accounts associated with the linked broker are stored in linkedBroker.accounts. Each of these TradeItLinkedBrokerAccount objects can be used to trade and retrieve balances and positions.

In this example below, we showcase a simple way to use TradeItLinkedBrokerAccount to pull balances and positions.

// Account balances - given an authenticated broker account
linkedBrokerAccount.getAccountOverview(onSuccess: {
}, onFailure: { errorResult in

// Account positions - given an authenticated broker account
linkedBrokerAccount.getPositions(onSuccess: { positions in
    print({ position in
        return position.position
}, onFailure: { errorResult in

For more details and code examples, please refer to the Wiki Page.


The Dummy broker is a simulated broker used to perform tests without connecting a live broker account in the QA environment. All of the API interactions are stateless and return fake data.

Depending on the username you choose (password will always be “pass”), you can emulate many use cases. See below for some examples:




No error


Returns security question response


Returns a user with 6 accounts


Used to test session expiration. Links and authenticates, then expires the session after 4 requests until the session is reauthenticated


Used to test OAuth token invalidation/expiration. Links and authenticates, then expires the OAuth token by relinking an expired session, which expires after 4 requests


Used to reproduce the IB account activation in progress: Returns 800 error (activation in progress) for 10 minutes


Returns a no account error message upon authentication


Returns null values for every field that can potentially return as null


Returns error response if request is to place a sell short or buy to cover

When placing orders with our dummy accounts, we simulate broker warning messages.

Order Size


Quantity < 50

Review response with no warning messages

50 <= Quantity < 100

Review response with warnings and acknowledgement messages

Quantity >= 100

Returns error response