Interactive Brokers offers the ability to trade, monitor and manage your IB account using a single RESTful API.
With the Client Portal Web API:
There is no need for special libraries to integrate with your application.
You use only a small, headless gateway to connect to your application.
Additional security with IP restrictions is available.
Enjoy access to data that's not available through our existing APIs, including PortfolioAnalyst, Statements, Transaction History (up to 90 days) and more.
Getting Started
You must have Java 8 update 192 or higher installed (gateway is compatible with higher Java versions including OpenJDK 11).
Download and unzip the CP WebAPI gateway from the website.
New gateway versions will be released frequently so its recommended to periodically use the gateway download link to download the current version. Version release notes are under development and will be available in the future.
Navigate to the directory where the gateway has been unzipped in a command prompt.
Launch the gateway with the command "bin\run.bat root\conf.yaml" (on Windows) or "bin/run.sh root/conf.yaml" (on Mac/Unix).
The port number is 5000 by default and set in the root/conf.yaml configuration file.
Authenticate with your username/password and second factor device (for production accounts).
Note you can login to paper accounts by using the paper account-specific username/password combination.
Every paper account has its own username. The paper account username can be found in Client Portal at: Settings -> Account Settings -> Paper Trading Account -> Configure You can also reset your paper trading account password there if necessary.
You should receive the message "Client login succeeds" after successful authentication. The tab can then be closed.
It is expected that gateway will require restart and reauthentication at least daily. If left inactive, the gateway session will automatically timeout for security reasons within a few minutes and all endpoints will return 401: Access Denied errors. An active session can be extended by pinging the /portal/sso/validate endpoint are regular time intervals, such as once per minute.
Download the current OpenAPI specification as a JSON file
Important Notes
Brokerage Session
A brokerage session is necessary to access order information, place orders, or receive market data, and involves a distinct set of backend processes from other functionalities such as looking up historical account information. Trading applications such as TWS or IBKR mobile only utilize a brokerage session. A given username can only create a single brokerage session at a time, so launching TWS will disconnect a brokerage session in the CP API, and vice versa.
From the CP API a brokerage session is accessed with any of the endpoints containing iserver. So if a user does not have trading permissions and is unable to login to TWS, though they can still login to Client Portal, they will not be able to access the iserver endpoints. Before accessing other iserver endpoints, the endpoint /portal/iserver/auth/status should first be called. If it returns {authenticated: false...}, then there is not a valid brokerage session and a user can attempt to create a brokerage session with the /portal/iserver/reauthenticate endpoint.
Sequence of Endpoints
Most endpoints are independent, however in a few cases an endpoint must first be preceded by a different endpoint.
Notably, /portfolio/accounts must be called prior to other /portfolio in an individual account structure, and /portfolio/subaccounts must be called first in an advisor or master account structure. This will return the list of accounts that are valid to use with the other /portfolio endpoints. It is important to note that the account list returned from the /portfolio endpoint can differ from the account list returned from the /iserver endpoint, since the /iserver endpoints refer to those accounts which the username has trading access to under a brokerage session.
Limitations on orders and trades queries
The endpoints /orders and /trades which query the day's live orders and trades will return at most 1000 items. If more trades than 1000 are needed it would be advised to reachout to the API Group directly to have your user configured.
Note that it is also possible to setup flex queries via the web to return executions.
The limitation of 1000 also applies to order information returned from a websocket.
Contract ID (ConId) Lookup
ConIds uniquely specify an instrument in the IBKR database and are needed for many endpoints. To receive the ConId for a stock, the endpoint /iserver/secdef/search can be used, and for futures the endpoint /trsrv/futures can be used. For option lookups there is an additional step described here.
A demo app demonstrating streaming websocket data is provided with the gateway download and accessible at: https://localhost:5000/demo/#/ (assuming gateway is running locally on the default port 5000).
Third Party Tools:
The API uses a standard swagger format compliant with the OpenAPI 2.0 specification for RESTful APIs, so there are a wealth of third party tools available for automatically generating code meeting the API specifications.
Query endpoints directly from your browser with the Swagger-UI interface
Generate client code in the language of your choice by loading the OpenAPI JSON specification into the Swagger Editor
Troubleshooting & Initial Endpoints
To troubleshoot an issue with an unexpected response, first try the endpoints in the below order and note the response. That can be done directly from this site, or with a tool of your choice that logs the raw HTML header + body.
Base URL:
Keeping Session Alive
If left inactive a session will timeout within a few minutes. It can be kept alive by calling /portal/sso/validate can be called at regular intervals.
Interval: seconds
Keeping a brokerage session alive
This script calls /portal/iserver/auth/status every minute, and if authenticated : false is returned,
automatically calls /portal/iserver/reauthenticate to attempt to initiate a brokerage session.
Base URL
Last Request: {{ logs.request }} Time: {{ logs.timestamp }} Last Response: {{ logs.response }}
Reauthentication attempts: {{reauthAttempt}}
Current issues under review
The configuration file conf.yaml used for the CP gateway has a field origin.allowed for the domain of originating requests. However the endpoint /am/user may trigger a CORB (Cross-Origin Resource Blocked) error. This issue is under review with the development group. At the current time there are different 3rd party tools available to circumvent this issue, such as the browser extensions:
* Note these extensions are not secure to have enabled for general web browsing.
Extending the gateway session- though pinging the endpoint /portal/sso/validate can extend a session, gateway may sometimes need to be restarted intraday. The possibility of avoiding intraday restarts so that gateway can typically remain running all day from a single authentication is under review.
To report issues to customer service:
Be sure to include the timestamp of requests, with the raw HTML header and raw HTML body
Do not send unencrypted logs with any personal information via email. Instead use the secure Message Center in Client Portal.
