Menu

Get started

Tip

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 easily and securely on web or mobile and enable:

  • 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

Tip

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

Tip

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.

Integration

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 PortoflioView and TradingTicket in your existing experience.

Guides

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

Menu

Web guide

Get the Code

Getting Started

First you will need to obtain an API key from TradeIt. Send an email to contact@trade.it 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 = 'https://ems.qa.tradingticket.com/api/v1/
    preference/getStocksOrEtfsBrokerList';
  
    function callback(err, res, body) {
        if (err) {
            throw err
        }
        resp.render('index', { list: body.brokerList });
    };
    request(options, callback)
});
                                
                            

OAuth

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:

Tip

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.

Tip

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) {
        $.ajax({
            data: {apiKey: "tradeit-test-api-key", broker: broker},
            dataType: "json",
            method: "POST",
            url: "https://ems.qa.tradingticket.com/api/v1/user/getOAuthLoginPopupUrlForWebApp",
            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.

Tip

The oAuth-Verifier expires in 30 seconds.

var receiveMessage = function(e) {
        var data = JSON.parse(e.data);
        var oAuthVerifier = data.oAuthVerifier;
        getTradeItTokens(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.

Tip

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

var getTradeItTokens = function(oAuthVerifier) {
    $.ajax({
        data: {apiKey: "tradeit-test-api-key", oAuthVerifier: oAuthVerifier},
        dataType: "json",
        method: "POST",
        url: "https://ems.qa.tradingticket.com/api/v1/user/
        getOAuthAccessToken",
        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.

Authenticating

Tip

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.

Tip

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.

$.ajax({
    data: {apiKey: "tradeit-test-api-key", userId: result.userId, userToken: result.userToken},
    dataType: "json",
    method: "POST",
    url: "https://ems.qa.tradingticket.com/api/v1/user/authenticate?srv=",
    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.

Tip

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

var authWithSecurityQuestion = function(answer, token) {
        $('#answer').val('');
        $.ajax({
            data: {apiKey: "tradeit-test-api-key", token: token, securityAnswer: answer},
                dataType: "json",
                method: "POST",
                url: "https://ems.qa.tradingticket.com/api/v1/user/answerSecurityQuestion?srv=05040504",
                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.
•Or an error response [SEE SOME ERROR HANDLING SOMETHING SOMEWHERE]

Portfolio

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

$.ajax({
    data: {apiKey: "tradeit-test-api-key", token: sessionToken,
    accountNumber: account},
    dataType: "json",
    method: "POST",
    url: "https://ems.qa.tradingticket.com/api/v1/position/getPositions",
    success: parseResult
 });
                                
                            

Trading

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:

Tip

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

Tip

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

    $.ajax({
        data: postData,
        dataType: "json",
        method: "POST",
        url: "https://ems.qa.tradingticket.com/api/v1/order/
        previewStockOrEtfOrder",
        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:

{
    "code":200,
    "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

Testing

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

Menu

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

Installation

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 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/tradingticket/SpecRepo'

target 'YourProjectTargetName' do
    use_frameworks!
    pod 'TradeItIosTicketSDK2', '~> 1.1.0'
end

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

Usage

Tip

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

Environment

Enum

QA

TradeItEmsTestEnv

Production

TradeItEmsProductionEnv

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!

TradeItSDK.configure(
    apiKey: API_KEY, // obtained by emailing contact@trade.it
    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.

Integrating

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 
handleOAuthCallback

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

    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
        }

    TradeItSDK.launcher.handleOAuthCallback(onTopmostViewController:
    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 =
TradeItSDK.linkedBrokerManager.linkedBrokers.first
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

Themes

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 
buttons
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
UITextField

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: {
    print(linkedBrokerAccount.balance)
}, onFailure: { errorResult in
    print(errorResult)
})

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

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

Testing

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:

Username

Response

dummy

No error

dummySecurity

Returns security question response

dummyMultiple

Returns a user with 6 accounts

dummy600

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

dummy700

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

dummyDelay

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

dummyNoAccount

Returns a no account error message upon authentication

dummyNull

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

dummyNotMargin

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

Returns

Quantity < 50

Review response with no warning messages

50 <= Quantity < 100

Review response with warnings and acknowledgement messages

Quantity >= 100

Returns error response