Trading Web API

Introduction

Copy Location

Interactive Brokers (IBKR) RESTful Web API is designed to provide users with seamless, secure, and real-time access to their IBKR account. The Web API runs parallel to the IBKR hosted application, providing users with scalable, and efficient access to essential services. Our API is split into two key components:

• Account Management: Provides solution for Introducing Brokers and Financial Advisors to preserve their current user experience and interface design while relying on IBKR’s brokerage services. Advisors and brokers can integrate with the Account Management API to manage Client Registration, Client Account Maintenance, User Authentication, Funding, and Reporting.
• Trading: Our trading API is available to all IBKR clients free of cost and can be used to manage trades, view real-time portfolio information, access market data, view contract information, and authenticate for brokerage sessions.

Connectivity

Copy Location

IBKR’s Web API implementation follows standard HTTP verbs for communication. It employs a range of HTTP status codes and JSON-formatted messages to convey operation status and error information. To ensure secure communication, all API requests must use HTTPS. Authorization and Authentication for IBKR’s Web API is managed using OAuth 2.0.

Authentication

Copy Location

IBKR only supports private_key_jwt client authentication as described in RFC 7521 and RFC 7523.

• Client authenticates against the authorization server by presenting a signed JWT token called a client_assertion which the authorization server validates against the public key(s) provided by the client during registration.
• This scheme is considered safer than the standard client id/client secret authentication scheme used in early OAuth 2.0 integrations given that it prevents the client from having to pass the client secret in back-end requests.

Data Transmission

Copy Location

User requests will be sent to IBKR in JSON format using HTTPS.

References

Copy Location

We know that great documentation makes all the difference. In addition to IBKR’s dedicated API Integration team, IBKR provides documentation for both the developer AND project managers.

• Documentation: Within our long form documentation we include best practices, flow charts, and descriptions to help users maximize the API’s potential.
• Reference: Our API reference includes detailed endpoint references, schema requirements, authentication guides, and sample request and responses.

Getting Started

Copy Location

Retail

Copy Location

For retail and individual clients, Authentication to our WebAPI is managed using the Client Portal Gateway, a small java program used to route local web requests with appropriate authentication. Click here to get started.

Institutional or Third Party

Copy Location

We understand that enterprise integrations can be more complex. We have a designated API Solutions team that will help in creating solution that aligns with your business objectives. To get started, please contact our API Solutions (e-mail: api-solutions@interactivebrokers.com) with the following information:

• Firm Name
• Firm Type (ie. Introducing Broker, Financial Advisor OR Third Party Service Provider)
• API Services which you are interested in using (ie. Registration, Funding, Single Sign On, View Portfolio Data, Trading, Reporting)
• Describe intended usage (1-2 sentences)

Feedback

Copy Location

Have feedback on our Web API documentation or reference material?

Email us at API-Feedback@interactivebrokers.com.

We value your suggestions, ideas, and feedback in order to continuously improve our API solutions.

This is an automated feedback inbox and unfortunately, we will not be actively responding from this email. However, if you need a specific answer or additional support, please contact our API Support team or access our general support. Current or prospective institutional clients may also contact their sales representative.

Getting Started with the Trading API

Copy Location

Clients with fully open and funded accounts may use our Web API's Trading features to trade their accounts immediately, without any onboarding or approval process.

However, our Web API's Trading functionality is accessible via several methods of authentication in addition to OAuth 2.0, some of which do require approval or configuration prior to use.

Trading Access for Organizations

Copy Location

Enterprise and Institutional clients have several methods of authorization and authentication at their disposal. All methods permit requests to be made directly to Interactive Brokers' infrastructure.

The list below outlines the general suitability of the available methods for various use-cases. For a more thorough discussion of these access methods, please contact our API Integrations team.

• OAuth2.0 (beta)
  • Supports first-party (accessing one's own accounts) and third-party (accessing the accounts of unaffiliated IB clients with their authorization) usage
  • Offers access to account management and trading features
• OAuth1.0a
  • Supports first-party (accessing one's own accounts) and third-party (accessing the accounts of unaffiliated IB clients with their authorization) usage
  • Offers access to trading features only
• SSO
  • Available to Financial Advisors and Introducing Brokers
  • Supports the development of alternative UIs specifically for clients under your management
  • Offers access to account management and trading features

Trading Access for Individuals

Copy Location

Trading in the Web API for individual clients involves an IBKR username and password.

Whether accessing a live account or its associated simulated paper account, the live account must be fully open and funded. The live account must also be of the "IBKR Pro" type.

If you do not already have an account, you can create one for free.

Trading Access for Third Parties

Copy Location

Interactive Brokers identifies third-party developers as vendors of software that would interact with IB client accounts to which the vendor has no formal relationship or access within IB. This is in contrast to an advisor or introducing broker who maintains an account structure with IB and formally manages client accounts.

Third-party vendors may currently only seek approval for the use of OAuth1.0a.

Third-party vendors must receive Compliance approval for their product offerings before integration can proceed.

The third-party approval process begins with the submission of a third-party onboarding questionnaire.

Please note that vendors are expected to have an established business entity and a public presence online with material describing their offering. Proof of concept builds to demonstrate intended functionality are strongly encouraged as well. The onboarding process typically proceeds as follows:

1. Our onboarding team conducts the initial screening. Estimated time to complete this step is 2-3 weeks. If our onboarding team is able to proceed with your request for approval, they will send your application to our Compliance team for review.
2. IBKR Compliance conducts an enhanced due diligence review on all third-party applicants, followed by a three-tier approval process. Estimated time to complete Compliance-related reviews and tasks is 3-6 weeks.
3. If Compliance grants approval, our Legal team will generate a Web API agreement which will be relayed to you for review and signature. In parallel, our third-party onboarding team will ask you to provide public keys and a callback URL in support of the configuration of your OAuth1.0a consumer. Detailed instructions for this process will be provided once this stage is reached. Estimated time for IB complete our portions of the aforementioned process is 3-5 weeks.

The above timelines are estimates and can vary. We recommend providing as much information as possible up front. Not doing so can extend timelines.

During the enhanced due diligence reviews conducted by our Compliance teams, they will expect vendors to have a completed website with finalized details of the product offering. This typically includes a clear user workflow for all components and descriptions of their functionality and capabilities.

Should Compliance approval be reached for your product offering, any significant changes to the offering following approved (such as the addition of trading functionality) would require additional review and approval from our Compliance teams before being offered to IBKR clients.

Please be aware we expect third-party vendors offering automated trading solutions to hold applicable registration with financial authorities in all regions they plan to service, unless the vendor is able to provide support (i.e., a legal opinion) as to why the proposed service would not require registration in a given location. Additionally, the offering will need to be reviewed and approved by Compliance teams in all regions in which you intend to serve IBKR clients.

Usage and Availability

Copy Location

Scheduled Server Maintenance

Copy Location

Interactive Brokers conducts scheduled maintenance on the infrastructure that serves the Web API. During maintenance windows, some features of the Web API are momentarily unavailable.

The timing of the Web API's maintenance windows vary slightly from the those observed in other platforms, such as Trader Workstation.

The Web API itself is accessible 24 hours a day during the week. It receives maintenance only on Saturday evenings.

Brokerage functionality (provided by /iserver endpoints) is briefly unavailable each evening at approximately 0100 local time by region.

Weekday IServer Reset Timing

Copy Location

| Region | Maintenance Onset | | :---------- | :--------- | | North America
(NY and Chicago) | 01:00 US/Eastern | | Europe | 01:00 CEST | | Asia | 01:00 HKT |

Pacing Limitations

Copy Location

Interactive Brokers currently enforces a global request rate limit of 50 requests per second for each authenticated username -- that is, each Web API session.

Users making requests via the CP Gateway tool are restricted to 10 requests per second.

Additionally, some endpoints are also subject to their own pacing limits as described in the table below.

When a rate limit is exceeded, the Web API will return a 429 Too Many Requests status code.

Violator IP addresses may be put in a penalty box for 10 minutes. After this period, the IP address is removed from the penalty box. Repeat violator IP addresses may be permanently blocked until the issue is resolved.

Per-Endpoint Request Rate Limits

Copy Location

| Endpoint | Method | Limit | | :---------------------------------- | :----: | :-------------------- | | /iserver/marketdata/snapshot | GET | 10 req/s | | /iserver/scanner/params | GET | 1 req/15 mins | | /iserver/scanner/run | POST | 1 req/sec | | /iserver/trades | GET | 1 req/5 secs | | /iserver/orders | GET | 1 req/5 secs | | /iserver/account/pnl/partitioned | GET | 1 req/5 secs | | /portfolio/accounts | GET | 1 req/5 secs | | /portfolio/subaccounts | GET | 1 req/5 secs | | /pa/performance | POST | 1 req/15 mins | | /pa/summary | POST | 1 req/15 mins | | /pa/transactions | POST | 1 req/15 mins | | /fyi/unreadnumber | GET | 1 req/sec | | /fyi/settings | GET | 1 req/sec | | /fyi/settings/{typecode} | POST | 1 req/sec | | /fyi/disclaimer/{typecode} | GET | 1 req/sec | | /fyi/disclaimer/{typecode} | PUT | 1 req/sec | | /fyi/deliveryoptions | GET | 1 req/sec | | /fyi/deliveryoptions/email | PUT | 1 req/sec | | /fyi/deliveryoptions/device | POST | 1 req/sec | | /fyi/deliveryoptions/{deviceId} | DELETE | 1 req/sec | | /fyi/notifications | GET | 1 req/sec | | /fyi/notifications/more | GET | 1 req/sec | | /fyi/notifications/{notificationId} | PUT | 1 req/sec | | /tickle | GET | 1 req/sec | | /sso/validate | GET | 1 req/min |

Additional Usage Limits

Copy Location

| Endpoint | Method | Limit | | :---------------------------------- | :----: | :-------------------- | | /trsv/secdef | POST | 200 conids/request | | /iserver/marketdata/history | GET | 5 concurrent requests |

Trading Sessions in the Web API

Copy Location

Access to Trading functionality in the Web API entails the creation of a trading-enabled brokerage session.

A brokerage session is associated with an IB username (your credentials), which in turn has trading permissions for one or more accounts (the actual pools of equity).

A single username can only have one brokerage session active at a time across all IB platforms.

Permissions for trading in general, for specific asset classes, market data subscriptions (and thus access to the subscribed feeds), etc. are carried by IB usernames, not the underlying accounts. Hence references to brokerage sessions refer to a logged-in username that is in contact with IBKR’s backend trading infrastructure.

Though Interactive Brokers permits a username only one brokerage session at any given time, some of the Web API's Trading functionality is accessible without a brokerage session. This allows a username's active brokerage session to continue elsewhere undisturbed.

We typically refer to these non-brokerage features as the "read-only" subset of the Trading portion of the Web API. Examples of read-only features include retrieval of portfolio data and certain instrument search tools. When trading with the Web API, sessions can therefore be thought of as two-tiered:

1. An "outer" prerequisite read-only session that is required to be active/valid in order to make any CP Web API request, though by itself it only permits access to non-/iserver endpoints.
2. The brokerage session, established after the read-only, that permits access to trading, consumption of market data, and all other functionality behind /iserver endpoints.

Instrument Discovery

Copy Location

The Web API requires the use of IB's contract ID ("conid") to uniquely specify instruments. Knowledge of a particular instrument's conid is required to retrieve intrument trading rules and market data, and also to submit orders.

The Web API offers several ways to retrieve our conid identifier, as well as well as all other attributes of the the instruments we offer for trading.

Note that IB conids are persistent for the life of an instrument. Therefore, we recommend retrieving conids and storing them locally prior to trading.

Contract IDs

Copy Location

Before we can use the Web API to interact with a financial instrument, we must first determine its unique conid.

We start by searching IB's instrument database by symbol. Three endpoints exist to facilitate this step. All three endpoints will return all matching records within their scope. Subsequent requests will can further filter this result set.

Equities

Copy Location

The following endpoint is designed specifically for resolving stock symbols into conids. Note that it accepts a comma-separated list, and returns all matching results accordingly.

GET /trsrv/stocks?symbols=AAPL

{
  "AAPL": [
    {
      "name": "APPLE INC",
      "chineseName": "苹果公å

View our Web API Account Management documentation here.