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.
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
Desktop applications and non-standard mobile implementations need to use the TradeIt oAuth page and follow the outlined flow:
- Request the PopUp URL user/getOAuthLoginPopupUrlForWebApp
- Open the returned PopUp URL in a new window, so the user can login
- 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.
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
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.
The list of capabilities for each broker is returned by the
/getBrokerList endpoint. See LIST AVAILABLE BROKERS section for reference.
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.
|instrument||string||the type of instrument. Possible values: "equities", "fx", "options", "crypto".|
|actions||Array of OrderActionCapability||Possible values for
|priceTypes||Array of OrderPriceTypeCapability||Possible values for
|expirationTypes||Array of DisplayLabelValueObject||Possible values for
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.
|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|
|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|
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:
|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
|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:
|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:
|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)|