-
Notifications
You must be signed in to change notification settings - Fork 12
Ibkr Ws Client
The IbkrWsClientclass provides an interface to the IBKR WebSocket API.
IbkrWsClient
is a concrete implementation of the WsClient
abstract base class, which is a collection of functionalities that facilitate connecting to a WebSocket API:
- Asynchronicity - communication with the WebSocket API is automatiically handled on a separate thread in a non-blocking fashion.
- Threading - managing the lifecycle of the WebSocket processing thread.
- Connection - taking care of establishing and re-establishing the WebSocket connection.
- Subscriptions - managing WebSocket channel subscriptions and distributing messages accordingly.
- Queues - providing an asynchronous interface to consume the data received.
On top of these base functionalities, the IbkrWsClient
implements message processing and connectivity handling specific to the IBKR WebSocket API.
Using the IbkrWsClient
involves handling three areas:
- Managing its lifecycle. It is asynchronous and it will run on a separate thread, hence we need to construct it, start it and then manage its lifecycle on the originating thread.
- Subscribing and unsubscribing. It is subscription-based, hence we need to specify which channels we want to subscribe to and remember to unsubscribe later.
- Consuming data. It uses a queue system, hence we need to access these queues and consume their data.
We construct the IbkrWsClient
as follows:
from ibind import IbkrClient, IbkrWsClient, ibind_logs_initialize
ibind_logs_initialize()
client = IbkrClient()
ws_client = IbkrWsClient(ibkr_client=client)
Note that we pass an instance of IbkrClient
class as an argument. This is due to the fact that IBKR WebSocket API requires us to utilise the tickle
REST endpoint in order to authenticate when connecting. IbkrWsClient
uses the IbkrClient
to handle this automatically.
Having done that, we can manage the IbkrWsClient
's lifecycle:
ws_client.start()
print(ws_client.running) # True
ws_client.shutdown()
print(ws_client.running) # False
Outputs:
2024-04-26 17:02:34,248|I| IbkrWsClient: Starting
2024-04-26 17:02:34,248|I| IbkrWsClient: Trying to connect
2024-04-26 17:02:36,344|I| IbkrWsClient: Connection open
True
2024-04-26 17:02:36,359|I| IbkrWsClient: Shutting down
2024-04-26 17:02:36,365|I| IbkrWsClient: on_close
2024-04-26 17:02:36,366|I| IbkrWsClient: Connection closed
2024-04-26 17:02:36,366|I| IbkrWsClient: Gracefully stopped
False
Interacting with the IBKR WebSocket channels involves sending an appropriate string payloads. These usually:
- Start with
s
for subscription andu
for unsubscription, eg.smd
andumd
. - Have a two-letter channel identifier, eg.
md
for market data. - Have additional arguments defined after a
+
plus symbol, eg.smd+conid+...
IbkrWsClient
handles these three items distinctly when either subscribing or unsubscribing:
- Adding the
s
andu
prefix is handled automatically when eithersubscribe
orunsubscribe
methods are called. - The channel identifier - referred to as the
channel
- needs to be provided as the first argument. - Additional payload arguments - referred to as the
data
- can be passed as the second argument.
For example, in order to subscribe to the Live Order Updates, the documentation indicates that we need to send the following message:
sor+{}
This translates to:
- The
's'
prefix is expected. - The
channel
is'or'
. - There is no additional arguments that we would provide through
data
.
We subscribe to this channel using IbkrWsClient
in the following fashion:
ws_client.subscribe(channel='or', data=None, needs_confirmation=False)
Let's look at another example, this time subscribing to the Trades Data channel which accepts additional arguments:
str+{
"realtimeUpdatesOnly":realtimeUpdatesOnly,
"days":days
}
This translates to:
- The
's'
prefix is expected. - The
channel
is'tr'
. - We can pass
data
dictionary containingrealtimeUpdatesOnly
anddays
fields.
We subscribe to this channel using IbkrWsClient
in the following fashion:
ws_client.subscribe(channel='tr', data={'realtimeUpdatesOnly': True, 'days': 5}, needs_confirmation=False)
The subscribe
and unsubscribe
methods accept needs_confirmation
parameter (True
by default). It indicates whether the client should expect a confirmation from the API, which is used to aid the subscriptions' lifecycle management.
IBKR WebSocket API sends information back directly after subscribing - but only for some of its channels. Hence we can set needs_confirmation=False
when subscribing to channels that don't send any confirmation.
Contrarily, for channels that do provide a confirmation, IbkrWsClient
will expect a confirmation and attempt to re-subscribe if it is not received. Some channels in fact require two subscription requests to be sent before starting to send data, which is also facilitated by this confirmation and re-attempt functionality.
When valid WebSocket messages are received, the worker thread of IbkrWsClient
processes these and stores them in appropriate FIFO Queue
objects.
The queues in IbkrWsClient
are identified using the IbkrWsKey
enum. Each IBKR WebSocket channel has a corresponding IbkrWsKey
. Therefore, requesting data for a particular channel involves identifying it by passing the appropriate IbkrWsKey
when calling the new_queue_accessor
method in order to acquire a new QueueAccessor
object.
QueueAccessor
is a read-only wrapper around the Queue
object, employed to ensure that the write access to queues is only given to the IbkrWsClient
.
QueueAccessor
exposes two read functions from the Queue
object:
-
get
- for accessing data. Note that unlike theQueue.get
, this method is non-blocking by default, and returns aNone
instead of raisingEmpty
exception if no items are available. -
empty
- for checking if queue has items available.
To summarise, consuming data involves:
- Identifying the channel using the
IbkrWsKey
. - Acquiring a new
QueueAccessor
by passing the appropriateIbkrWsKey
to thenew_queue_accessor
method. - Using
QueueAccessor.get
method to receive items from the queue.
# acquire a new QueueAccessor
qa = ws_client.new_queue_accessor(IbkrWsKey.MARKET_DATA)
while True:
# get data from the queue
item = qa.get()
# process data
print(item)
See any error on this page? Create an Issue and let us know.