Tutorial: Web API – How to connect to WebSocket

What is WebSocket?  

WebSocket is a bidirectional, fully-duplex protocol that is used in the same scenario as client-server communication. Unlike HTTP it starts from ws:// or wss://. It is a stateful protocol, which means the connection between the client and server will keep alive until it is terminated by either the client or server. After closing the connection it’s terminated from both ends.  

Please be sure to authenticate first in order to resolve the below URLs.
For authentication details, visit https://www.interactivebrokers.com/en/trading/ib-api.php

How to connect to WebSocket? 

The websocket endpoint is available at wss://api.ibkr.com/v1/api/ws, when using the Gateway for authentication replace api.ibkr.com with localhost:5000. Just having the socket open doesn’t mean the session is alive or the socket would function. It could be lingering on one side, we use a reverse proxy in the middle. After opening the socket a message has to be sent to trigger an event on our backend. There are two ways of authorizing yourself with the websocket connection.  

1. Include the cookies from the “set-cookie” headers. The first time you send an endpoint the “set-cookie” is returned. Most browsers will automatically do this for you, although there are some exceptions such as Chrome. 

2. 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"}

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

Receive:

{"message":"waiting for session"} 

Then access the endpoint https://api.ibkr.com/v1/api/tickle 

Receive:

{ 

  "session": "aeccc9d7515398c50fa894d967d099b1", 

  "iserver": {, 

    "tickle": true,, 

    "authStatus": {, 

      "authenticated": true,, 

      "competing": false,, 

      "message": "",, 

      "MAC": "98:F2:B3:23:CF:10" 

    } 

  } 

} 

Request over websocket:

   {"session":"aeccc9d7515398c50fa894d967d099b1"}

Receive:

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

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

If you have any further questions or issues connecting to websocket please reach-out to the API Group at https://www.interactivebrokers.com/en/index.php?f=47047. 

Visit the IBKR API Center for Downloads, Resources, and Technical Details: 
https://www.interactivebrokers.com/en/trading/ib-api.php.