Go to top ↑
Menu
OVERVIEW JSON API iOS SDK Android SDK

Overview

Welcome to TradeIt!

Below you will find overview for using the TradeIt API.

Before running the API in your production environment, you will need to have a unique API key issued to you.

Although we have done our best to illustrate function calls with sample JSON request/response objects, please make sure to peruse the details of each method, as not all scenarios can be possibly covered.

Our API is architected around a JSON-pure approach. We use standard HTTP to communicate as well as JSON responses to indicate status and errors. All responses come in standard JSON format.

The TradeIt API is served over HTTPS to ensure data privacy. Request data is included within the body as JSON, with the exception of the SRV param which is passed along the query string for the authentication and security question requests.

The basic flow is centered around using our oAuth flow to create a userToken. Using this userToken you can authenticate the user to establish a 30 minute session. Successful authentication will return a session token that is required for all subsequent API calls.

All tokens to expire after 30 days, at which point a renew token function will need to be called and the user re-authenticated. We also provide a delete token function that should be implemented in the event the user wants to disconnect from your service.

Still have questions? Get in touch.

Implementation Guidelines

Testing & Environment

Make sure to build and test your code against our testing environment before deploying to production.
TradeIt Testing Environment: https://ems.qa.tradingticket.com
TradeIt Production Environment: https://ems.tradingticket.com

While using the TradeIt testing environment, all broker connections are made to the LIVE broker environments.

In order to test the flow without executing a trade, use our virtual Dummy Broker. Click here to find out more about using the Dummy Broker

Authentication & Token Storage

Mobile implementations should use the iOS SDK or Android SDK to create and retrieve tokens.

Desktop applications and non-standard mobile implementations need to use the TradeIt oAuth page and follow the outlined flow:

  1. Request the PopUp URL user/getOAuthLoginPopupUrlForWebApp
  2. Open the returned PopUp URL in a new window, so the user can login
  3. On successful login, the page uses a javascript post message to alert your site with an oAuthVerifier token
  4. You'll post this to your server and then request user/getOAuthAccessToken to receive the userId and userToken

Check out LINK A BROKER section for more information, and examples.

NOTE: After 3 invalid login attempts in a row, the user IP will be blocked from TradeIt servers for a duration of 5 minutes.

Broker Branding

TradeIt does not hold the trademark rights to the brokers it supports. Some brokers are more sensitive than others about protocols for branding and advertising. Therefore, we ask that you refrain from building broker-branded content into your UX, unless you have a specific arrangement with a broker for co-promotion that uses their branding.

TradeIt Logo and Terms Link

Please include “powered by TradeIt” somewhere in the UX for authenticating or linking an account. Also, we require that you include a link to our terms and conditions, which are located at: https://www.trade.it/terms

Capabilities

In order to provide a smooth and efficient user experience, your app should take in to account the trading instruments and services that are available for a given linked broker or account.

Broker capabilities

The list of capabilities for each broker is returned by the /getBrokerList endpoint. See LIST AVAILABLE BROKERS section for reference.

Account capabilities

Each account associated with a linked broker has different trading capabilites. When the authenticate request is made for a linked broker, the response contains a list of the user's accounts associated with that linked broker. Each account in the response will contain a list of order capabilities specific to that account.

Order capabilities must be used to display the list of actions, price types, expiration types, quantity types available to the user in the trading ticket.

Order Capability Object

Order capabilities must be used to display the list of actions, price types, expiration types, quantity types available to the user in the trading ticket. See the TRADE section for reference.

Field Type Description
instrument string the type of instrument. Possible values: "equities", "fx", "options", "crypto".
actions Array of OrderActionCapability Possible values for value property corresponds to the orderAction post parameter Possible values for supportedOrderQuantityTypes property corresponds to the orderQuantityType post parameter
priceTypes Array of OrderPriceTypeCapability Possible values for value property corresponds to the orderPriceType post parameter Possible values for supportedOrderQuantityTypes property corresponds to the orderQuantityType post parameter
expirationTypes Array of DisplayLabelValueObject Possible values for value property corresponds to the orderExpiration post parameter

Error Handling

All requests can potentially return our standard error message. We provide a table of error codes and meanings below.
For the few methods that specify so, we also return a short and long message that should be presented to the user.
Generally, the short message can be used as title and the long messages as the body.

Field Type Details
code int See table below for code meanings
longMessages array[string] An array of strings to be presented to the user.
shortMessage string The general error message
status string Will always be ERROR
token string User's session token
Code Meaning
100 System Error
101 Concurrent Authentication Error - Triggered when we are currently processing a login for a user and second request for the same user comes in.
200 Broker Execution Error - User should modify the input for the trade request
300 Broker Authentication Error - Authentication info is incorrect or the user may have changed their login information and the oAuth token is no longer valid.
301 Too Many Login Attempts Error - After 3 invalid login attempts in a row, the user IP will be blocked from TradeIt servers for a duration of 5 minutes.
400 Broker Account Error - User credentials are valid, but needs to take action on the brokers site (ie. sign exchange agreement, sign margin agreement)
500 Params Error - Publisher should check the parameters being passed in
600 Session Expired - Publisher should call authenticate again in order to generate a new session token
700 Token invalid or expired - Publisher should call oAuthUpdate in order to refresh the token
800 Broker Account not available - The broker account is being activated. User will have to authenticate in one or two business day

Testing

Dummy broker account

In the QA environment there is a Dummy broker available to perform tests without connecting a live broker account. All of the API interactions are stateless and return fake data. To login, select the Dummy broker and use any of the usernames listed below, the password will always be pass. You can emulate the following scenarios:

username response
dummy no errors
dummyNotMargin returns error response if request is to place a sell short or buy to cover. Only buy and sell will be returned in the account capabilities response
dummyNull returns null values for every field that can potentially return as null
dummySecurity returns security question response (answer is tradingticket)
dummyMultiple returns a user with multiple accounts, specifically:
∟ ************005 An account that returns options instrument in the capabilities
∟ ************006 An account that returns no positions
∟ ************009 An account that supports equity and crypto. Use this account to test crypto position, crypto order status, crypto transaction, crypto preview and trade
dummyDelay used to reproduce the IB account activation in progress: once you link dummyDelay, the error 800 will be returned for ten minutes
dummy600 expires sessionToken after 4 requests
dummy700 expires userToken after re-authenticating a sessionToken, which expires after 4 requests
dummyAction returns 400 Broker Account Error (Your broker needs more information before you can trade. Please visit your broker website for details.) on authentication
dummyNoAccount returns 400 Broker Account Error (Your broker requires an active account before you can trade. It's possible your funds have yet to clear or an agreement needs to be signed. Please visit your broker website for more information.) on authentication
dummyQuote returns 400 Broker Account Error (Your broker requires you to sign or update your Real-Time quote agreements before you can trade. Please visit your broker website for more information.) on authentication
dummyFailTrade returns 200 Broker Execution Error (Could not place trade) for each trade request with quantity above 10
dummyRetirement returns 400 Broker Account Error (You cannot trade this kind of security in a retirement account. Please visit your broker to open a brokerage account.) on authentication
dummyCanDisableMargin returns true for userCanDisableMargin flag in the authentication response
dummyLinkError returns 100 System Error (Could not complete linking. Please try again.) on linking with oAuthVerifier
any other ID that is not dummy returns error response with authentication error

When username is dummy, dummyMultiple or dummySecurity:

Order Size Returns
quantity is below 50 returns review response with no warning messages
quantity is between 50 and 99 returns review response with warnings and ack messages
quantity is 100 and up returns error response

For all dummy brokers:

action when returns
Authentication password is NOT pass or expires-after-(digit) 300 Broker Authentication Error (Check your username and password and try again.)
Cancel order orderNumber is invalidOrderNumber 200 Broker Execution Error (Invalid order number)
Get single order orderNumber is invalidOrderNumber 200 Broker Execution Error (Invalid order number)
Review order orderInfo.symbol is INVALIDSYMBOL 200 Broker Execution Error (Invalid symbol)

Live broker accounts

Be aware that our staging environment only works with dummy broker and that production points to live broker environments. Connecting a live non-dummy broker account while pointing to production will perform real trade requests to brokers.