Interactive Brokers MCP Server

# Streaming Websocket Data Interactive Brokers Web API offers WebSocket streaming for market data, orders and pnl updates. To connect to the WebSocket follow the [Getting Started Instructions](index.html#login) to authenticate the gateway session. Once you receive the message \"Client login succeeds\" a websocket connection can now be established using the endpoint:[**wss://localhost:5000/v1/api/ws**]{style="font-size:16px; color:blue;"} 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 <table style="width: 475px;"> <caption>Available Topics</caption> <tbody><tr> <th bgcolor="#85C1E9">Topic</th> <th bgcolor="#85C1E9">Definition</th> </tr> <tr id="row1"> <td colspan="2"><b>Solicated Message Types</b></td> </tr> <tr id="row2"> </tr><tr> <td>smd+conid / umd + conid</td> <td>market data + contract identifier</td> </tr> <tr id="row3"> </tr><tr> <td>sor / uor</td> <td>live orders</td> </tr> <tr id="row4"> </tr><tr> <td>spl / upl</td> <td>profit and loss</td> </tr> <tr id="row5"> </tr><tr> <td>ech+hb</td> <td>echo + heartbeat</td> </tr> <tr id="row6"> <td colspan="2"><b>Unsolicated Message Types</b></td> </tr> <tr id="row7"> </tr><tr> <td>system</td> <td>system connection</td> </tr> <tr id="row8"> </tr><tr> <td>sts</td> <td>status</td> </tr> <tr id="row9"> </tr><tr> <td>ntf</td> <td>notification</td> </tr><tr id="row10"> </tr><tr> <td>blt</td> <td>bulletin</td> </tr> </tbody></table> ### <span style="font-size: 22px;">Solicited Message Types</span> ### 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 <b>smd+conid</b>. The conid (contract identifier) uniquely defines an instrument in IBKR's database and is needed for many endpoints. To find the conid for a stock, the endpoint <span style="color: blue;">/iserver/secdef/search</span> can be used, for futures <span style="color: blue;">/trsrv/futures</span> and for options there is an additional step [described here](option_lookup.html). For the topic: <b>smd+conid</b> it is required to specify the argument <b>fields</b>. 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](https://interactivebrokers.com/api/doc.html#tag/Market-Data). Additional field values can be added to an existing market data request by resending <b>smd+conid</b>. To unsubscribe from market data, the topic is <b>umd+conid</b>. <br> #### Format: smd+conid+{"fields":[]} - Request: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;"><span>`ws.send('smd+265598+{"fields":["31","83"]}');`</span> </pre></div> <br> - Received: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"31": </span><span>"382.89"</span>, <span style="color: rgb(0, 116, 232);">"83": </span><span style="color: rgb(5, 139, 0);">0.04</span>, <span style="color: rgb(0, 116, 232);">"6119": </span><span>"q6"</span>, <span style="color: rgb(0, 116, 232);">"server_id": </span><span>"q6"</span>, <span style="color: rgb(0, 116, 232);">"conid": </span><span style="color: rgb(5, 139, 0);">265598</span>, <span style="color: rgb(0, 116, 232);">"_updated": </span><span style="color: rgb(5, 139, 0);">1593524408296</span>, <span style="color: rgb(0, 116, 232);">"topic": </span><span>"smd+265598"</span>, } </pre></div> <br> #### Format: umd+conid+{} - Request: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;"><span>`ws.send('umd+265598+{}');`</span> </pre></div> <br> - - - <h3>Live Orders</h3> &#13;&#10;As long as an order is active, it is possible to retrive it using the Web API. For streaming live orders the topic is <b>sor</b>. When live orders are requested we will start to relay back updates. To receive all orders for the current day the endpoint <span style="color: blue;">/iserver/account/orders?force=false</span> can be used. To unsubscribe from live orders, the topic is <b>uor</b>. <br> &#13;&#10;<h4>Format: sor+{}</h4> <ul> <li>Request: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;"><span>`ws.send('sor+{}');`</span> </pre></div> </li> <br> <li>Received: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"> <pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"topic": </span><span>"sor"</span> , <span style="color: rgb(0, 116, 232);">"args": </span>[ { <span style="color: rgb(0, 116, 232);">"acct": </span><span>"DU1234"</span>, <span style="color: rgb(0, 116, 232);">"conid": </span><span style="color: rgb(5, 139, 0);">265598</span>, <span style="color: rgb(0, 116, 232);">"orderId": </span><span style="color: rgb(5, 139, 0);">922048212</span>, <span style="color: rgb(0, 116, 232);">"cashCcy": </span><span>"USD"</span>, <span style="color: rgb(0, 116, 232);">"sizeAndFills": </span><span>"0/1"</span>, <span style="color: rgb(0, 116, 232);">"orderDesc": </span><span>"Buy 100 Limit 372.00 GTC"</span>, <span style="color: rgb(0, 116, 232);">"description1": </span><span>"AAPL"</span>, <span style="color: rgb(0, 116, 232);">"ticker": </span><span>"AAPL"</span>, <span style="color: rgb(0, 116, 232);">"secType": </span><span>"STK"</span>, <span style="color: rgb(0, 116, 232);">"listingExchange": </span><span>"NASDAQ.NMS"</span>, <span style="color: rgb(0, 116, 232);">"remainingQuantity": </span><span style="color: rgb(5, 139, 0);">100.0</span>, <span style="color: rgb(0, 116, 232);">"filledQuantity": </span><span style="color: rgb(5, 139, 0);">0.0</span>, <span style="color: rgb(0, 116, 232);">"companyName": </span><span>"APPLE INC"</span>, <span style="color: rgb(0, 116, 232);">"status": </span><span>"Submitted"</span>, <span style="color: rgb(0, 116, 232);">"origOrderType": </span><span>"LIMIT"</span>, <span style="color: rgb(0, 116, 232);">"supportsTaxOpt": </span><span>"1"</span>, <span style="color: rgb(0, 116, 232);">"lastExecutionTime": </span><span>"200708173551"</span>, <span style="color: rgb(0, 116, 232);">"lastExecutionTime_r": </span><span style="color: rgb(5, 139, 0);">1594229751000</span>, <span style="color: rgb(0, 116, 232);">"orderType": </span><span>"Limit"</span>, <span style="color: rgb(0, 116, 232);">"side": </span><span>"BUY"</span>, <span style="color: rgb(0, 116, 232);">"timeInForce": </span><span>"GTC"</span>, <span style="color: rgb(0, 116, 232);">"price": </span><span style="color: rgb(5, 139, 0);">372</span>, <span style="color: rgb(0, 116, 232);">"bgColor": </span><span>"#000000"</span>, <span style="color: rgb(0, 116, 232);">"fgColor": </span><span>"#00F000"</span> } ] } </pre></div> </li> <br> </ul> &#13;&#10;<h4>Format: uor+{}</h4> <ul> <li> Request: <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;"><span>`ws.send('uor+{}');`</span> </pre></div> </li> <br> </ul> &#13;&#10;<b>Live Order - Updates</b>: 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. <ul> <li>Received: Status Change(s) <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"> <pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"topic": </span><span>"sor"</span> , <span style="color: rgb(0, 116, 232);">"args": </span>[ { <span style="color: rgb(0, 116, 232);">"acct": </span><span>"DU1234"</span>, <span style="color: rgb(0, 116, 232);">"orderId": </span><span style="color: rgb(5, 139, 0);">352055828</span>, <span style="color: rgb(0, 116, 232);">"status": </span><span>"PendingSubmit"</span>, <span style="color: rgb(0, 116, 232);">"fgColor": </span><span>"#3399CC"</span> }, { <span style="color: rgb(0, 116, 232);">"acct": </span><span>"DU1234"</span>, <span style="color: rgb(0, 116, 232);">"orderId": </span><span style="color: rgb(5, 139, 0);">352055828</span>, <span style="color: rgb(0, 116, 232);">"status": </span><span>"PreSubmitted"</span>, <span style="color: rgb(0, 116, 232);">"bgColor": </span><span>"#FFFFFF"</span>, <span style="color: rgb(0, 116, 232);">"fgColor": </span><span>"#0000CC"</span> }, { <span style="color: rgb(0, 116, 232);">"acct": </span><span>"DU1234"</span>, <span style="color: rgb(0, 116, 232);">"orderId": </span><span style="color: rgb(5, 139, 0);">352055828</span>, <span style="color: rgb(0, 116, 232);">"status": </span><span>"Submitted"</span>, <span style="color: rgb(0, 116, 232);">"bgColor": </span><span>"#000000"</span>, <span style="color: rgb(0, 116, 232);">"fgColor": </span><span>"#00F000"</span> } ] } </pre></div> </li> <br> </ul> &#13;&#10;<ul> <li>Received: Partial Fill(s) <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"> <pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"topic": </span><span>"sor"</span> , <span style="color: rgb(0, 116, 232);">"args": </span>[ { <span style="color: rgb(0, 116, 232);">"acct": </span><span>"DU1234"</span>, <span style="color: rgb(0, 116, 232);">"orderId": </span><span style="color: rgb(5, 139, 0);">352055828</span>, <span style="color: rgb(0, 116, 232);">"sizeAndFills": </span><span>"100/622"</span>, <span style="color: rgb(0, 116, 232);">"remainingQuantity": </span><span style="color: rgb(5, 139, 0);">622.0</span>, <span style="color: rgb(0, 116, 232);">"filledQuantity": </span><span style="color: rgb(5, 139, 0);">100.0</span>, <span style="color: rgb(0, 116, 232);">"avgPrice": </span><span>"382.45"</span>, }, { <span style="color: rgb(0, 116, 232);">"acct": </span><span>"DU1234"</span>, <span style="color: rgb(0, 116, 232);">"orderId": </span><span style="color: rgb(5, 139, 0);">352055828</span>, <span style="color: rgb(0, 116, 232);">"sizeAndFills": </span><span>"700/22"</span>, <span style="color: rgb(0, 116, 232);">"remainingQuantity": </span><span style="color: rgb(5, 139, 0);">22.0</span>, <span style="color: rgb(0, 116, 232);">"filledQuantity": </span><span style="color: rgb(5, 139, 0);">700.0</span>, }, { <span style="color: rgb(0, 116, 232);">"acct": </span><span>"DU1234"</span>, <span style="color: rgb(0, 116, 232);">"orderId": </span><span style="color: rgb(5, 139, 0);">352055828</span>, <span style="color: rgb(0, 116, 232);">"sizeAndFills": </span><span>"722"</span>, <span style="color: rgb(0, 116, 232);">"orderDesc": </span><span>"Sold 722 Limit 382.40 GTC"</span>, <span style="color: rgb(0, 116, 232);">"remainingQuantity": </span><span style="color: rgb(5, 139, 0);">0.0</span>, <span style="color: rgb(0, 116, 232);">"filledQuantity": </span><span style="color: rgb(5, 139, 0);">722.0</span>, <span style="color: rgb(0, 116, 232);">"status": </span><span>"Filled"</span>, <span style="color: rgb(0, 116, 232);">"timeInForce": </span><span>"GTC"</span>, <span style="color: rgb(0, 116, 232);">"price": </span><span style="color: rgb(5, 139, 0);">382.4</span>, <span style="color: rgb(0, 116, 232);">"bgColor": </span><span>"#FFFFFF"</span>, <span style="color: rgb(0, 116, 232);">"fgColor": </span><span>"#000000"</span> } ] } </pre></div> </li> <br> </ul> &#13;&#10;<hr> <h3>Profit and Loss</h3> For existing positions it is possible to receive Profit and Loss updates to the Web API using the topic <b>spl</b>. In the payload response the daily profit and loss (<b>dpl</b>) and unrealized profit and loss (<b>upl</b>) 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 <b>upl</b>. <br> &#13;&#10;<h4>Format: spl+{}</h4> <ul> <li>Request: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">`ws.send('spl+{}');` </pre></div> <br> </li> <li>Received: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"> <pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"topic"</span>: <span>"spl"</span> , <span style="color: rgb(0, 116, 232);">"args"</span>: { <span style="color: rgb(0, 116, 232);">"DU1234.Core"</span>: { <span style="color: rgb(0, 116, 232);">"rowType"</span>:<span style="color: rgb(5, 139, 0);">1</span>, <span style="color: rgb(0, 116, 232);">"dpl"</span>:<span style="color: rgb(5, 139, 0);">-57520.0</span> <span style="color: rgb(0, 116, 232);">"upl"</span>:<span style="color: rgb(5, 139, 0);">972100.0</span> } } } </pre></div> </li> <br> </ul> &#13;&#10;<h4>Format: upl{}</h4> <ul> <li> Request: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">`ws.send('upl{}');` </pre></div> <br> </li> </ul> &#13;&#10;<hr> <h3>Echo</h3> To maintain an active websocket connection the topic <b>ech</b> is used to send a hearbeat with the argument <b>hb</b>. It is advised to send a heatbeat at least once per minute. <br> &#13;&#10;<h4>Format: ech+hb</h4> <ul> <li>Request: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">`ws.send('ech+hb');` </pre></div> <br> </li> <li>Received: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">ech+hb </pre></div> <br> </li> </ul> &#13;&#10;<hr> <hr> ### <span style="font-size: 22px;">Unsolicited Message Types</span> ### System Connection When initially connecting to websocket the topic <b>system</b> 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. <br> - Received: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"topic"</span>: <span>"system"</span> , <span style="color: rgb(0, 116, 232);">"success"</span>: <span>"user123"</span> } { <span style="color: rgb(0, 116, 232);">"topic"</span>: <span>"system"</span> , <span style="color: rgb(0, 116, 232);">"hb"</span>: <span style="color: rgb(5, 139, 0);">1594677336001</span> } </pre></div> <br> - - - <h3>Authentication Status</h3> When connecting to websocket the topic <b>sts</b> will relay back the status of the authentication. Authentication status is already relayed back if there is a change, such as a competing sessions. <br> <ul> <li>Received: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"topic": </span><span>"sts"</span> , <span style="color: rgb(0, 116, 232);">"args": </span>{ <span style="color: rgb(0, 116, 232);">"authenticated": </span><span style="color: rgb(5, 139, 0);">true</span> } { <span style="color: rgb(0, 116, 232);">"topic": </span><span>"sts"</span> , <span style="color: rgb(0, 116, 232);">"args": </span>{ <span style="color: rgb(0, 116, 232);">"competing": </span><span style="color: rgb(5, 139, 0);">false</span> } } </pre></div> <br> </li></ul> &#13;&#10;<hr> <h3>Notifications</h3> If there is a brief message regarding trading activity the topic <b>ntf</b> will be sent. <br> <ul> <li>Received: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 46em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"topic": </span><span>"ntf"</span> , <span style="color: rgb(0, 116, 232);">"args": </span>{ <span style="color: rgb(0, 116, 232);">"id": </span><span style="color: rgb(5, 139, 0);">INDICATIVE_DATA_SUGGESTION</span> , <span style="color: rgb(0, 116, 232);">"text": </span><span>"CFD quotes reference the trade, volume and bid/ask market data on the underlying STK"</span> , <span style="color: rgb(0, 116, 232);">"title": </span><span>"Warning"</span> , <span style="color: rgb(0, 116, 232);">"url": </span><span>"https://interactivebrokers.com/"</span> } } </pre></div> <br> </li></ul> &#13;&#10;<hr> <h3>Bulletins</h3> If there is an urgent message concerning exchange issues, system problems and other trading information the topic <b>blt</b> is sent along with the message argument. <br> <ul> <li>Received: <br> <div style="background-color: rgb(255, 255, 255); background-image: initial; overflow-x: auto; overflow-y: auto; width: 22em; padding-top: 0.2em; padding-right: 0.6em; padding-bottom: 0.2em; padding-left: 0.6em;"><pre style="margin-top: 0; margin-right: 0; margin-bottom: 0; margin-left: 0; line-height: 125%;">{ <span style="color: rgb(0, 116, 232);">"topic": </span><span>"blt"</span> , <span style="color: rgb(0, 116, 232);">"args": </span>[ <span style="color: rgb(0, 116, 232);">"id": </span><span>""</span> , <span style="color: rgb(0, 116, 232);">"message": </span><span>""</span> ] } </pre></div>