Resources

Developer Tool Kit

View as MarkdownOpen in Claude

This section provides comprehensive information on how to integrate with our Account Management API and a developer toolkit to get you up and running quickly.

Prerequisites

  • An API credential (contact our support team at am-api@interactivebrokers.com to obtain one)
  • Basic knowledge of REST API
  • A development environment capable of making HTTP requests

Start Trading

Establishing a customer profile, setting up your trading account, and executing your first transaction

Request Access Token

The access token is required to access IBKR Web API. Request an access token using [POST]/api/v1/token. These tokens contain a scope parameter which describes what you are allowed to do with a given access token.

For this exercise, we need the following scopes:

  • accounts.read: View Brokerage Account information
  • accounts.write: Create Brokerage Account
  • bank-instructions.write: Add Banking Instructions
  • transfers.write: Transfer Funds
  • statements.read: View Client Statement
  • instructions.read: View Fund Transfer
  • sso-browser-sessions.write: Create SSO session to IBKR Portal.
  • sso.sessions.write: Placing Trades
{
  "url": "https://api.ibkr.com/oauth2/api/v1/token",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Cookie": "x-sess-uuid=0.46eb7068.1753288804.ce36eee"
  },
  "data": {
    "client_assertion_type": "{{clientAssertionType}}",
    "client_assertion": "{{clientAssertion}}",
    "grant_type": "client_credentials",
    "scope": "accounts.read accounts.write bank-instructions.read bank-instructions.write clients.read clients.write echo.read echo.write fee-templates.read fee-templates.write instructions.read instructions.write statements.read transfers.read transfers.write sso-sessions.write sso-browser-sessions.write enumerations.read"
  }
}

Create Brokerage Account

To establish a brokerage account for the client within the IBKR platform, submit client data to IBKR using [POST] gw/api/v1/accounts. The required data points for the request will vary based on the account type and customer type.

Authentication & Processing

IBKR authenticates the provided access token to verify server authorization before proceeding with the account creation request. The system typically processes the request and delivers a response within 30 seconds, though in some instances this may extend to 120 seconds.

Response Interpretation

Upon completion, IBKR returns a structured response that will indicate either a successful account creation or an error requiring attention.

Successful Creation

When account creation is successful, the response will contain:

  • IBKR Credential user
  • IBKR Account Number accounts.value
  • Password (if enabled) password
  • Pending Registration Tasks Required For Approval pendingTasks
    • If present: Account will not be approved/opened until tasks are complete.

Note: The hosting firm is responsible for securely communicating these credentials to the account holder.

Error Resolution

If an error occurs, the account will not be established. The hosting firm must:

  1. Review the error details
  2. Make necessary corrections based on the Error Library documentation
  3. Resubmit the request

Open Brokerage Account

Check state of the applications to see if any action is needed. Only accounts with an Open state are available for trading. TIP: Addressing all requirements promptly will help expedite your account activation. Regularly monitor your application status to ensure timely completion of the account opening process.

[GET] /gw/api/v1/accounts/{accountId}/status

  • Incomplete Application = Connect user to IBKR Portal using Single Sign On to complete online registration journey.
  • Documents Required = Action Needed
    • View Pending Tasks Required for Approval: /gw/api/v1/accounts/{accountId}/tasks?type=pending
  • Under Review with IBKR = Application is PENDING on IBKR, no action needed.
  • Pending Approval = Account is in the approval queue and should be opened by the following business day.
  • Open = Account is opened and there are no pending tasks assigned to the account.

Task Requirements for Account Approval

Tasks fall into two categories:

  • Required tasks ("isRequiredForApproval": true) – Must be completed for account approval
  • Optional tasks ("isRequiredForApproval": false) – Not necessary for account approval

Completing Tasks

Option 1: API Method

  • Use the PATCH endpoint: /api/v1/accounts/
  • Limitation: Only supports select tasks.
  • Best for programmatic completion of supported tasks

Option 2: IBKR Portal via Single Sign On

  • Redirect users to complete tasks directly in the IBKR Portal using Single Sign On
  • Advantage: Supports all possible tasks; no development as the interface is hosted by IBKR.

Recommended Implementation

  1. First attempt to complete tasks via API (Option 1)
  2. If any required tasks are not supported via API, fall back to the IBKR Portal (Option 2)
  3. Always have Option 2 available as a fallback mechanism for unsupported tasks

This approach provides the most seamless experience while ensuring all required tasks can be completed.

Fund Account

Once your account has been successfully opened, you can proceed with account funding. The specific funding mechanism will depend on your customer type.

Non-Disclosed Clients

For Non-Disclosed clients, all funds must be processed through the Non-Disclosed master account:

  • Funding is initiated by an internal transfer of cash or positions from the Non-Disclosed master account to the Non-Disclosed sub-account

Direct Clients

For Direct Clients, including Fully-Disclosed and Advisor, funding is initiated directly at the sub-account level using a cash or position transfer.

Important: If a transfer method is not supported using the front end, it will not be supported using the API

Place Trades

  1. Request SSO Bearer Token
    • [POST]/api/v1/sso-sessions: Create a Single Sign On (SSO) session to access IBKR’s Trading Web API
    • Returns a JSON object containing a reference to the newly created SSO session (including an SSO Bearer Token).
  2. Initialize Brokerage Session
    • [POST]/iserver/auth/ssodh/init : This is essential in order to use all /iserver trading & market data endpoints.
      • Additional background regarding Trading Web API sessions noted here.
    • Receive Brokerage Accounts (Optional): Receive a list of Brokerage Accounts the user has trading access to, their respective aliases and the currently selectedAccount via [GET]/iserver/accounts.
  3. Place Order
    • [POST]/iserver/account/{accountID}/orders: Available order types include (but are not limited to): MKT, LMT, STP, STP LMT, TRAIL, MOC, LOC, VWAP (IBALGO orders), Bracket, OCA, pre-trade allocation group orders (for Financial Advisors), cashQty orders etc.
  4. Log Out
    • Log the user out of the Trading Web API session using [POST]/logout. Any further activity requires re-authentication.

View Account Activity

Option 1: Query Account Information using Web API

Option 2: Generate Statements using Web API [POST]/api/v1/statements

  • Generates PDF statements for specified date range
  • Maximum range: 365 days per request

Option 3: Start of Day and End of Day Files

Account Maintenance

Implementing comprehensive account maintenance capabilities is essential for effective post-approval client management.

Profile Changes

  • changeAccountHolderDetail: Updating client account information, ensuring data accuracy and compliance with KYC requirements.
  • updateCredentials: Allows secure updating of email addresses associated with accounts, supporting proper client communications and security protocols.
  • updateTaxForm: Facilitates timely updates to tax forms associated with accounts, ensuring accurate tax reporting and compliance with tax authorities.
  • completeLoginMessages: Allows users to address pending tasks assigned to the account post approval including acknowledgement or changes to existing IBKR agreements and Disclosures.
  • changeFinancialInformation: Allows updates to client financial profile including objectives, experience and sources of wealth.
  • changeBaseCurrency: Supports international clients and those with changing currency needs.

Account Capabilities

  • Trading Permissions
    • addTradingPermissions: Enables clients to access additional products and markets post account approval as their needs evolve. This capability allows for appropriate risk management through controlled access to trading features.
    • removeTradingPermissions: Removal of trading capabilities when needed, supporting both client-requested changes and compliance-driven restrictions.
  • Dividend Reinvestment (DRIP)
    • enrollInDRIP: Enables participation in Dividend Reinvestment Plans, supporting long-term investment strategies and account growth. This capability promotes passive wealth accumulation and client retention.
    • leaveDRIP: Provides flexibility to exit dividend reinvestment programs when client needs or strategies change, supporting client autonomy and account management flexibility.
  • Stock Yield Enhancement Program
    • enrollInSYEP: Allows clients to participate in Stock Yield Enhancement Programs, creating opportunities for additional income through securities lending. This capability supports portfolio optimization and income generation strategies.
    • leaveSYEP: Provides clients with the flexibility to exit Stock Yield Enhancement Programs when their investment strategy changes or when they wish to regain full control over their securities. This supports client autonomy and risk management preferences.

Cash Transactions

Transferring Funds Between External Bank Account and IBKR Brokerage Account

Request Access Token

The access token is required to access IBKR Web API. Request an access token using [POST]/api/v1/token. These tokens contain a scope parameter which describes what you are allowed to do with a given access token.

For this exercise, we need the following scopes:

  • bank-instructions.write: Add Banking Instructions
  • transfers.write: Transfer Funds
  • instructions.read: View Fund Transfer
{
  "url": "https://api.ibkr.com/oauth2/api/v1/token",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded",
    "Cookie": "x-sess-uuid=0.46eb7068.1753288804.ce36eee"
  },
  "data": {
    "client_assertion_type": "{{clientAssertionType}}",
    "client_assertion": "{{clientAssertion}}",
    "grant_type": "client_credentials",
    "scope": "accounts.read accounts.write bank-instructions.read bank-instructions.write clients.read clients.write echo.read echo.write fee-templates.read fee-templates.write instructions.read instructions.write statements.read transfers.read transfers.write sso-sessions.write sso-browser-sessions.write enumerations.read"
  }
}

Banking Instructions

Verify that banking instructions exist for the specified account before allowing fund transfer.

  1. Verify Active Banking Instructions for the account: The /gw/api/v1/bank-instructions/query endpoint can be used to view list of saved banking instructions on file by accountId and bankInstructionMethod. The response will return the corresponding bankInstructionName and, bankRoutingNumber, currency last 4 digits of the bankAccountNumber (if applicable).
    • If instruction is returned, offer user option to use existing instruction
    • If no instruction is returned OR user does not want to use instruction on file, Hosting firm will instruct user they need to add instructions to process request.
  2. Add Banking Instructions
    • ACH: The /gw/api/v1/bank-instructions endpoint can be used to add banking instructions to an existing IBKR brokerage account. Only available to U.S. residents with linked bank account.
    • Additional payment types and currencies including Open Banking, Wise, Bill Pay, EFT, etc. will need to be added using the IBKR hosted interface. Seamlessly integrate these options into your platform by leveraging our Single Sign-On (SSO) functionality with IFRAME embedding, allowing IBKR funding screens to display natively within your application interface.

View Available Cash Balances

The /gw/api/v1/external-cash-transfers/query can be used to view the available cash for withdrawal with and without margin loan based on an accountId AND currency. For non-disclosed clients, this endpoint will return available cash to transfer between master and sub account.

Response will return following values:

  • withdrawableAmount: Cash Amount available for withdrawal (assuming margin loan). Only applicable for Fully-Disclosed and Advisor Clients.
  • withdrawableAmountNoBorrow: Cash Amount available for withdrawal (without margin loan). Only applicable for Fully-Disclosed and Advisor Clients.
  • allowedTransferAmountToMaster: Allowed Transfer Amount to Master assuming margin loan. Only applicable for Non-Disclosed Clients.
  • allowedTransferAmountToMasterNoBorrow: Allowed Transfer Amount(no_borrow) to Master. Only applicable for Non-Disclosed Clients.
  • withdrawableBalanceWithoutOriginHold: The amount available for withdrawal without origination hold.

Transfer Funds

The /gw/api/v1/external-cash-transfers can be used to manage cash transfers between external bank account and the IBKR brokerage account. Transfer details including method (ACH and WIRE), transaction type (DEPOSIT or WITHDRAWAL), currency, and amount will be defined within the body of the request.

GBP- Open Banking

POST /gw/api/v1/external-cash-transfers
{
  "instructionType": "DEPOSIT",
  "instruction": {
    "clientInstructionId": 7013045,
    "accountId": "U46377",
    "currency": "GBP",
    "amount": 100,
    "bankInstructionMethod": "ACH",
    "bankInstructionName": "British Bank",
  }
}

USD- ACH Deposit

POST /gw/api/v1/external-cash-transfers
{
  "instructionType": "DEPOSIT",
  "instruction": {
    "clientInstructionId": 7013045,
    "accountId": "U46377",
    "currency": "USD",
    "amount": 100,
    "bankInstructionMethod": "ACH",
    "bankInstructionName": "My Checking Account",
  }
}

USD- Wire Withdrawal

POST /gw/api/v1/external-cash-transfers
{
  "instructionType": "WITHDRAWAL",
  "instruction": {
    "clientInstructionId": 7013045,
    "accountId": "U46377",
    "currency": "USD",
    "amount": 100,
    "bankInstructionMethod": "WIRE",
    "bankInstructionName": "CHASE Bank",
  }
}