IBKR Client Portal Web API

Streaming WebSocket Data

Interactive Brokers Web API offers the webSocket endpoint to provide streaming data such as market data, live order and pnl updates. Before connecting to websocket you would need to have an authenticated session.

How to Authenticate:

Using Gateway:
To connect using the Gateway follow the Getting Started Instructions, once you receive the message "Client login succeeds" you have completed the authentication step. To gain access to services that require a brokerage session such as market data then send the endpoint https://localhost:5000/v1/api/iserver/accounts

Using OAuth:
To connect using OAuth following the directions on Github. Once the Live Session Token is generated you completed the authentication step. To access services that require a brokerage session you'll need to complete the SSODH Init and Response.

How to connect to Websocket:

The websocket endpoint is available at wss://api.ibkr.com/v1/api/ws, when using Gateway for authentication replace api.ibkr.com with localhost:5000
There are two ways of authorizing yourself with the websocket connection.

Include the cookies from the "set-cookie" headers from previous requests. Most browsers will automatically do this for you, although there are some exception such as Chrome.
Send the "session" value obtained via the /tickle endpoint. Once a websocket without the proper cookies is opened, the websocket will reply with a message saying "waiting for session". This indicates it is waiting for you to send the session value. The session value should be sent as a JSON object, with one key/pair as follows:

Request:

{"session":"SESSION_VALUE_HERE"}

Replacing SESSION_VALUE_HERE with the actual session. If the session is valid, the websocket will send a response confirming that you are authenticated.

Received:
```
{"message":"waiting for session"}
```

Access the endpoint https://api.ibkr.com/v1/api/tickle

Received:

{
  "session": "aeccc9d7515398c50fa894d967d099b1",
  "iserver": {,
    "tickle": true,,
    "authStatus": {,
      "authenticated": true,,
      "competing": false,,
      "message": "",,
      "MAC": "98:F2:B3:23:CF:10"
    }
  }
}

Request over websocket:

{"session":"aeccc9d7515398c50fa894d967d099b1"}

Received:

  {"topic":"sts","args":{"authenticated":true}}
  {"topic":"system","success":"username"}

Websocket Messages:

There are two types of messages:

Solicited (↑↓): User has to explicitly send request to receive data.
Unsolicited (↓↓): User receives data without any incoming request.

Format for solicated message types: TOPIC+{ARGUMENTS}

The first letter of the topic determines, s=subscribe or u=unsubscribe
+ is used as a separator
Pass an empty argument {} if none is required
Each response relays back the topic of the request

Available Topics
Topic	Definition
Solicated Message Types
smd+conidex / umd+conidex	market data + contract identifier and optional exchange
smh+conid / umh+serverId	market data history + server identifier
sor / uor	live orders
str / utr	trades
spl / upl	profit and loss
ech+hb	echo + heartbeat
tic	ping session
Unsolicated Message Types
system	system connection
sts	status
ntf	notification
blt	bulletin

Try the websocket connection here:

Note: Make sure to first launch gateway and authenticate.

wss://

{{ log.event }}: {{ log.data }}

Solicited Message Types

Market Data (Level I)

Using the Web API, you can request real time data for trading and analysis. For streaming top of the book (level I) data, the topic is smd+conidex. The conid (contract identifier) uniquely defines an instrument in IBKR's database and is needed for many endpoints. The conidex is formatted as conid or conid@EXCHANGE, if no exchange is specified then SMART is defaulted on contracts that support it. To find the conid for a stock, the endpoint /iserver/secdef/search can be used, for futures /trsrv/futures and for options there is an additional step described here. For the topic: smd+conidex it is required to specify the argument fields. The field value is a JSON Object which are a comma separated list of available tick types as described in the endpoint /iserver/marketdata/snapshot. Additional field values can be added to an existing market data request by resending smd+conidex. To unsubscribe from market data, the topic is umd+conidex.

Format: smd+conidex+{"fields":[]}

Request:

ws.send('smd+265598+{"fields":["31","83"]}');

Received:

{
  "31": "382.89",
  "83": 0.04,
  "6119": "q6",
  "server_id": "q6",
  "conid": 265598,
  "_updated": 1593524408296, 
  "topic": "smd+265598",
}

Format: umd+conidex+{}

Request:
```
ws.send('umd+265598+{}');
```

Market Data (History)

For streaming historical data, the topic smh+conid is used. There are also optional params available in Json format. If no params are specified then pass an empty {} param. If a param is specified incorrectly it will be ignored and default returned. For details on the conid review Market Data (Level I) section. Only a max of 5 concurrent request available at a time. To unsubscribe, the topic is umh+serverId whereby use the serverId from the received data.

params	definition	valid values
String exchange	listing exchange	valid exchange the contract trades
String period	duration of time back	{1-30}min, {1-8}h, {1-1000}d, {1-792}w, {1-182}m, {1-15}y
String bar	data granularity	1min, 2min, 3min, 5min, 10min, 15min, 30min, 1h, 2h, 3h, 4h, 8h, 1d, 1w, 1m
Boolean outsideRth	outside regular trading hours	true/false
String source	The type of data received	"m" or "midpoint" for #MIDPOINT "t" or "trades" for #TRADES "ba" or "bid_ask" for #BID_ASK "b" or "bid" for #BID "a" or "ask" for #ASK
String format	historical values returned	Can specify multiple separated by forward slash e.g. %o/%c %o - open %c - close %h - high %l - low

Format: smh+conid+{params}

Request:

ws.send('smh+265598+{"exchange":"ISLAND","period":"2h","bar":"5min","outsideRth":false,"source":"t","format":"%h/%l"}');

Received:

{
  "serverId": "341115",
  "symbol": "AAPL",
  "text": "AAPLE INC",
  "priceFactor": 100,
  "startTime": "20210317-18:00:00",
  "high": "12586/14469/65",
  "low": "12283/34103/0",
  "timePeriod": "7200s",
  "barLength": 300,
  "mdAvailability": "S",
  "mktDataDelay": 0,
  "outsideRth": false,
  "volumeFactor": 1,
  "priceDisplayRule": 1,
  "priceDisplayValue": "2",
  "negativeCapable": false,
  "messageVersion": 2,
  "data": [...],
  "points": 23, 
  "topic": "smh+265598",
}

Format: umh+serverId

Request:
```
ws.send('umh+341115');
```

Live Orders

As long as an order is active, it is possible to retrive it using the Web API. For streaming live orders the topic is sor. Once live orders are requested we will start to relay back when there is an update. To receive all orders for the current day the endpoint /iserver/account/orders?force=false can be used. It is advised to query all orders for the current day first before subscribing to live orders. To unsubscribe from live orders, the topic is uor.

Format: sor+{}

Request:
```
ws.send('sor+{}');
```

Received:

{
  "topic": "sor" ,
  "args": [
    {
      "acct": "DU1234",
      "conid": 265598,
      "orderId": 922048212,
      "cashCcy": "USD",
      "sizeAndFills": "0/1",
      "orderDesc": "Buy 100 Limit 372.00 GTC",
      "description1": "AAPL",
      "ticker": "AAPL",
      "secType": "STK",
      "listingExchange": "NASDAQ.NMS",
      "remainingQuantity": 100.0,
      "filledQuantity": 0.0,
      "companyName": "APPLE INC",
      "status": "Submitted",
      "origOrderType": "LIMIT",
      "supportsTaxOpt": "1",
      "lastExecutionTime": "200708173551",
      "lastExecutionTime_r": 1594229751000,
      "orderType": "Limit",
      "side": "BUY",
      "timeInForce": "GTC",
      "price": 372,
      "bgColor": "#000000",
      "fgColor": "#00F000"
     }
   ]
}

Format: uor+{}

Request:
```
ws.send('uor+{}');
```

Live Order - Updates: When there is an update to your order only the change to the order is relayed back along with the orderId. Most commonly this would involve status changes and partial fills.

Received: Status Change(s)

{
  "topic": "sor" ,
  "args": [
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "status": "PendingSubmit",
      "fgColor": "#3399CC"
     },
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "status": "PreSubmitted",
      "bgColor": "#FFFFFF",
      "fgColor": "#0000CC"
     },
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "status": "Submitted",
      "bgColor": "#000000",
      "fgColor": "#00F000"
     }
   ]
}

Received: Partial Fill(s)

{
  "topic": "sor" ,
  "args": [
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "sizeAndFills": "100/622",
      "remainingQuantity": 622.0,
      "filledQuantity": 100.0,
      "avgPrice": "382.45",
     },
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "sizeAndFills": "700/22",
      "remainingQuantity": 22.0,
      "filledQuantity": 700.0,
     },
    {
      "acct": "DU1234",
      "orderId": 352055828,
      "sizeAndFills": "722",
      "orderDesc": "Sold 722 Limit 382.40 GTC",
      "remainingQuantity": 0.0,
      "filledQuantity": 722.0,
      "status": "Filled",
      "timeInForce": "GTC",
      "price": 382.4,
      "bgColor": "#FFFFFF",
      "fgColor": "#000000"
     }
   ]
}

Trades

To review a list of your trades for the current day and six previous days use the topic str. If trades are required of less than 7 days, "days" parameter can be passed with integer value corresponding to the number of days needed (1 represents today and value can be upto 7). For updates you would only receive new orders as they fill. To receive only new trade updates and no previous trades, "realtimeUpdatesOnly" parameter can be passed. To unsubscribe from trades, the topic is utr.

Format: str+{}

Request:
```
ws.send('str+{}');
```
Following provides trades executed only today:
```
ws.send('str+{ "days": 1 }');
```
Following provides only realtime updates and no previous trades:
```
ws.send('str+{ "realtimeUpdatesOnly": true }');
```

Received:

{
  "topic": "str" ,
  "args": [
    {
      "execution_id": "0000e0d5.60cf1bd1.01.01",
      "symbol": "AAPL",
      "supports_tax_opt": "1",
      "side": "B",
      "order_description": "Bot 1 @ 130.64 on ISLAND",
      "trade_time": "20210408-22:10:01",
      "trade_time_r": 1617919801000,
      "size": 1,
      "price": "130.64",
      "order_ref": "66807500",
      "submitter": "apara428",
      "exchange": "ISLAND",
      "commission": "0.35",
      "net_amount": 130.64,
      "account": "DU26214",
      "accountCode": "DU26214",
      "company_name": "APPLE INC",
      "contract_description_1": "AAPL",
      "sec_type": "STK",
      "listing_exchange": "NASDAQ.NMS",
      "conid": "265598",
      "conidex": "265598",
      "clearing_id": "IB",
      "clearing_name": "IB",
      "liquidation_trade": "0"
     }
   ]
}

Format: utr+{}

Request:
```
ws.send('utr+{}');
```

Profit and Loss

For existing positions it is possible to receive Profit and Loss updates to the Web API using the topic spl. In the payload response the daily profit and loss (dpl) and unrealized profit and loss (upl) are received as a total value for all positions. Updates are relayed back as quickly as once per second but can vary based on market activity. To unsubscribe from profit and loss the topic is upl.

Format: spl+{}

Request:
```
ws.send('spl+{}');
```

Received:

{
  "topic": "spl" ,
  "args": {
    "DU1234.Core": {
      "rowType":1,
      "dpl":-57520.0
      "upl":972100.0
    }
  }
}

Format: upl{}

Request:
```
ws.send('upl{}');
```

Echo

To maintain an active websocket connection the topic ech is used to send a hearbeat with the argument hb. It is advised to send a heatbeat at least once per minute.

Format: ech+hb

Request:
```
ws.send('ech+hb');
```
Received:
```
ech+hb
```

Ping Session

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. It still requires the UI to send the endpoint /tickle every few minutes or when expires from /sso/validate = 0.

Format: tic

Request:
```
ws.send('tic');
```

Received:

{
  "topic": "tic",
  "alive": true,
  "id": "ee2e7cefefaad3d03b439ec1d2e9b5b7",
  "lastAccessed": 1616098376569,
}

Unsolicited Message Types

System Connection

When initially connecting to websocket the topic system relays back a confirmation with the corresponding username. While the websocket is connecting every 10 seconds there after a heartbeat with corresponding unix time (in millisecond format) is relayed back.

Received:

{
  "topic": "system" ,
  "success": "user123"
}
{
  "topic": "system" ,
  "hb": 1594677336001
}

Authentication Status

When connecting to websocket the topic sts will relay back the status of the authentication. Authentication status is already relayed back if there is a change, such as a competing sessions.

Received:

{
  "topic": "sts" ,
  "args": {
    "authenticated": true
      }
{
  "topic": "sts" ,
  "args": {
    "competing": false
      }
}

Notifications

If there is a brief message regarding trading activity the topic ntf will be sent.

Received:

{
  "topic": "ntf" ,
  "args": {
    "id": INDICATIVE_DATA_SUGGESTION ,
    "text": "CFD quotes reference the trade, volume and bid/ask market data on the underlying STK" ,
    "title": "Warning" ,
    "url": "https://interactivebrokers.com/"
      }
}

Bulletins

If there is an urgent message concerning exchange issues, system problems and other trading information the topic blt is sent along with the message argument.

Received:

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