Client Portal API

Individual clients using Client Portal API will need to use a Java-based API gateway in order to access protected endpoints. The gateway is responsible for routing requests to the backend and ensuring that the brokerage session is authenticated. Interactive Brokers offers both a Standard and Beta release for our Client Portal API platforms. If you ever experience issues with the standard release, please try our Beta client in case your issue has already been resolved.

As the Client Portal API Gateway was developed using Java, a working installation of the Java Runtime Environment (JRE) is required to run it. The minimum required version is Java 8 update 192.

In order to check if you have a working installation of Java, open a terminal and run the following command:

java --version

If Java is installed and correctly configured you should see information about the currently installed version, otherwise an error is raised.

If you do not have a working installation of Java, you can download it from the official website

In order to launch the Client Portal Gateway, you must execute a set of commands through the Windows Command Prompt or Unix Terminal. This can not be done through the default file explorer. The API gateway is meant to be run on a local machine. As such, attempting to operate the gateway on a separate machine from where commands are generated may result in the issues and is not a supported practice by Interactive Brokers.

By default, the gateway will listen on port 5000. Clients can however change this to any available port on their device by modifying the listenPort field in the gateway configuration file ‘conf.yaml’, found in the ‘root’ directory of the gateway.

After successfully running the gateway, you may proceed through the Authentication steps before proceeding to calling your requested endpoints.

Using the terminal, navigate to the directory where the gateway has been unzipped. For example:

cd C:/Users/Example/Downloads/clientportal.gw

On Windows, launch the gateway using the following command:

binrun.bat rootconf.yaml

And in the case of Unix systems:

bin/run.sh root/conf.yaml

First request the sessionId from the  /tickle  endpoint and save the returned session value.

{
    "session": "d21b8cf5ebc8ea01c6ce37c8125ec83f",
    "ssoExpires": ssoExpires,
    "collission": collission,
    "userId": userId,
    "hmds": {
        "error": "no bridge"
    },
    "iserver": {
        "authStatus": {
            "authenticated": true,
            "competing": false,
            "connected": true,
            "message": "",
            "MAC": "MAC",
            "serverInfo": {
                "serverName": "serverName",
                "serverVersion": "serverVersion"
            }
        }
    }
}

Next, you will need to build your websocket to wss://localhost:5000/v1/api/ws. This will not be sent until the next step.

'{"session":"d21b8cf5ebc8ea01c6ce37c8125ec83f"}'

In your request to establish the websocket, be sure to set your cookie header as “api={‘session’ value here}”

After establishing your session, you may send whichever topics are needed through the newly established websocket. 

Market Data Request

Topic:

smd
Subscribes the user to watchlist market data.
Streaming, top-of-the-book, level one, market data is available for all instruments using Client Portal API’s websocket endpoint.

Topic Target:

conids: Required.
Must pass a single contract identifier.
Contracts requested use SMART routing by default. To specify the exchange, the contract identifier should be modified to: conId@EXCHANGE, where EXCHANGE is the requested data source.

Arguments:

fields: Array of Strings. Optional.
Pass an array of field IDs. Each ID should be passed as a string.
You can find a list of fields in the Market Data Fields section.

smd+conId+{
    "fields":"field_1",
    "field_2",
    "field_n", 
    "field_n+1"
}

Market Data Response

server_id: String.
Returns the request’s identifier.

conidEx: String.
Returns the passed conid field. May include exchange if specified in request.

conid: int.
Returns the contract id of the request

_updated: int*.
Returns the epoch time of the update in a 13 character integer .

6119: String.
Field value of the server_id. Returns the request’s identifier.

fields*: String.
Returns a response for each request. Some fields not be as readily available as others. See the Market Data section for more details.

6509: String.
Returns a multi-character value representing the Market Data Availability.

topic: String.
Restates the requesting topic.

{
    "server_id":"server_id",
    "conidEx":"conidEx",
    "conid":conid,"
    _updated":_updated,
    "6119":"serverId",
    "field_1":field_1,
    "field_2":field_2,
    "field_n":field_n, 
    "field_n+1":field_n+1,
    "6509":"RB",
    "topic":"smd+conid"
}

Market Data Unsubscribe Request

Topic:

umd
Unubscribes the user from watchlist market data.

Topic Target:

conids: Required.
Must pass a single contract identifier.

Arguments:

null.

umd+conId+{}

Historical Data Request

Topic:

smh
Subscribes the user to historical bar data.
Streaming, top-of-the-book, level one, historical data is available for all instruments using Client Portal API’s websocket endpoint.

Topic Target:

conids: Required.
Must pass a single contract identifier.
Contracts requested use SMART routing by default. To specify the exchange, the contract identifier should be modified to: conId@EXCHANGE, where EXCHANGE is the requested data source.

Arguments:

exchange: String.
Requested exchange to receive data.

period: String.
Total duration for which bars will be requested.

bar: String.
Interval of time to receive data.

outsideRth: Bool.
Determines if you want data outside regular trading hours (true) or only during market hours (false).

source: String.
The value determining what type of data to show.

format: String.
The format in which bars are returned.
 

smh+conid+{
    "exchange":"exchange",
    "period":"period",
    "bar":"bar",
    "outsideRth":outsideRth,
    "source":"source",
    "format":"format"
}

Historical Data Response

serverId: String.
Request identifier for the specific historical data request. Used for cancelling the data stream.

symbol: String.
Returns the symbol for the requested conid.

text: String.
Company long name.

priceFactor: int.
Price mutlipler (based on $0.01)

startTime: String.
Returns the starting time (in epoch time) of the response.

high: String.
Returns the highest “high value/Volume value/Outside RTH volume” of the period.

low: String.
Returns the lowest “Low value/Volume value/Outside RTH volume” of the period.

timePeriod: String.
Returns the period covered by the request.

barLength: int.
Returns the string length of the bar response.

mdAvailability: String.
Internal IBKR message.

mktDataDelay: int.
Returns if there is any delay in the market data.

outsideRth: Bool.
Returns if the data contains information outside regular trading hours.

volumeFactor: int.
Determines if the volume is returned as lots, multipliers, or as-is.

priceDisplayRule: int.
Internal IBKR message.

priceDisplayValue: String.
Internal IBKR message.

negativeCapable: Bool.
Returns contract rule whether the contract supports negative values or not.

messageVersion: int.
Internal IBKR message.

data: Array of Objects.
Returns all bars related that fall within the period.

o: float.
Opening value for the bar’s duration.

c: float.
Closing value for the bar’s duration.

l: float.
Lowest value for the bar’s duration.

h: float.
Highest value for the bar’s duration.

v: int.
Total volume of the bar.

t: int.
Epoch time of the bar return.

points: int.
Displays the total number of bars returned within ‘data’.

topic: String.
Represents the request sent.

{
    "serverId": "serverId",
    "symbol": "symbol",
    "text": "text",
    "priceFactor": priceFactor,
    "startTime": "startTime",
    "high": "high",
    "low": "low",
    "timePeriod": "timePeriod",
    "barLength": barLength,
    "mdAvailability": "mdAvailability",
    "mktDataDelay": mktDataDelay,
    "outsideRth": outsideRth,
    "volumeFactor": volumeFactor,
    "priceDisplayRule": priceDisplayRule,
    "priceDisplayValue": "priceDisplayValue",
    "negativeCapable": negativeCapable,
    "messageVersion": messageVersion,
    "data": [data],
    "points": points, 
    "topic": "topic",
}

Cancel Historical Data Request

Topic:

umh
Unubscribes the user from historical bar data.

Arguments:

serverId: String. Required

serverId is passe initially from the historical data request.

umh+{serverId}

Market Depth Request

Topic:

sbd
Subscribes the user to market depth data.
Streaming depth of book data requires users to maintain a L2, Depth of Book, market data subscription.

Topic Target:

acctId: Required.
Must pass a single AccountId.

conids: Required.
Must pass a single contract identifier.

exchange: Optional.
Must pass a single contract identifier.
If no exchange is specified, all available deep exchanges are assumed.

Arguments:

Do not pass arguments

sbd+acctId+conid+exchange

Market Depth Response

topic: String.
Returns the request’s topic string.

data: Array of Objects.
Returns an array of objects to indicate the depth of market (DOM).

row: int.
Returns the row identifier of the market depth data.

focus: int.
Indicates if the value was marked as the last price for the contract.

price: String.
Returns the Last, or last executed trade, price.
In some instances, price and size will be returned in the structure ‘”price”:”size @ price”‘.

ask: String.
Returns the corresponding ask size.

bid: String.
Returns the corresponding bid size.

{
  "topic":"sbd+acctId+conid",
  "data":[
    {"row":0,"focus":0,"price":"price"},
    {"row":1,"focus":0,"price":"size @ price"},
    {"row":n,"focus":0,"price":"price", "bid":"bid"},
    {"row":n+1,"focus":0,"price":"price", "ask":"ask"},
    {"row":n+1,"focus":0,"price":"size @ price", "ask":"ask"}
  ]
}

Cancel Market Depth Request

Topic:

ubd
Unsubscribes the user from market depth.

Arguments:

acctId: Required.
Must pass the account ID of the account that made the request.

ubd+{acctId}

Market Depth Request

Topic:

tic
Ping the websocket in order to keep the websocket session alive.
To maintain a session for accessing /iserver or /ccp endpoints, use the topic tic. It is advised to ping the session at least once per minute.

Note: It is still required to send a request to the /tickle endpoint every few minutes or when the session expires (/sso/validate is returning a 0).

Do not pass arguments

tic

Order Updates Request

Topic:

sor
Subscribes the user to live order updates.

Arguments:

Do not pass arguments

sor+{}

Order Updates Response

topic: String.

args: Array of Objects.

acct: String.
Returns the account Id of which account made the request.

conid: int.
Contract Identifier for the given order.

orderId: int.
Order identfier affiliated with the given order.

cashCcy: String.
Base currency used for the transaction.

sizeAndFills: String.
Total quantity filled in the order.

orderDesc: String.
Order description of the given order.
Describes the side, size, orderType, price, and tif of the orer.

description1: String.
Ticker symbol of the request.

ticker: String.
Ticker symbol of the request.

secType: String.
Security type of the request.

listingExchange: String.
Primary exchange where the contract is held.

remainingQuantity: float.
Percentage of the order quantity remaining.

filledQuantity: float.
Percentage of the ordr quantity filled.

companyName: String.
Longname of the contract’s company.

status: String.
Current order status.
Value Format: Presubmitted, Submitted, Filled, Cancelled.

origOrderType: String.
Returns the original order type of the given order.

supportsTaxOpt: String.
Determines if the order supports Tax Optimizer.

lastExecutionTime: String.
Returns the datetime object of the most recent execution.

lastExecutionTime_r: int.
Returns the epoch timestamp of the most recent execution.

orderType: String.
Returns the current order type of the order.
Value Format: MARKET, LIMIT, STOP

side: String.
Returns the side of the trade.
Value Format: BUY, SELL

timeInForce: String.
Returns the time in force for the given order.

price: int.
Provides the limit or stop price for the submitted order.

bgColor: String.
Background color. Used for Client Portal only.

fgColor: String.
Foreground color. Used for Client Portal only.

{
    "topic": "sor" ,
    "args": [
        {
            "acct": "acct",
            "conid": conid,
            "orderId": orderId,
            "cashCcy": "cashCcy",
            "sizeAndFills": "sizeAndFills",
            "orderDesc": "orderDesc",
            "description1": "description1",
            "ticker": "ticker",
            "secType": "secType",
            "listingExchange": "listingExchange",
            "remainingQuantity": remainingQuantity,
            "filledQuantity": filledQuantity,
            "companyName": "companyName",
            "status": "status",
            "origOrderType": "origOrderType",
            "supportsTaxOpt": "supportsTaxOpt",
            "lastExecutionTime": "lastExecutionTime",
            "lastExecutionTime_r": lastExecutionTime_r,
            "orderType": "orderType",
            "side": "side",
            "timeInForce": "timeInForce",
            "price": price,
            "bgColor": "#000000",
            "fgColor": "#00F000"
        }
    ]
}

Cancel Order Updates Request

Topic:

uor
Cancels the live order updates subscription.

Arguments:

Do not pass arguments

uor+{}

Profit & Loss Request

Topic:

spl
Subscribes the user to live profit and loss information.

Arguments:

Do not pass arguments

zspl+{}

Order Updates Response

topic: String.
Returns the topic of the given request.

args: Object.
Returns the object containing the pnl data.

acctId.Core: Object.
Specifies the account for which data was requested.

rowType: int.
The row value of the request. Will increment with additional accounts.

dpl: float.
Daily Profit and Loss value.

nl: float.
Net Liquidity in the account.

upl: float.
Unrealized Profit and Loss for the day.

el: float.
Excess Liquidty in the account.

mv: float
Market value of held stocks in the account.

{ 
   "topic": "spl" , 
    "args": { 
        "acctId.Core": { 
            "rowType":rowType, 
            "dpl":dpl, 
            "nl":nl,
            "upl":upl,
            "el": el,
            "mv": mv
        }
    }
}

Cancel Order Updates Request

Topic:

upl
Cancels the subscriptions to profit and loss information.

Arguments:

Do not pass arguments

upl+{}

Trades Data Request

Topic:

str
Subscribes the user to trades data. This will return all executions data while streamed.

Arguments:

realtimeUpdatesOnly: bool. Optional
Decide whether you want to display any historical executions, or only the executions available in real time.
Set to false by default.

days: int. Optional
Returns the number of days of executions for data to be returned.
Set to 1 by default.

str+{
    "realtimeUpdatesOnly":realtimeUpdatesOnly, 
    "days":days
}

Trades Data Response

topic: String.
Returns the topic of the given request.

args: Object.
Returns the object containing the pnl data.

execution_id: String.
Execution identifier of the specific trade.

symbol: String.
Ticker symbol of the traded contract.

supports_tax_opt: String.
Determines if the contract supports the tax optimizer. Client Portal only.

side: String.
Determines if the order was a buy or sell side.

order_description: String.
Describes the full content of the order.
Value format: “{SIDE} {SIZE} @ {PRICE} on {EXCHANGE}”

trade_time: String.
Traded date time in UTC.
Value format: “YYYYMMDD-HH:mm:ss”

trade_time_r: int.
Traded datetime of the execution in epoch time.

size: float.
Returns the quantity of shares traded.

price: String.
Returns the price used for the given trade.

exchange: String.
Returns the exchange the order executed at.

net_amount: float.
Returns the total amount traded after calculating multiplier.

account: String.
Returns the account the order was traded on.

accountCode: String.
Returns the account the order was traded on.

company_name: String.
Returns the title of the company for the contract.

contract_description_1: String.
Returns the underlying symbol of the contract.

contract_description_2: String.
Returns a full description of the derivative.

sec_type: String.
Returns the security type traded.

conid: int.
Contract identifier for the traded contract.

conidEx: String.
Returns the conidEx of the order if specified. Otherwise returns conid.

open_close: String.
Returns if the execution was a closing trade.
Returns “???” if the position was already open, but not a closing order.

liquidation_trade: String.
Returns if the trade was a result of liquidation.

is_event_trading: String.
Determines if the order can be used with EventTrader.

{
  "topic":"topic"
  "args":[
    {
    "execution_id":"execution_id"
    "symbol":"symbol"
    "supports_tax_opt":"supports_tax_opt"
    "side":"side"
    "order_description":"order_description"
    "trade_time":"trade_time"
    "trade_time_r":trade_time_r
    "size":size
    "price":"price"
    "exchange":"exchange"
    "net_amount":net_amount
    "account":"account"
    "accountCode":"accountCode"
    "company_name":"company_name"
    "contract_description_1":"contract_description_1"
    "contract_description_2":"contract_description_2"
    "sec_type":"sec_type"
    "conid":conid
    "conidEx":"conidEx"
    "open_close":"open_close"
    "liquidation_trade":"liquidation_trade"
    "is_event_trading":"is_event_trading"
    }
  ]
}

Cancel Trades Data Request

Topic:

utr
Cancels the trades data subscription

utr

topic: String.
Returns the topic of the given request.

args: Object.
Returns the object containing the pnl data.

accounts: Array.
Displays all accounts currently accessible by the user.

acctProps: Object.
Returns an object detailing the account properties.

acctId: Object.
Returns the specific allocation group or account information.

hasChildAccounts: bool.
Returns whether there are any subaccounts attached to the listed account.

supportsCashQty: bool.
Returns where the account supports cash quantity orders.

noFXConv: bool.
Returns if the account supports forex conversion.

isProp: bool.

supportsFractions: bool.
Returns if the account supports fractional trading.

allowCustomerTime: bool.
Returns if the account returns data in the customer’s local time.

aliases: Object.
Returns a series of accounts and their affiliated aliases.

allowFeatures:  Object.
Displays the allowed features for the account.

showGFIS: bool.
Determines whether the account can display data or not.

showEUCostReport: bool.
Determines if the account receives the EU Cost Report.

allowEventContract: bool.
Determines if the account can receive event contracts.

allowFXConv: bool.
Determines if the account allows forex conversions.

allowFinancialLens: bool.
Determines if the account supports Financial Lens (Client Portal Only).

allowMTA: bool.
Determines if the account supports Mobile Trading Alerts.

allowTypeAhead: bool.
Determines if the account supports Type Ahead (Client Portal Only).

allowEventTrading: bool.
Determines if the account supports Event Trader (Client Portal Only).

snapshotRefreshTimeout: int.
Determines if the account can support snapshot refresh (Client Portal Only).

liteUser: bool.
Returns if the account is an IBKR Lite account.

showWebNews: bool.
Returns if the account

research: bool.
Determines if the account supports research subscriptions.

debugPnl: bool.
Determines if the account enables debug for PnL (Client Portal Only).

showTaxOpt: bool.
Determines if the account supports Tax Optimizer (Client Portal Only).

showImpactDashboard: bool.
Determines if the account should display the Impact Dashboard on startup (Client Portal Only).

allowDynAccount: bool.
Determines if the account supports Dynamic Account Structures (Client Portal Only).

allowCrypto: bool.
Determines if the account supports Crypto trading.

allowedAssetTypes: String.
Returns all support asset or security types.

chartPeriods: Object of Arrays.
Returns the trading hours supported by each approvided asset type.

groups: Array.
Lists all groups the account is listed under.

profiles: Array.
Lists all profiles the account is listed under.

selectedAccount: String.
Returns the acively selected account.

serverInfo: Object.
Returns a description of the server info.

sessionId: String.
Returns the sesion identifier.

isFT: bool.
Returns if the fractional trading account.

isPaper: bool.
Returns if the active account is a paper trading account.

{
    "topic":"act",
    "args":{
       "accounts":[],
       "acctProps":{
          "All":{
             "hasChildAccounts":hasChildAccounts,
             "supportsCashQty":supportsCashQty,
             "noFXConv":noFXConv,
             "isProp":isProp,
             "supportsFractions":supportsFractions,
             "allowCustomerTime":allowCustomerTime
          }
       },
       "aliases":{},
       "allowFeatures":{
          "showGFIS":showGFIS,
          "showEUCostReport":showEUCostReport,
          "allowEventContract":allowEventContract,
          "allowFXConv":allowFXConv,
          "allowFinancialLens":allowFinancialLens,
          "allowMTA":allowMTA,
          "allowTypeAhead":allowTypeAhead,
          "allowEventTrading":allowEventTrading,
          "snapshotRefreshTimeout":snapshotRefreshTimeout,
          "liteUser":liteUser,
          "showWebNews":showWebNews,
          "research":research,
          "debugPnl":debugPnl,
          "showTaxOpt":showTaxOpt,
          "showImpactDashboard":showImpactDashboard,
          "allowDynAccount":allowDynAccount,
          "allowCrypto":allowCrypto,
          "allowedAssetTypes":"allowedAssetTypes"
       },
       "chartPeriods":{
          "STK":[],
          "CFD":[],
          "OPT":[],
          "FOP":[],
          "WAR":[],
          "IOPT":[],
          "FUT":[],
          "CASH":[],
          "IND":[],
          "BOND":[],
          "FUND":[],
          "CMDTY":[],
          "PHYSS":[],
          "CRYPTO":[]
       },
       "groups":[],
       "profiles":[],
       "selectedAccount":"selectedAccount",
       "serverInfo":{
          "serverName":"serverName",
          "serverVersion":"serverVersion"
       },
       "sessionId":"sessionId",
       "isFT":isFT,
       "isPaper":isPaper
    }
 }

topic: String.
Returns the topic of the given request.

args: Object.
Returns the data object.

authenticated: bool.
Returns whether the user is authenticated to the brokerage session.

{
    "topic": "sts" ,
    "args": {
        "authenticated": authenticated
    }
}

topic: String.
Returns the topic of the given request.

args: Object.
Returns the bulletins argument values.

id: String.
Returns the ID for the specific bulletin.

message: String.
Returns the bulletin information.

{
    "topic": "blt" ,
    "args": {
        "id": "id" ,
        "message": "message" 
    }
}

topic: String.
Returns the topic of the given request.

success: String.
Returns the username logged in with that has built the websocket.

{
    "topic": "system" ,
    "success": "success"
}

topic: String.
Returns the topic of the given request.

args: Object.
Returns the object containing the pnl data.

id: String.
Returns the identifier for the specific notification.

text: String.
Returns the body text for the affiliated notification.

title: String.
Returns the title or headline for the notification.

url: String.
If relevant, provides a url where a user can go to read more about the notification.

{
    "topic": "ntf",
    "args": {
        "id": "id",
        "text": "text",
        "title": "title",
        "url": "url"
    }
}