ib-dx

Talk directly to IBKR. The TWS API your program already uses, with no IB Gateway, no Trader Workstation and no JVM between you and the venue.

Get started Python recipes Rust recipes GitHub

For ib_async, use ib_async-dx, which runs it on this engine.

One line changes

A program written against the TWS API talks to IB Gateway or Trader Workstation over a socket on localhost, and that process talks to the venue. ib-dx takes the gateway's place: it logs in, holds the trading, market-data, historical and security-definition connections open, and gives your program the same calls and the same callbacks.

- client.connect("127.0.0.1", 4001, clientId=1)     # needs a gateway running
+ client.connect(username="...", password="...")    # no external process

port is still accepted, and client.port reads it back while the session is held, but nothing connects on it. There is no local process to point it at.

What goes away

What you get

Where to go next

Status

Under active development. Every capability claim in this repository is assigned from a named artifact, a test, a script or a recorded server response, never from reading the code. The matrix is in capabilities.md, its counts are recomputed on every commit, and the build fails if one moves.

Both install routes build from the repository: see Getting started.

Getting started

What you need

• An Interactive Brokers account, paper or live. No IB software, and not the ibapi package either.
• Rust 1.89 or newer. Both install routes compile the engine.
• Python 3.11 or newer, for the Python surface.

Install

Both routes build from the repository.

Rust

[dependencies]
ib-dx = { git = "https://github.com/userFRM/ib-dx" }

Python

pip install "git+https://github.com/userFRM/ib-dx"

The package imports as ib_dx. The build backend is maturin, which compiles the Rust core into the extension module, and pyproject.toml names the features it needs, so there is nothing to pass. It builds for CPython 3.11 to 3.14 and the free-threaded 3.14t; the free-threaded 3.13t is not supported.

Either route compiles the engine, so it needs Rust 1.89 or newer and, on Linux, the OpenSSL headers and pkg-config (libssl-dev on Debian and Ubuntu, openssl-devel on Fedora and RHEL).

From the source

Working on the client itself, build it in place:

git clone https://github.com/userFRM/ib-dx
cd ib-dx
uv venv .venv
source .venv/bin/activate          # .venv\Scripts\activate on Windows
uv pip install maturin
maturin develop

maturin develop replaces the installed module. A local pytest run tests whatever was built last, so rebuild before running one.

Feature flags

default = []. The Rust client needs nothing turned on.

The features not in that table exist for this repository's own test suites. They are off by default and should stay off in anything you install.

Credentials

The credentials go in the connect call. There is no configuration file and no process holding a login on your behalf.

client.connect(username="your_user", password="your_pass", paper=True)

let client = EClient::connect(&Config {
    username: "your_user".into(),
    password: "your_pass".into(),
    paper: true,
    ..Default::default()
})?;

Do not name a host. Left empty, the client knocks on one of the venue's regional doors and the venue answers by naming the server this account actually lives on; the session moves there. A host is worth stating only to knock at a particular region.

paper. true skips the live second-factor approval gate — a paper session presents no second factor. false enters that gate on connect, and that call blocks until it is answered.

Which factor an account presents is stated by the venue when the gate opens, and this client handles two: an authenticator code, which has nothing to fall back on and needs a code_provider, and an IBKey push, which does not. Nothing below has been exercised against a live account from here, so treat the timing and the shape of the prompt as the venue's to state rather than as described.

Use a paper account while you are writing something. A live account is a live account.

One program per login. Each program opens its own session, and a login holds one session at a time: a second program on the same login takes the first one's session, and the venue names the host that took it. Give each program that runs at the same time a login of its own.

One place reads the environment instead of the call: the programs under examples/ read IB_USERNAME and IB_PASSWORD:

export IB_USERNAME="your_username"
export IB_PASSWORD="your_password"

Pick a surface

Every surface below drives the same engine. Pick by the program you have, not by capability.

For ib_async, use ib_async-dx, which runs it on this engine.

Hello, world

Both files below are the ones in the repository, included rather than copied, so this page cannot drift from what actually runs. The Rust one is compiled by CI along with the rest of examples/. Each subscribes to SPY for five seconds and prints the last quote it saw.

Rust

//! Recipe: stream SPY market data for 5 seconds, print latest bid/ask/last.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_tick_data

use std::env;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use ib_dx::api::client::{Contract, EClient, EClientConfig};
use ib_dx::api::types::TickAttrib;
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct State {
    bid: f64,
    ask: f64,
    last: f64,
    ticks: u64,
}

struct TickWrapper {
    state: Arc<Mutex<State>>,
}

impl Wrapper for TickWrapper {
    fn tick_price(&mut self, _req_id: i64, tick_type: i32, price: f64, _: &TickAttrib) {
        let mut s = self.state.lock().unwrap();
        s.ticks += 1;
        match tick_type {
            1 => s.bid = price,
            2 => s.ask = price,
            4 => s.last = price,
            _ => {}
        }
    }
    fn error(&mut self, req_id: i64, _error_time: i64, code: i64, msg: &str, _adv: &str) {
        if !matches!(code, 2104 | 2106 | 2158) {
            eprintln!("[error] req_id={req_id} code={code} msg={msg}");
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let state = Arc::new(Mutex::new(State::default()));
    let mut wrapper = TickWrapper { state: state.clone() };

    let spy = Contract {
        con_id: 756733,
        symbol: "SPY".into(),
        sec_type: "STK".into(),
        exchange: "SMART".into(),
        currency: "USD".into(),
        ..Default::default()
    };

    let req_id = 1;
    println!("streaming SPY for 5s…");
    client.req_mkt_data(req_id, &spy, "", false, false, &[]);

    let deadline = Instant::now() + Duration::from_secs(5);
    while Instant::now() < deadline {
        client.process_msgs(&mut wrapper);
        std::thread::sleep(Duration::from_millis(20));
    }

    client.cancel_mkt_data(req_id);

    let s = state.lock().unwrap();
    println!("ticks: {}  bid={:.2}  ask={:.2}  last={:.2}", s.ticks, s.bid, s.ask, s.last);

    drop(s);
    client.disconnect();
    Ok(())
}

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_tick_data

Python

"""Recipe: stream SPY market data for 5 seconds, print latest bid/ask/last.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_tick_data.py
"""

import os
import threading
import time

from ib_dx import EClient, EWrapper, Contract


class TickWrapper(EWrapper):
    def __init__(self):
        self.bid = 0.0
        self.ask = 0.0
        self.last = 0.0
        self.ticks = 0

    def tick_price(self, req_id, tick_type, price, attrib):
        self.ticks += 1
        if tick_type == 1:
            self.bid = price
        elif tick_type == 2:
            self.ask = price
        elif tick_type == 4:
            self.last = price

    def tick_size(self, req_id, tick_type, size):
        self.ticks += 1

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")


w = TickWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()

spy = Contract()
spy.con_id = 756733
spy.symbol = "SPY"
spy.sec_type = "STK"
spy.exchange = "SMART"
spy.currency = "USD"

req_id = 1
print("streaming SPY for 5s…")
c.req_mkt_data(req_id, spy, "", False, False)
deadline = time.monotonic() + 5
while time.monotonic() < deadline:
    time.sleep(0.1)
c.cancel_mkt_data(req_id)

print(f"ticks: {w.ticks}  bid={w.bid:.2f}  ask={w.ask:.2f}  last={w.last:.2f}")
c.disconnect()

IB_USERNAME=... IB_PASSWORD=... python examples/hello_tick_data.py

Next steps

• Login — connect, take the first order id, disconnect
• Streaming ticks · L2 depth
• Order lifecycle — place, modify, cancel, fill
• Limits — read this before you depend on a call
• Requests, delivery and shutdown — request signatures, ordered callbacks, error origins and the shutdown result

What the session states, and the API does not forward

This client speaks the protocol a gateway speaks. The gateway receives more than it forwards: some of what the venue states at logon and on a contract has no message in the API a gateway offers its own clients, so a program written against that API has no way to ask for it.

Everything below is stated by the venue on an ordinary session. The figures are from one paper session and will differ with the account; what does not differ is that none of it is reachable through ib_async or the TWS API.

The examples are Python. Every one of these has a Rust EClient equivalent — fields and Option-wrapped returns included — see the table at the end.

What the account may do

The venue states its grants at logon — one token per capability.

grants = client.enabled_features()          # 302 on the session this was written from
"ISLAND2NASDAQ" in grants                   # True

They decide behaviour. island_for_nasdaq — whether a US stock trading on Nasdaq is named by the older spelling — takes this grant as well as the setting, which is how it is decided: the same token is read off the same list at logon and holds it beside the setting.

Which orders the venue will take

Stated at logon, per security type, before a single order is sent.

perms = client.order_permissions()           # 21 security types
len(perms["STK"])                            # 92 order types and attributes
client.permitted_order_types("FUT")          # or None, if the type is not permitted at all

Through the API a program discovers this by being refused. An order for a security type absent from this map is refused before it is sent, with the reason on the error callback.

Which algorithms this account may use

Keyed by provider and security type: the documents that define them, as the venue lists them. The list is asked for the first time an order names an algorithm, as a gateway asks it, and is empty until then.

client.algorithms()                          # 13 keys: 'IBALGO/STK', 'FOXRIVER/STK', …
client.algorithms_for("STK")                 # ['FOXRIVER-AE', 'IBALGO-AE', 'JONES-AE', …]

An order is held to the definitions the list names for its contract (see an order through an algorithm).

Which order defaults the account holds

The venue keeps a set of order defaults per security type and fills parts of an order the caller left unstated from them: the size a compete order competes with and the offset it competes by, where neither was named. So the same call on two accounts is not the same order.

client.order_presets()      # [('s=CASH', 'v=1&a=1'), ('s=FUT', 'v=1&a=1'), ('s=STK', 'v=1&a=1'), …]

The key is the venue's own, and a currency can split one: s=CASH&tc=EUR sits beside s=CASH. The second figure is the set's attributes as the venue writes them: v= names its variant and a=1 marks it active, so ('s=CASH&tc=EUR', 'v=1') is a set that is not active. The values inside a set are asked for separately and are not carried here.

What the session itself is

client.get_account_id()                      # the account this session acts for
client.next_order_id()                       # the first id it may use
client.ccp_session_id()                      # what a web endpoint expects as a header
client.misc_url("region_dam")                # hosts the venue pushed at logon

How far away the venue is

client.req_ping()
client.last_rtt_ms()                         # 10.96 on the session this was written from

The API has no notion of this. A program that wants to know whether it is close to the venue has to time a request that does something else.

What the venue states about a contract, beyond its quote

A quote subscription can carry far more than prices. The venue publishes dozens of series against a contract, each under a number of its own, and the API forwards a handful of them. Ask for one by putting its number in the generic tick list, then read what it stated.

Some carry the venue's own named fields as text — analyst ratings, ownership, fund terms, screening scores, margin, technical readings, company accounts:

client.req_mkt_data(1, contract, "454,505,631,678,705", False, False, [])
client.company_data_series(265598)      # [434, 454, 505, 548, 631, 678, 699, 705, …]
client.company_data(265598, 454)        # [('IITPCHL', '47.7348'), … ('IISHOS', '14594180000')]
client.company_data(756733, 505)        # [('EXPRATIO', '0.0945'), ('TOTALASSETVALUE', '811937033817.46'), …]
client.company_data(265598, 705)        # [('TRESGS', '7.10404'), ('TRESGCS', '3.65619'), …]

The keys are the venue's own and are handed on unchanged, so a field it adds arrives with the rest instead of being dropped for not being recognised here. One of these series answered with 212 fields on a single contract.

Others carry figures rather than text — a bond's accrued interest, what one contract delivers, volatility, the volume a contract usually opens and closes on, what margin a future takes:

client.stated_figures_series(1)         # [398, 399, 402, 459, 493, 504, 527, 584, …]
client.stated_figures(1, 527)           # [0.0154349]   volatility over twenty days
client.stated_figures(1, 504)           # [383820.0, 1.0]  what one contract delivers
client.stated_figures(1, 407)           # [24340.8, 18338.7, 34772.6, 26198.1]

Six of them state the volatility a contract has shown over 10, 50, 75, 100, 150 and 200 days, one figure each: 511 and 513 to 517 (stated_figures(1, 511) and on).

The figures arrive in the venue's order and at its widths, and a figure it holds nothing for arrives as the largest number its field carries. Nothing is republished under a tick number of this client's own choosing.

Four series number their figures themselves, in two tables — whole numbers and fractional ones:

client.numbered_figures(1, 562, fractional=False)   # [(7, 20260911.0), (30, 20260814.0), … (1826, 20210917.0)]
client.numbered_figures(1, 562, fractional=True)    # [(7, 765.96), (30, 776.34), … (1826, 419.586)]
client.numbered_figures(1, 757, fractional=True)    # [(30, 766.106)]  the average close over thirty days

The first of those is a price history: the number is a span of days, the whole table holds the date each was taken and the fractional table the price on it, back to five years — from a quote subscription, with no historical-data request.

Two more state a run of paired figures, and one carries the venue's option model as the contract closed rather than as it stands — every greek it states, including several the API has no field for:

client.paired_figures(1, 546)           # [(coordinate, volatility), …]
client.closing_option_model(1)          # {'delta': …, 'rho': …, 'fugit': …, …}

Others state rows of three figures, and what the three are is the series' own: on 547 a quantity, what it is offered at and a second price where the form states one; on 320 a packed quote's field, its figure and how far its decimal point moves.

client.stated_rows_series(1)            # [320, 547]  which series stated rows
client.stated_rows(1, 547)              # [(quantity, price, second price), …]

Two more state what the venue's option model works an underlying's chain from, per class of its options and per expiry: 687 as it stands, and 691 as the chain closed. Each is asked for on a subscription on the underlying, and this client asks the venue for it on the option model's name, as a gateway does:

client.req_mkt_data(1, underlying, "687", False, False, [])
client.chain_model_parameters(1, 687)   # [{'productId': …, 'classes': [('SPY', [100.0])],
                                        #   'underlyingPrice': …, 'dividends': [(yyyymmdd, amount)],
                                        #   'terms': [{'lastTradeDate': …, 'modelYield': …,
                                        #              'interestRate': …, 'forward': …,
                                        #              'callAtmVol': …, 'putAtmVol': …}], …}]

A gateway reads both for its own model and hands none of it on. The two volatilities are per trading day; the venue states no unit for the yield and the rate. What a series stated goes when the series is withdrawn, as a gateway forgets it.

Series that are acknowledged and state nothing

Some series are acknowledged and then say nothing: the venue assigns the subscription a tag and states nothing on it, with no error to read. On the session this was written from, six behaved that way: 490, 546, 669, 700, 726 and 733. The same six on the same account, minutes apart, over both a paper and a live login.

An empty result from any of the calls above can mean two things: a series the venue has nothing to say about for that contract, or one this account is not entitled to. The subscription list in account management is what tells them apart.

Why this is not in the API

The API is a protocol between a gateway and a program on the same machine. What the gateway does with any of this is its own and not visible from here; what is visible is that none of it was ever framed as a message to forward. A client that speaks the venue's protocol receives it directly, so it is here.

Two consequences worth stating plainly:

• None of this is derived. Every figure above is stated by the venue, read off the session. Nothing here computes what the venue did not say.
• A gateway has no message for these. A program that calls one runs here and not against a gateway, so a program that has to run against both leaves them alone.

The same calls in Rust

Login

The smallest program that opens a session: connect, read the order id, disconnect.

Two flavours are shown. Paper for everyday testing, live for read-only checks against the real account.

What this shows

• Reading credentials from environment variables.
• EClient.connect(username=, password=, host=, paper=).
• Starting EClient.run on a daemon thread.
• Reading the order id off the next_valid_id callback.

What comes back

connect() blocks until the session is up, and fires three callbacks on your wrapper before it returns, on the calling thread: connect_ack, managed_accounts, then next_valid_id.

next_valid_id is fired last on purpose. The venue names what the account has already used just after the connection is made, and an id announced before that lands is one a fill spent long ago. A program that trusted it would have its first order refused as a duplicate.

So when connect() returns, the session is established and the id has already been delivered. The wait() in the example is belt and braces, not a gate.

The daemon run() thread is what carries every callback after connect: quotes, order status, bars, errors. Start it, or nothing further arrives.

Limits

A live login may push a second factor. Approve it on your authenticator; connect() blocks until the gate clears, so give it a longer wall clock than a paper login needs.

The live example is read-only: it logs in, prints, and disconnects. Send orders from the paper account.

Paper

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_login.py

Source

"""Hello-world recipe: connect, wait for next_valid_id, disconnect.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_login.py
"""

import os
import threading

from ib_dx import EClient, EWrapper


class LoginWrapper(EWrapper):
    def __init__(self):
        self.ready = threading.Event()
        self.order_id = None

    def next_valid_id(self, order_id):
        self.order_id = order_id
        self.ready.set()


w = LoginWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()

if not w.ready.wait(timeout=15):
    raise RuntimeError("did not receive next_valid_id")

print(f"logged in. next_valid_id = {w.order_id}")

c.disconnect()

Live

Run it

IB_LIVE_USERNAME=... IB_LIVE_PASSWORD=... python examples/hello_login_live.py

Source

"""Live-account login recipe: connect with paper=False, wait for next_valid_id,
disconnect. Read-only — no orders, no market data.

When the live login triggers a second-factor push, approve it on your mobile
authenticator. The connect call blocks until the gate clears.

Usage:
    IB_LIVE_USERNAME=... IB_LIVE_PASSWORD=... python examples/hello_login_live.py
"""

import os
import threading

from ib_dx import EClient, EWrapper


class LoginWrapper(EWrapper):
    def __init__(self):
        self.ready = threading.Event()
        self.order_id = None

    def next_valid_id(self, order_id):
        self.order_id = order_id
        self.ready.set()


w = LoginWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_LIVE_USERNAME"],
    password=os.environ["IB_LIVE_PASSWORD"],
    host=os.environ.get("IB_HOST", ""),
    paper=False,
)
threading.Thread(target=c.run, daemon=True).start()

if not w.ready.wait(timeout=60):
    raise RuntimeError("did not receive next_valid_id")

print(f"logged in LIVE. next_valid_id = {w.order_id}")

c.disconnect()

Request Contract Details

Resolve a symbol: send a partial description, collect every contract the venue lists under it, stop when the end marker lands. This is how you turn "AAPL" into a con_id you can quote and trade on.

What this shows

• Building a partial Contract from symbol, sec_type, exchange and currency.
• req_contract_details(req_id, contract) and the contract_details callback.
• Driving the callback loop on a daemon thread with EClient.run.
• Reading con_id, primary_exchange and trading_class off the returned ContractDetails.

What comes back

One contract_details callback per matching contract, then one contract_details_end for the request id. A description that matches several listings answers with all of them, so more than one row means an ambiguous description rather than an error.

The shorter form

Two blocking methods do the same work with no wrapper and no callbacks:

rows = c.contract_details(aapl)   # list, every match
one  = c.qualify_contract(aapl)   # a single Contract

qualify_contract refuses an ambiguous description rather than handing back whichever the venue listed first, which would be a different contract from the one you asked about. c.qualify_contracts([...]) takes several at once. Nothing that answers these calls reaches your wrapper, even what arrives after the call has returned.

These send, wait and return. They take their answer off the queue by request id and release the interpreter lock while waiting, so they need no run() thread of their own. Do not run both styles on one client: run() drains every queue rather than only its own, so a dispatch loop beside a blocking call competes with it for the answer. Pick the callbacks or pick these.

Lookups by contract id

A lookup by con_id includes the requested exchange. Leaving the exchange empty asks for the preferred definition. The same rule applies when a market data request needs to name a contract given only by id.

Contract details reuse exchange rule scopes already returned during the session. A first lookup can still need a separate request for each missing exchange; later lookups reuse those answers. CORPACT is excluded because it does not name a trading venue.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_contract_details.py

Source

"""Recipe: req_contract_details for AAPL on paper, print con_id and primary exchange.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_contract_details.py
"""

import os
import threading

from ib_dx import EClient, EWrapper, Contract


class DetailsWrapper(EWrapper):
    def __init__(self):
        self.rows = []
        self.done = threading.Event()

    def contract_details(self, req_id, details):
        self.rows.append(details)

    def contract_details_end(self, req_id):
        self.done.set()

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")


w = DetailsWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()

aapl = Contract()
aapl.symbol = "AAPL"
aapl.sec_type = "STK"
aapl.exchange = "SMART"
aapl.currency = "USD"
c.req_contract_details(1, aapl)

if not w.done.wait(timeout=15):
    raise RuntimeError("contract_details_end not received")

print(f"matches: {len(w.rows)}")
for d in w.rows:
    print(f"  con_id={d.contract.con_id:>8}  "
          f"primary={d.contract.primary_exchange:<10}  "
          f"trading_class={d.contract.trading_class}")

c.disconnect()

Historical Bars

Fetch one trading day of 5-minute SPY bars and print the first and last. Use this whenever you need a finished series rather than a live feed.

What this shows

• Building a Contract that carries con_id, so the venue is not asked to guess which listing you meant.
• req_historical_data(req_id, contract, end_date_time, duration_str, bar_size_setting, what_to_show, use_rth), with format_date, keep_up_to_date and chart_options left at their defaults.
• Driving the callback loop on a daemon thread with EClient.run.
• Reading OHLCV off the bar object.

An empty end_date_time means now. use_rth=1 keeps the series inside regular hours.

What comes back

One historical_data callback per bar, in time order, then one historical_data_end carrying the first and last timestamps of the range that was served. A request whose bars are refused once it has been handed over is told why on error, and nothing follows it: a gateway states no end after a refusal, so a program waiting for the end stops on the error too. A request kept up to date whose five-second stream the venue refuses is told nothing, as a gateway tells it nothing: a history still to come arrives with its end, and no update follows. When the historical connection drops, a request kept up to date ends on 10182, and one still arriving is told 165 and asked again once the connection is back, as a gateway does. A 165 is a notice and ends nothing: the call that waits for the bars waits through it.

With keep_up_to_date=True the bar still forming goes on from the history's last bar, as a gateway's does: the live five-second bars inside it are folded into the open, high, low and volume the venue stated for it. Five-second bars are sent as the stream sends them. One that arrives before the history is in is held, as a gateway holds it, and folded into the history's last bar with the next one after it; one from before the bar in hand opened is passed over. So nothing of the bar still forming is heard before historical_data_end, and every update is heard on historical_data_update, whatever else the request's number has done: a live bar stream under the same number is heard on real_time_bar, and a second request under the number, refused while this one answers, leaves this one's dates as it asked for them. A daily session supplied with the history keeps its opening and end across UTC midnight. Its updates use the session end's date on the series' timezone, as the history does, under both date-format settings. Timed daily history is returned as yyyyMMdd; explicit weekly and monthly date strings are preserved.

When that session ends, the next five-second bar opens the next bar at midnight UTC of its own day, as a gateway opens it. That bar ends at the next midnight UTC, or at the close the history stated where that falls between the two, and is dated by where it ends on the series' timezone; a bar that has ended is opened again by the next five-second bar. So a session that opens before midnight UTC, as a future's evening session does, is dated by the day the history closed until midnight UTC, and by the next one after it. On a timezone east of UTC the next midnight UTC falls on the following day there, so the bar a session there rolls over to is dated by the day after that session, as a gateway dates it. Intraday bars open on whole multiples of their length from the epoch; a week opens on Monday and a month on its first day at midnight UTC. Updates to these calendar bars remain dates under both date-format settings.

The shorter form

One blocking method does the same request and returns the list:

bars = c.historical_data(spy, "", "1 D", "5 mins", "TRADES", use_rth=1)

It sends, waits and returns, taking its answer off the queue by request id and releasing the interpreter lock while it waits. Do not run run() beside it on the same client: run() drains every queue rather than only its own, so the two compete for the answer. Pick the callbacks or pick this.

Cancelling historical data also withdraws the corporate-actions query held by that request. A separate corporate-actions request keeps running, even when it uses the same caller request id.

Limits

bar_size_setting and what_to_show are checked before anything is sent, so a misspelling is refused here rather than answered with a different series. With keep_up_to_date=True the size must be one this client can form from the five-second bars the venue keeps sending: five seconds up to a day in whole multiples of five seconds, a week, or a month. A second is shorter than what arrives and is refused. A request kept up to date is refused, as a gateway refuses it, with an end date, on a combination, or on a series other than TRADES, MIDPOINT, BID, ASK and the two option open-interest series — an empty series name included.

How far back a series goes, and which bar sizes pair with which durations, are the venue's rules. A request outside them comes back as a stated refusal on the error callback rather than as empty bars.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_bar_data.py

Source

"""Recipe: fetch 1 day of 5-minute SPY bars, print first/last bar.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_bar_data.py
"""

import os
import threading

from ib_dx import EClient, EWrapper, Contract


class BarsWrapper(EWrapper):
    def __init__(self):
        self.bars = []
        self.done = threading.Event()

    def historical_data(self, req_id, bar):
        self.bars.append(bar)

    def historical_data_end(self, req_id, start, end):
        self.done.set()

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")
        # A refused request is told the error alone: no end follows it.
        if req_id == 1:
            self.done.set()


w = BarsWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()

spy = Contract()
spy.con_id = 756733
spy.symbol = "SPY"
spy.sec_type = "STK"
spy.exchange = "SMART"
spy.currency = "USD"

c.req_historical_data(
    1, spy,
    end_date_time="",
    duration_str="1 D",
    bar_size_setting="5 mins",
    what_to_show="TRADES",
    use_rth=1,
)

if not w.done.wait(timeout=30):
    raise RuntimeError("the bar request was not answered")

print(f"bars: {len(w.bars)}")
if w.bars:
    first, last = w.bars[0], w.bars[-1]
    print(f"  first: {first.date}  O={first.open} H={first.high} L={first.low} C={first.close} V={first.volume}")
    print(f"  last : {last.date}  O={last.open} H={last.high} L={last.low} C={last.close} V={last.volume}")

c.disconnect()

Streaming Ticks

Subscribe to top-of-book on SPY, collect for five seconds, print the latest bid, ask and last.

What this shows

• req_mkt_data(req_id, contract, generic_tick_list, snapshot, regulatory_snapshot).
• Reading prices off tick_price, where tick_type names which price it is: 1 bid, 2 ask, 4 last, 9 close.
• cancel_mkt_data(req_id) before disconnecting.

What comes back

tick_req_params (tickReqParams in Python) states the contract's price increment, exchange and snapshot permission once per request, with the first record the request is served and ahead of its ticks, as a gateway states it; a request served no record is told nothing. It reads the latest stored parameters when the callback is delivered. Where the venue names no best-bid-and-offer exchange, as for a currency, a crypto or a bond, the exchange is empty. The permission is 0 there, on a bond, a bill, a fixed-income contract or a combination, and while the frozen quote is served in place of the live one, whatever the venue stated, as a gateway states it. On a closed market whose frozen quote is served, that is the record the parameters go out with, so the permission is 0. A follower sharing the subscription gets its own callback; cancelling and reusing its request id starts a new request. A request cancelled before delivery receives no callback.

tick_price and tick_size for as long as the subscription runs.

tick_generic fires for the halt state the venue states on tick 49: 0 while the contract is trading, 1 once it has stopped.

With snapshot=True you get the first available quote, then tick_snapshot_end, and this client cancels the subscription for you.

regulatory_snapshot=True is the venue's own one-shot snapshot. It is a different request type, and an account without the entitlement is refused by the venue.

Limits

Each number in generic_tick_list is asked for, as a subscription of its own beside the prices. The number you state is the number the venue knows the series by, so there is nothing to translate. "292" additionally subscribes to news for that contract, and "292:BRFG+DJNL" asks for it from the providers it names; an entry that is not a number is reported rather than sent.

Every number the protocol will accept in that list is read here, and each arrives under the number the reference client publishes it under:

Any other number is asked for the same way, as a series of its own. What the venue states on series the TWS API has no tick for is read through the calls under Beyond the documented API.

One subscription per contract. To change the mode on a contract, cancel first.

Every subscription starts live, whatever the type set on req_market_data_type. As a gateway takes the types, 2 turns frozen data on, 3 and 4 turn delayed data on (4 with delayed-frozen, 3 without), and only 1 turns frozen data off, so a 2 asked after a 3 or a 4 still leaves the delayed feed to fall back to. With delayed data on, a bid/ask refusal that states delayed data is available switches to the delayed feed and reports 10167 without ending the request, and market_data_type reports 3. With nothing to fall back to, the refusal ends the request as a gateway ends it: under 354, "Requested market data is not subscribed.", followed by "Delayed market data is available." where the refusal says so; or under 10089, where the services the refusal names for the API reach past those it names for the data. The venue's own words follow either, as sent. Under type 2 alone the request ends there, and no frozen quote is asked for.

Where the logon enables frozen data, the market's status is watched, as a gateway watches it, for a subscription made with frozen data on while it is served live, and for one that has fallen back to delayed data with delayed-frozen data on. While the status says the market is closed, the frozen quote is asked for beside the live one and served, reported as 2; beside a delayed one the delayed-frozen quote is asked for too, and served from its first record, reported as 4, the delayed one until then. The quote asked for first is kept up meanwhile, and once the status says the market is open the frozen quotes are withdrawn and that quote is served again as it stands, reported as 1 or 3. A refusal of the live quote ends the watch on it without a word: the frozen quote beside it is withdrawn, and so is the status, unless the fallback watches it. So a login entitled to live data is served live under type 4 alone, and on a closed market its quote states what the live feed states, zero yields included; under type 2, alone or before a 4, it is served the frozen quote. A calculation's own subscription falls back to nothing: it asks the delayed feed directly where delayed data is on, and watches no status.

req_mkt_data_ex selects a feed directly: mode_9887 is 0 realtime, 1 delayed, 2 frozen, or 3 delayed-frozen. Frozen keeps thinly traded names quoting after hours, when the realtime feed is silent.

A refusal naming several requests reaches each affected caller. The bid/ask and last entries of one quote produce one subscription error. Cancelling a tick-by-tick stream uses its query identifier before acknowledgement and its assigned stream identifier afterwards; another caller sharing that stream keeps receiving data until it cancels too.

req_mkt_data_ex takes mkt_data_options=None after mode_9887, with the same option checks as req_mkt_data. With no session, both report 504, Not connected, before checking the request.

The list accepts manual=0 or manual=1. An unknown key is refused under 10337, an invalid value under 10338, and a malformed list under 320. NOAPIMISCVLD at logon lifts the key and value checks; the later check that manual is zero or one remains.

Reading without the callbacks

c.quote(req_id) returns a dict of bid, ask, last, bid_size, ask_size, last_size, volume, high, low, open, close for a running subscription, or None if that request id is not subscribed. No wrapper state to keep, no lock to take.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_tick_data.py

Source

"""Recipe: stream SPY market data for 5 seconds, print latest bid/ask/last.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_tick_data.py
"""

import os
import threading
import time

from ib_dx import EClient, EWrapper, Contract


class TickWrapper(EWrapper):
    def __init__(self):
        self.bid = 0.0
        self.ask = 0.0
        self.last = 0.0
        self.ticks = 0

    def tick_price(self, req_id, tick_type, price, attrib):
        self.ticks += 1
        if tick_type == 1:
            self.bid = price
        elif tick_type == 2:
            self.ask = price
        elif tick_type == 4:
            self.last = price

    def tick_size(self, req_id, tick_type, size):
        self.ticks += 1

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")


w = TickWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()

spy = Contract()
spy.con_id = 756733
spy.symbol = "SPY"
spy.sec_type = "STK"
spy.exchange = "SMART"
spy.currency = "USD"

req_id = 1
print("streaming SPY for 5s…")
c.req_mkt_data(req_id, spy, "", False, False)
deadline = time.monotonic() + 5
while time.monotonic() < deadline:
    time.sleep(0.1)
c.cancel_mkt_data(req_id)

print(f"ticks: {w.ticks}  bid={w.bid:.2f}  ask={w.ask:.2f}  last={w.last:.2f}")
c.disconnect()

Streaming L2 Market Depth

Subscribe to Level-2 depth on two contracts at once, keep a bid and ask book per contract from the update stream, and print top-of-book at the end.

What this shows

• req_mkt_depth(req_id, contract, num_rows=5), one request id per contract.
• Applying update_mkt_depth_l2 events to a book keyed by level position.
• cancel_mkt_depth(req_id, is_smart_depth) for each subscription before disconnecting, naming the mode the book was asked in.

What comes back

update_mkt_depth_l2(req_id, position, market_maker, operation, side, price, size, is_smart_depth) on every level change:

A level carries the maker the venue names on it. An exchange-level book often names none — many venues quote no makers — and then the field is empty; on the aggregated book the exchange stands in where the venue names no maker. That is why the example keeps market_maker alongside price and size.

The example collects for the whole window and prints once at the end, not on every update. DURATION_SECS sets that window; the default is 15.

After a reconnect the venue restates the book from the top. The client reports that on error as 317, the TWS API's notice that a book was reset, before the first new level arrives — as a gateway does. Empty the book on it, or the levels that follow land on top of the old ones.

Limits

A depth subscription the venue will not serve is refused, and the refusal arrives on the error callback. The example prints an em dash for a side with no levels rather than failing, so a book that never started shows up as zero updates rather than as an error.

A contract whose security type and exchange are both left off is sent as it stands, and an unnamed exchange is read as the smart destination. Naming a security type that does not match the contract asks for one book as another's, which the venue refuses.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_l2.py

Collect for longer:

DURATION_SECS=30 python examples/hello_l2.py

Source

"""Recipe: stream L2 market depth on AAPL + TSLA, print top-of-book on update.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_l2.py
"""

import os
import threading
import time

from ib_dx import EClient, EWrapper, Contract


class Book:
    def __init__(self, symbol):
        self.symbol = symbol
        self.bids = {}   # position -> (price, size, mm)
        self.asks = {}
        self.updates = 0

    def apply(self, position, mm, operation, side, price, size):
        self.updates += 1
        book = self.bids if side == 1 else self.asks
        if operation in (0, 1):
            book[position] = (price, size, mm)
        elif operation == 2:
            book.pop(position, None)

    def top(self):
        bid = max(self.bids.values(), default=None, key=lambda v: v[0])
        ask = min(self.asks.values(), default=None, key=lambda v: v[0])
        return bid, ask


class L2Wrapper(EWrapper):
    def __init__(self, books):
        self.books = books          # req_id -> Book

    def update_mkt_depth_l2(self, req_id, position, market_maker,
                            operation, side, price, size, is_smart_depth):
        if req_id in self.books:
            self.books[req_id].apply(position, market_maker, operation, side, price, size)

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")


def make_stk(con_id, symbol):
    c = Contract()
    c.con_id = con_id
    c.symbol = symbol
    c.sec_type = "STK"
    c.exchange = "SMART"
    c.currency = "USD"
    return c


SUBSCRIPTIONS = [
    (1, make_stk(265598, "AAPL")),
    (2, make_stk(76792991, "TSLA")),
]
DURATION_SECS = int(os.environ.get("DURATION_SECS", "15"))

books = {req_id: Book(c.symbol) for req_id, c in SUBSCRIPTIONS}
w = L2Wrapper(books)
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()

for req_id, contract in SUBSCRIPTIONS:
    c.req_mkt_depth(req_id, contract, num_rows=5)

print(f"streaming L2 for {DURATION_SECS}s…")
time.sleep(DURATION_SECS)

for req_id, _ in SUBSCRIPTIONS:
    c.cancel_mkt_depth(req_id)

for book in books.values():
    bid, ask = book.top()
    bid_s = f"{bid[0]:.2f} x {bid[1]:.0f}" if bid else "—"
    ask_s = f"{ask[0]:.2f} x {ask[1]:.0f}" if ask else "—"
    print(f"  {book.symbol:<5} updates={book.updates:>5}  bid={bid_s:>14}   ask={ask_s:<14}")

c.disconnect()

Market Scanner

Run the TOP_PERC_GAIN scan over US major stocks, filtered to names above $5, and print the top ten.

What this shows

• req_scanner_subscription(req_id, subscription), where subscription is any object carrying the right attributes. The example defines a small class; the reference client's own ScannerSubscription works too.
• Reading scanner_data rows, each a rank and a ContractDetails, until scanner_data_end.
• cancel_scanner_subscription(req_id) before disconnecting.

What the subscription object is read for

The scan itself:

Then the filters, each read by attribute and sent under the venue's own tag name: abovePrice, belowPrice, aboveVolume, marketCapAbove, marketCapBelow, moodyRatingAbove, moodyRatingBelow, spRatingAbove, spRatingBelow, maturityDateAbove, maturityDateBelow, couponRateAbove, couponRateBelow, averageOptionVolumeAbove, plus excludeConvertible and stockTypeFilter.

An attribute you leave off takes its default. One that is present and cannot be read is refused rather than run as a different scan under your request id.

What comes back

One scanner_data callback per row, then scanner_data_end for the request id. Rows are ranked; the example sorts by rank because it collects them into a list first.

A scanner subscription keeps answering until it is cancelled. The example cancels; if you leave one running it goes on delivering into a session nobody is reading.

Limits

Which scan codes and locations are valid is the venue's list. req_scanner_parameters() fetches it, and an unknown code comes back as a stated refusal on the error callback. When the historical connection drops, a running scan is told 165 as it drops, at each attempt to bring it back that fails and once it is back, and is then subscribed again and goes on under its number, as a gateway does; a 165 ends nothing.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_scanner.py

Source

"""Recipe: subscribe to TOP_PERC_GAIN scanner, print first 10 results.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_scanner.py
"""

import os
import threading

from ib_dx import EClient, EWrapper


class ScannerSubscription:
    def __init__(self):
        self.instrument = "STK"
        self.locationCode = "STK.US.MAJOR"
        self.scanCode = "TOP_PERC_GAIN"
        self.numberOfRows = 25
        self.abovePrice = 5.0


class ScannerWrapper(EWrapper):
    def __init__(self):
        self.rows = []
        self.done = threading.Event()

    def scanner_data(self, req_id, rank, contract_details,
                     distance, benchmark, projection, legs_str):
        self.rows.append((rank, contract_details))

    def scanner_data_end(self, req_id):
        self.done.set()

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")


w = ScannerWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()

req_id = 1
print("subscribing TOP_PERC_GAIN, STK.US.MAJOR…")
c.req_scanner_subscription(req_id, ScannerSubscription())

if not w.done.wait(timeout=30):
    print(f"(scanner_data_end not received; got {len(w.rows)} rows so far)")

w.rows.sort(key=lambda r: r[0])
print(f"results: {len(w.rows)}")
for rank, d in w.rows[:10]:
    print(f"  #{rank:<3}  {d.contract.symbol:<8} {d.contract.primary_exchange:<6} con_id={d.contract.con_id}")

c.cancel_scanner_subscription(req_id)
c.disconnect()

Request Account PnL

Subscribe to the account-level PnL stream, take the first update, cancel and disconnect.

What this shows

• c.get_account_id(), which names the account the session opened under.
• req_pnl(req_id, account).
• Reading daily_pnl, unrealized_pnl and realized_pnl off the pnl callback.
• cancel_pnl(req_id) before disconnecting.

account empty means the account this session opened under.

What comes back

The venue states what each holding was worth at midnight and what it has realised since. The three figures on the pnl callback are worked out from those against the prices this session is being told, so they move as the session's quotes move.

Limits

account is checked as a gateway checks it, in its order and words: a blank one is refused (Account must not be empty, 321); one the login does not hold is refused (Invalid account code, 321), and so is All on a login holding one account or where the logon says the login may not ask for every account; All on a login the venue adds accounts to is refused (This API request for All is not supported for Dynamic Account Addition, 321). Another account the login holds, and All where a gateway would take it, are refused too, on both clients: the figures are worked out from one account's midnight seeds and holdings, the one this session opened under. Nothing is subscribed for a refused request.

model_code is taken and not applied. There is no model portfolio to name here, so leave it at its default.

cancel_pnl stops the updates. The venue has no message withdrawing the subscription itself, on a gateway as here, so the updates stopping is what the call does.

An account with no position reports zeros. Pair this with the limit-order recipe if you want to watch the numbers move.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_pnl.py

Source

"""Recipe: subscribe to account-level PnL, take one update, then cancel.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_pnl.py
"""

import os
import threading

from ib_dx import EClient, EWrapper


class PnlWrapper(EWrapper):
    def __init__(self):
        self.got_pnl = threading.Event()
        self.pnl_data = None

    def pnl(self, req_id, daily_pnl, unrealized_pnl, realized_pnl):
        self.pnl_data = (daily_pnl, unrealized_pnl, realized_pnl)
        self.got_pnl.set()

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")


w = PnlWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()


account = c.get_account_id()
print(f"account: {account}")

req_id = 1
c.req_pnl(req_id, account)

if w.got_pnl.wait(timeout=15):
    daily, unrealized, realized = w.pnl_data
    print(f"daily={daily:.2f}  unrealized={unrealized:.2f}  realized={realized:.2f}")
else:
    print("no pnl update within 15s — try again with an open position")

c.cancel_pnl(req_id)
c.disconnect()

Send a Limit Order

Place a BUY LMT on SPY far below market, watch it acknowledge, then cancel it. Connect, take an id, place, read status, cancel, disconnect.

What this shows

• Taking the order id off next_valid_id, which connect() fires before it returns. c.next_order_id() reserves one directly if you would rather ask.
• An Order with order_type = "LMT" and lmt_price set. outside_rth = True is what lets it be acknowledged outside regular hours.
• order_status callbacks. PreSubmitted then Submitted while it rests, Cancelled once the cancel lands.
• cancel_order(order_id, order_cancel). The second argument is what the withdrawal states about itself: an OrderCancel (who is withdrawing it, whether a person entered it, a manual time), or a time alone; "" states nothing. The operator and who entered it travel on the cancel. A time does not, and the caller is told so on error; a time a gateway cannot read is refused under 10301 and the order keeps working.

What comes back

order_status on every change and again on each fill. filled and remaining are quantities, avg_fill_price is the average of what has filled so far. An order that rests will sit at Submitted until you cancel it.

The perm_id on that callback is the number the order goes to the venue under, as a gateway states it, which for this order is its own order id. It is stated from the moment the order is sent and stays the same for the life of the order, including across a modify.

Limits

Order ids count from one past the highest id the account is working an order under, which the venue names at every connect, from every session. So one taken here does not collide with an order placed elsewhere.

tif is checked against what the venue carries: DAY, GTC, IOC, FOK, OPG, GTD, GTX, DTC, AUC, NMIN, spelled exactly. An unrecognised value is refused here rather than sent as DAY and quietly expiring at the close.

Paper account only. The price is set far below market so it will not fill.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_limit_order.py

Source

"""Recipe: place a non-marketable BUY LMT on SPY, watch Submitted, then cancel.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_limit_order.py
"""

import os
import threading

from ib_dx import EClient, EWrapper, Contract, Order


class OrderWrapper(EWrapper):
    def __init__(self):
        self.next_id = None
        self.submitted = threading.Event()
        self.cancelled = threading.Event()

    def next_valid_id(self, order_id):
        self.next_id = order_id

    def order_status(self, order_id, status, filled, remaining,
                     avg_fill_price, perm_id, parent_id,
                     last_fill_price, client_id, why_held, mkt_cap_price):
        print(f"[status] oid={order_id} status={status}")
        if status == "Submitted":
            self.submitted.set()
        if status == "Cancelled":
            self.cancelled.set()

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")


w = OrderWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()


order_id = w.next_id

spy = Contract()
spy.con_id = 756733
spy.symbol = "SPY"
spy.sec_type = "STK"
spy.exchange = "SMART"
spy.currency = "USD"

order = Order()
order.action = "BUY"
order.total_quantity = 1
order.order_type = "LMT"
order.lmt_price = 1.00
order.tif = "DAY"
order.outside_rth = True

print(f"placing BUY 1 SPY LMT 1.00 (oid={order_id})")
c.place_order(order_id, spy, order)
w.submitted.wait(timeout=15)

print(f"cancelling oid={order_id}")
c.cancel_order(order_id, "")
w.cancelled.wait(timeout=15)

c.disconnect()

Send a Stop Order

Place a BUY STOP on SPY far above market. The trigger never fires, so the order rests. Watch it acknowledge, then cancel it.

What this shows

• Taking the order id off next_valid_id, which connect() fires before it returns.
• An Order with order_type = "STP" and the trigger price in aux_price. lmt_price is unused for a plain stop.
• tif = "GTC", so it survives the close rather than expiring with the day.
• order_status callbacks: PreSubmitted then Submitted while it rests, Cancelled once the cancel lands.
• cancel_order(order_id, "").

What comes back

The same order_status stream as any other order. A resting stop shows no fills: filled stays 0 and remaining stays at the full quantity until the trigger is touched.

Limits

A stop is held until its trigger is touched, then goes to the market as a market order. This example sets the trigger far above market so that never happens. On a real stop, the fill price is whatever the market gives you at that moment, not the trigger.

Paper account only.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/hello_stop_order.py

Source

"""Recipe: place a BUY STP on SPY far above market, watch Submitted, then cancel.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/hello_stop_order.py
"""

import os
import threading

from ib_dx import EClient, EWrapper, Contract, Order


class OrderWrapper(EWrapper):
    def __init__(self):
        self.next_id = None
        self.submitted = threading.Event()
        self.cancelled = threading.Event()

    def next_valid_id(self, order_id):
        self.next_id = order_id

    def order_status(self, order_id, status, filled, remaining,
                     avg_fill_price, perm_id, parent_id,
                     last_fill_price, client_id, why_held, mkt_cap_price):
        print(f"[status] oid={order_id} status={status}")
        if status == "Submitted":
            self.submitted.set()
        if status == "Cancelled":
            self.cancelled.set()

    def error(self, req_id, error_time, code, msg, advanced=""):
        if code not in (2104, 2106, 2158):
            print(f"[error] {code}: {msg}")


w = OrderWrapper()
c = EClient(w)
c.connect(
    username=os.environ["IB_USERNAME"],
    password=os.environ["IB_PASSWORD"],
    paper=True,
)
threading.Thread(target=c.run, daemon=True).start()


order_id = w.next_id

spy = Contract()
spy.con_id = 756733
spy.symbol = "SPY"
spy.sec_type = "STK"
spy.exchange = "SMART"
spy.currency = "USD"

order = Order()
order.action = "BUY"
order.total_quantity = 1
order.order_type = "STP"
order.aux_price = 9999.0
order.tif = "GTC"
order.outside_rth = True

print(f"placing BUY 1 SPY STP 9999.00 (oid={order_id})")
c.place_order(order_id, spy, order)
w.submitted.wait(timeout=15)

print(f"cancelling oid={order_id}")
c.cancel_order(order_id, "")
w.cancelled.wait(timeout=15)

c.disconnect()

Order Lifecycle

One order walked through every state it can reach on SPY: place, modify, fill, cancel, and the executions query afterwards. Use this when you are changing order handling and want each transition checked, rather than as a template to copy into a strategy.

It prints a pass/fail line per step and exits non-zero if any step failed.

What this shows

• Taking the first order id off next_valid_id and counting up from it. The example keeps its own counter so it can hold two ids at once; c.next_order_id() reserves one directly.
• Placing a limit order far from market and reading Submitted off order_status.
• req_open_orders(), and finding the order in the open_order callbacks.
• Placing again under the same order id at a new price, which is a modify, and checking the permId did not move.
• Walking the price to market to trigger a fill, then req_executions(req_id).
• Placing a second order, cancelling it, and reading the Cancelled terminal status.
• Flattening whatever filled before disconnecting.

What comes back

req_open_orders() waits up to three seconds for the replay the venue sends unprompted after a connect, then fires open_order and order_status for each working order. It waits because answering before that replay lands reports none of them, and a caller who reads "nothing working" places the same order twice. req_all_open_orders() is the same call.

req_executions(req_id) replays the day's executions — the fills this session has seen and the ones the venue restated when the session opened — then fires exec_details_end. A restarted program is answered with the fills it made before it restarted, including fills on orders that had already completed. What is not in it is the account's history: the venue restates a day, not a life, and this protocol has no question that asks for more. The fill in step 6 happens inside this session, which is why the query finds it either way.

An exec_filter is read by attribute: symbol, secType, exchange, side. A side of BUY or SELL is translated to the venue's own word before matching, so a filter written the way you write an order action works.

permId

The perm_id on order_status is the number the order goes to the venue under, as a gateway states it: for an order placed here, the number this client sent it under, and for one another session placed, the number that session sent it under. It is stable for the life of the order, which is what step 5 checks: a modify keeps the same order, so it keeps the same permId. A modify or a cancel of an order another session placed keeps that session's number too. It is not a key on its own: a number whose order was withdrawn or refused is free again at the venue, so orders the account finished under a number used twice share a permId, and completed_order delivers each of them.

Limits

Paper account only. Step 6 deliberately crosses the spread, so it moves real paper position; the script flattens it at the end.

Steps 6 and 7 need an open market. With the market shut, price discovery falls back to SPY_PRICE (default 630.0), nothing fills, and both steps report failure rather than passing on a market that never traded.

Run it

IB_USERNAME=... IB_PASSWORD=... python examples/order_lifecycle.py

Source

"""Order lifecycle on SPY: place, modify, cancel, fill, executions.

Walks an order through every state it can reach and checks each one, so a
change to order handling shows up here rather than in a live account.

  1. Take the next order id.
  2. Place SPY 100 shares, LMT far from market.
  3. req_open_orders() — the order is there, under a permId.
  4. Place again under the same id, at a new price — a modify.
  5. The permId is the same across the modify.
  6. Place again at market — trigger a fill.
  7. req_executions() — the fill is reported with its quantity and price.
  8. Place another LMT far from market, cancel it, see Cancelled.

Ends by flattening whatever step 6 filled.

Usage:
    IB_USERNAME=... IB_PASSWORD=... python examples/order_lifecycle.py
"""

import os
import sys
import time
import threading
from ib_dx import EWrapper, EClient, Contract, Order

SPY_CON_ID = 756733


class Wrapper(EWrapper):
    def __init__(self):
        super().__init__()
        self.next_id = 0

        self.order_statuses = []   # (order_id, status, filled, remaining, perm_id)
        self.perm_ids = {}         # order_id -> perm_id
        self.open_orders = []      # (order_id, contract, order)
        self.executions = []       # (req_id, contract, execution)

        self.got_status = threading.Event()
        self.got_fill = threading.Event()
        self.got_cancelled = threading.Event()
        self.got_open_order_end = threading.Event()
        self.got_exec_end = threading.Event()

        # Price discovery
        self.last_price = 0.0
        self.got_tick = threading.Event()

    def next_valid_id(self, order_id):
        self.next_id = order_id

    def managed_accounts(self, accounts_list):
        pass

    def connect_ack(self):
        pass

    def tick_price(self, req_id, tick_type, price, attrib):
        if price > 0 and tick_type in (1, 2, 4):
            self.last_price = price
            self.got_tick.set()

    def tick_size(self, req_id, tick_type, size):
        pass

    def order_status(self, order_id, status, filled, remaining,
                     avg_fill_price, perm_id, parent_id,
                     last_fill_price, client_id, why_held, mkt_cap_price):
        self.order_statuses.append((order_id, status, filled, remaining, perm_id))
        self.perm_ids[order_id] = perm_id
        print(f"  [status] oid={order_id} status={status} filled={filled} "
              f"remaining={remaining} permId={perm_id}")
        self.got_status.set()
        if status == "Filled" or filled > 0:
            self.got_fill.set()
        if status == "Cancelled":
            self.got_cancelled.set()

    def open_order(self, order_id, contract, order, order_state):
        self.open_orders.append((order_id, contract, order))

    def open_order_end(self):
        self.got_open_order_end.set()

    def exec_details(self, req_id, contract, execution):
        self.executions.append((req_id, contract, execution))
        print(f"  [exec] symbol={contract.symbol} exec={execution}")

    def exec_details_end(self, req_id):
        self.got_exec_end.set()

    def commission_and_fees_report(self, commission_and_fees_report):
        pass

    def error(self, req_id, error_time, error_code, error_string, advanced_order_reject_json=""):
        if error_code not in (2104, 2106, 2158, 202):
            print(f"  [error] {error_code}: {error_string}")


def make_spy():
    c = Contract()
    c.con_id = SPY_CON_ID
    c.symbol = "SPY"
    c.sec_type = "STK"
    c.exchange = "SMART"
    c.currency = "USD"
    return c


def alloc_id(wrapper):
    oid = wrapper.next_id
    wrapper.next_id += 1
    return oid


def get_price(client, wrapper):
    spy = make_spy()
    client.req_mkt_data(9999, spy, "", False)
    got = wrapper.got_tick.wait(timeout=30)
    client.cancel_mkt_data(9999)
    if not got or wrapper.last_price <= 0:
        return None
    return wrapper.last_price


def last_status_for(wrapper, oid):
    """Return last (status, remaining) for a given order_id, or (None, None)."""
    matches = [s for s in wrapper.order_statuses if s[0] == oid]
    if matches:
        return matches[-1][1], matches[-1][3]
    return None, None


def run_example():
    username = os.environ.get("IB_USERNAME", "")
    password = os.environ.get("IB_PASSWORD", "")
    if not username or not password:
        print("Set IB_USERNAME and IB_PASSWORD")
        sys.exit(1)

    w = Wrapper()
    c = EClient(w)
    c.connect(username=username, password=password,
              host=os.environ.get("IB_HOST", ""), paper=True)
    t = threading.Thread(target=c.run, daemon=True)
    t.start()
    print(f"Connected. nextValidId={w.next_id}")

    spy = make_spy()
    results = {}  # step -> pass/fail
    filled_qty = 0  # how many shares are left to flatten

    # ── Price discovery ──────────────────────────────────────────────────
    price = get_price(c, w)
    if price is None:
        # Use last known close as fallback when market is closed
        price = float(os.environ.get("SPY_PRICE", "630.0"))
        print(f"No live price — using fallback: {price}")
    else:
        print(f"SPY last price: {price}")

    # ══════════════════════════════════════════════════════════════════════
    # Step 1: reqIds — get next valid orderId
    # ══════════════════════════════════════════════════════════════════════
    print("\n=== Step 1: reqIds ===")
    oid1 = alloc_id(w)
    print(f"  orderId={oid1}")
    results["1_reqIds"] = "PASS"

    # ══════════════════════════════════════════════════════════════════════
    # Step 2: placeOrder — SPY 100 shares, LMT far from market
    # ══════════════════════════════════════════════════════════════════════
    print("\n=== Step 2: placeOrder (100 shares LMT far from market) ===")
    order1 = Order()
    order1.action = "BUY"
    order1.total_quantity = 100
    order1.order_type = "LMT"
    order1.lmt_price = round(price * 0.80, 2)  # 20% below market
    order1.tif = "GTC"
    order1.outside_rth = True

    c.place_order(oid1, spy, order1)
    assert w.got_status.wait(timeout=30), "No order status received"

    perm_id_place = w.perm_ids.get(oid1, 0)
    assert perm_id_place > 0, f"permId should be positive, got {perm_id_place}"
    print(f"  permId on place: {perm_id_place}")
    print(f"  lmt_price={order1.lmt_price} (20% below market)")
    results["2_place"] = "PASS"

    # ══════════════════════════════════════════════════════════════════════
    # Step 3: reqOpenOrders — verify order appears with correct permId
    # ══════════════════════════════════════════════════════════════════════
    print("\n=== Step 3: reqOpenOrders ===")
    c.req_open_orders()
    assert w.got_open_order_end.wait(timeout=15), "open_order_end not received"
    placed = [o for o in w.open_orders if o[0] == oid1]
    assert len(placed) > 0, "the order should appear in open orders"
    print(f"  Found {len(placed)} open order(s) for oid={oid1}")
    results["3_reqOpenOrders"] = "PASS"

    # ══════════════════════════════════════════════════════════════════════
    # Step 4: placeOrder (same orderId, new price) — modify
    # ══════════════════════════════════════════════════════════════════════
    print("\n=== Step 4: Modify order (same orderId, price closer to market) ===")
    w.got_status.clear()
    order1.lmt_price = round(price * 0.90, 2)  # 10% below — still won't fill
    c.place_order(oid1, spy, order1)
    assert w.got_status.wait(timeout=15), "No status on modify"

    status_after_modify, remaining_after_modify = last_status_for(w, oid1)
    modify_ok = status_after_modify == "Submitted" and remaining_after_modify == 100.0
    print(f"  new lmt_price={order1.lmt_price} (10% below market)")
    print(f"  status after modify: {status_after_modify}, remaining: {remaining_after_modify}")
    if modify_ok:
        results["4_modify"] = "PASS"
    else:
        results["4_modify"] = f"FAIL (expected Submitted/100, got {status_after_modify}/{remaining_after_modify})"

    # ══════════════════════════════════════════════════════════════════════
    # Step 5: Verify permId stable across modify
    # ══════════════════════════════════════════════════════════════════════
    print("\n=== Step 5: Verify permId stability ===")
    perm_id_modify = w.perm_ids[oid1]
    perm_stable = perm_id_place == perm_id_modify
    print(f"  permId after modify: {perm_id_modify} (stable={perm_stable})")
    results["5_permId_stable"] = "PASS" if perm_stable else f"FAIL ({perm_id_place} → {perm_id_modify})"

    # ══════════════════════════════════════════════════════════════════════
    # Step 6: placeOrder (same orderId, price at market) — trigger fill
    # ══════════════════════════════════════════════════════════════════════
    print("\n=== Step 6: Modify to market price (trigger fill) ===")
    time.sleep(2)  # let the venue settle the first modify
    w.got_status.clear()
    w.got_fill.clear()
    # Re-fetch price in case it moved
    w.got_tick.clear()
    c.req_mkt_data(9998, spy, "", False)
    if w.got_tick.wait(timeout=10) and w.last_price > 0:
        price = w.last_price
    c.cancel_mkt_data(9998)
    order1.lmt_price = round(price * 1.02, 2)  # slightly above market
    c.place_order(oid1, spy, order1)

    got_fill = w.got_fill.wait(timeout=30)
    if got_fill:
        fill_statuses = [s for s in w.order_statuses
                         if s[0] == oid1 and (s[1] == "Filled" or s[2] > 0)]
        if fill_statuses:
            filled_qty = int(fill_statuses[-1][2])  # how much was filled
            perm_id_fill = w.perm_ids[oid1]
            print(f"  Fill confirmed: qty={filled_qty}, permId={perm_id_fill}")
            results["6_fill_via_modify"] = "PASS"
        else:
            results["6_fill_via_modify"] = "FAIL (got_fill but no fill status)"
    else:
        status_now, _ = last_status_for(w, oid1)
        print(f"  No fill via modify (status={status_now})")
        results["6_fill_via_modify"] = f"FAIL (no fill, status={status_now})"

    # ══════════════════════════════════════════════════════════════════════
    # Step 7: reqExecutions — verify execDetails
    # ══════════════════════════════════════════════════════════════════════
    print("\n=== Step 7: reqExecutions ===")
    c.req_executions(8001)
    w.got_exec_end.wait(timeout=15)
    spy_execs = [e for e in w.executions if e[1].symbol == "SPY"]
    if spy_execs:
        print(f"  Found {len(spy_execs)} SPY execution(s)")
        results["7_reqExecutions"] = "PASS"
    else:
        print("  No SPY executions (expected if step 6 failed)")
        results["7_reqExecutions"] = "FAIL (no executions)" if got_fill else "SKIP (no fill in step 6)"

    # ══════════════════════════════════════════════════════════════════════
    # Step 8: Place another LMT far from market, then cancelOrder
    # ══════════════════════════════════════════════════════════════════════
    print("\n=== Step 8: Place another LMT far, then cancelOrder ===")
    w.got_status.clear()
    w.got_cancelled.clear()
    oid2 = alloc_id(w)
    order2 = Order()
    order2.action = "BUY"
    order2.total_quantity = 100
    order2.order_type = "LMT"
    order2.lmt_price = round(price * 0.80, 2)  # 20% below
    order2.tif = "GTC"
    order2.outside_rth = True

    c.place_order(oid2, spy, order2)
    assert w.got_status.wait(timeout=30), "No status for cancel-test order"
    submitted = [s for s in w.order_statuses if s[0] == oid2 and s[1] == "Submitted"]
    assert len(submitted) > 0, "Cancel-test order should be Submitted"
    print(f"  Order {oid2} submitted, permId={w.perm_ids.get(oid2, 0)}")

    c.cancel_order(oid2, "")
    got_cancel = w.got_cancelled.wait(timeout=15)
    if got_cancel:
        cancel_statuses = [s for s in w.order_statuses if s[0] == oid2 and s[1] == "Cancelled"]
        assert len(cancel_statuses) > 0, "Should have Cancelled status"
        print(f"  Order {oid2} cancelled OK")
        results["8_cancel"] = "PASS"
    else:
        results["8_cancel"] = "FAIL (cancel not confirmed within 15s)"

    # ══════════════════════════════════════════════════════════════════════
    # Cleanup: flatten any position from step 6
    # ══════════════════════════════════════════════════════════════════════
    if filled_qty > 0:
        print(f"\n=== Cleanup: Sell {filled_qty} to flatten ===")
        oid3 = alloc_id(w)
        sell = Order()
        sell.action = "SELL"
        sell.total_quantity = filled_qty
        sell.order_type = "MKT"
        sell.tif = "DAY"
        c.place_order(oid3, spy, sell)
        time.sleep(5)

    c.disconnect()
    t.join(timeout=5)

    # ══════════════════════════════════════════════════════════════════════
    # Summary
    # ══════════════════════════════════════════════════════════════════════
    print("\n" + "=" * 60)
    print("RESULTS SUMMARY")
    print("=" * 60)
    for step, result in results.items():
        mark = "PASS" if result == "PASS" else "FAIL"
        print(f"  [{mark}] {step}: {result}")

    passed = sum(1 for r in results.values() if r == "PASS")
    total = len(results)
    print(f"\n  {passed}/{total} steps passed")
    print("=" * 60)

    if passed == total:
        print("\n✓ Example complete — all steps passed")
    else:
        print(f"\n✗ Example complete — {total - passed} step(s) failed")
        sys.exit(1)


if __name__ == "__main__":
    run_example()

Login

The smallest program that opens a session: connect, read the order id this client would place under, disconnect.

Two flavours are shown. Paper for everyday testing, live for read-only checks against the real account.

What this shows

• Reading credentials from environment variables into EClientConfig.
• paper: true for the paper account, paper: false for the live one.
• client.account_id, which names the account the session opened under.
• req_ids, which reports the next order id.

What comes back

EClient::connect blocks until the session is up. When it returns, the session is established and client.account_id is populated. There is nothing further to wait for.

connect states the next order id once, as a gateway does: the first process_msgs read after the venue has named what the account is working calls next_valid_id on your wrapper, with one past the highest id the account is working an order under. req_ids states it again without asking the venue anything. The venue names that working set unprompted at every connect, from every session, not only this one. Nothing is reserved by either; the reservation happens when you place.

Limits

A live login may push a second factor. Approve it on your authenticator; the connect call blocks until the gate clears, so give it a longer wall clock than a paper login needs.

The live example is read-only: it logs in, prints, and disconnects. Send orders from the paper account.

Paper

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_login

Source

//! Hello-world recipe: connect, request next_valid_id, disconnect.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_login

use std::env;

use ib_dx::api::client::{EClient, EClientConfig};
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct LoginWrapper {
    next_id: Option<i64>,
}

impl Wrapper for LoginWrapper {
    fn next_valid_id(&mut self, order_id: i64) {
        self.next_id = Some(order_id);
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let mut wrapper = LoginWrapper::default();
    client.req_ids(1); client.process_msgs(&mut wrapper);

    let next_id = wrapper.next_id.ok_or("did not receive next_valid_id")?;
    println!("logged in. account = {}, next_valid_id = {next_id}", client.account_id);

    client.disconnect();
    Ok(())
}

Live

Run it

IB_LIVE_USERNAME=... IB_LIVE_PASSWORD=... cargo run --example hello_login_live

Source

//! Live-account login recipe: connect with `paper: false`, request next_valid_id,
//! Disconnect. Read-only — no orders, no market data.
//!
//! When the live login triggers a second-factor push, approve it on your mobile
//! Authenticator. The connect call blocks until the gate clears.
//!
//! Usage: IB_LIVE_USERNAME=... IB_LIVE_PASSWORD=... cargo run --example hello_login_live

use std::env;

use ib_dx::api::client::{EClient, EClientConfig};
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct LoginWrapper {
    next_id: Option<i64>,
}

impl Wrapper for LoginWrapper {
    fn next_valid_id(&mut self, order_id: i64) {
        self.next_id = Some(order_id);
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_LIVE_USERNAME")?,
        password: env::var("IB_LIVE_PASSWORD")?,
        host: env::var("IB_HOST").unwrap_or_default(),
        paper: false,
        ..Default::default()
    })?;

    let mut wrapper = LoginWrapper::default();
    client.req_ids(1); client.process_msgs(&mut wrapper);

    let next_id = wrapper.next_id.ok_or("did not receive next_valid_id")?;
    println!("logged in LIVE. account = {}, next_valid_id = {next_id}", client.account_id);

    client.disconnect();
    Ok(())
}

Request Contract Details

Resolve a symbol: send a partial description, collect every contract the venue lists under it, stop when the end marker lands. This is how you turn "AAPL" into a con_id you can quote and trade on.

What this shows

• Building a partial Contract from symbol, sec_type, exchange and currency.
• req_contract_details(req_id, &contract), and reading answers off the contract_details callback.
• Pumping the callbacks with process_msgs until contract_details_end fires.
• Reading con_id, primary_exchange and trading_class out of ContractDetails.

What comes back

One contract_details callback per matching contract, then one contract_details_end for the request id. A description that matches several listings answers with all of them, so rows.len() above one is an ambiguous description rather than an error.

The shorter form

req_contract_details is the request-and-callback shape. Two blocking calls do the same work without the wrapper:

let rows = client.contract_details(&aapl)?;   // every match
let one  = client.qualify_contract(&aapl)?;   // the single match

qualify_contract refuses an ambiguous description rather than handing back whichever the venue listed first, which would be a different contract from the one you asked about. Nothing that answers either call reaches the wrapper process_msgs is handed, even what arrives after the call has returned.

Lookups by contract id

A lookup by con_id includes the requested exchange. Leaving the exchange empty asks for the preferred definition. The same rule applies when a market data request needs to name a contract given only by id.

Contract details reuse exchange rule scopes already returned during the session. A first lookup can still need a separate request for each missing exchange; later lookups reuse those answers. CORPACT is excluded because it does not name a trading venue.

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_contract_details

Source

//! Recipe: req_contract_details for AAPL on paper, print con_id and primary exchange.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_contract_details

use std::env;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use ib_dx::api::client::{Contract, EClient, EClientConfig};
use ib_dx::api::types::ContractDetails;
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct State {
    rows: Vec<ContractDetails>,
    end_seen: bool,
}

struct DetailsWrapper {
    state: Arc<Mutex<State>>,
}

impl Wrapper for DetailsWrapper {
    fn contract_details(&mut self, _req_id: i64, details: &ContractDetails) {
        self.state.lock().unwrap().rows.push(details.clone());
    }
    fn contract_details_end(&mut self, _req_id: i64) {
        self.state.lock().unwrap().end_seen = true;
    }
    fn error(&mut self, req_id: i64, _error_time: i64, code: i64, msg: &str, _adv: &str) {
        eprintln!("[error] req_id={req_id} code={code} msg={msg}");
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let state = Arc::new(Mutex::new(State::default()));
    let mut wrapper = DetailsWrapper { state: state.clone() };

    let aapl = Contract {
        symbol: "AAPL".into(),
        sec_type: "STK".into(),
        exchange: "SMART".into(),
        currency: "USD".into(),
        ..Default::default()
    };
    client.req_contract_details(1, &aapl);

    let deadline = Instant::now() + Duration::from_secs(15);
    while Instant::now() < deadline {
        client.process_msgs(&mut wrapper);
        if state.lock().unwrap().end_seen { break; }
        std::thread::sleep(Duration::from_millis(20));
    }

    let s = state.lock().unwrap();
    println!("matches: {}", s.rows.len());
    for d in &s.rows {
        println!(
            "  con_id={:>8}  primary={:<10}  trading_class={}",
            d.contract.con_id, d.contract.primary_exchange, d.contract.trading_class,
        );
    }

    drop(s);
    client.disconnect();
    Ok(())
}

Historical Bars

Fetch one trading day of 5-minute SPY bars and print the first and last. Use this whenever you need a finished series rather than a live feed.

What this shows

• Building a Contract that carries con_id, so the venue is not asked to guess which listing you meant.
• req_historical_data, which takes every argument the request carries: req_id, contract, end_date_time, duration, bar_size, what_to_show, use_rth, format_date, keep_up_to_date.
• Pumping the callbacks with process_msgs until historical_data_end lands, or the request's refusal does.
• Reading OHLCV out of BarData.

An empty end_date_time means now. use_rth: true keeps the series inside regular hours. format_date: 1 asks for the date written out rather than as seconds. keep_up_to_date: false asks for closed bars only.

What comes back

One historical_data callback per bar, in time order, then one historical_data_end carrying the first and last timestamps of the range that was served. A request whose bars are refused once it has been handed over is told why on error, and nothing follows it: a gateway states no end after a refusal, so a program waiting for the end stops on the error too. A request kept up to date whose five-second stream the venue refuses is told nothing, as a gateway tells it nothing: a history still to come arrives with its end, and no update follows. When the historical connection drops, a request kept up to date ends on 10182, and one still arriving is told 165 and asked again once the connection is back, as a gateway does. A 165 is a notice and ends nothing: the call that waits for the bars waits through it.

With keep_up_to_date: true the bar still forming goes on from the history's last bar, as a gateway's does: the live five-second bars inside it are folded into the open, high, low and volume the venue stated for it. Five-second bars are sent as the stream sends them. One that arrives before the history is in is held, as a gateway holds it, and folded into the history's last bar with the next one after it; one from before the bar in hand opened is passed over. So nothing of the bar still forming is heard before historical_data_end, and every update is heard on historical_data_update, whatever else the request's number has done: a live bar stream under the same number is heard on real_time_bar, and a second request under the number, refused while this one answers, leaves this one's dates as it asked for them. A daily session supplied with the history keeps its opening and end across UTC midnight. Its updates use the session end's date on the series' timezone, as the history does, under both date-format settings. Timed daily history is returned as yyyyMMdd; explicit weekly and monthly date strings are preserved.

When that session ends, the next five-second bar opens the next bar at midnight UTC of its own day, as a gateway opens it. That bar ends at the next midnight UTC, or at the close the history stated where that falls between the two, and is dated by where it ends on the series' timezone; a bar that has ended is opened again by the next five-second bar. So a session that opens before midnight UTC, as a future's evening session does, is dated by the day the history closed until midnight UTC, and by the next one after it. On a timezone east of UTC the next midnight UTC falls on the following day there, so the bar a session there rolls over to is dated by the day after that session, as a gateway dates it. Intraday bars open on whole multiples of their length from the epoch; a week opens on Monday and a month on its first day at midnight UTC. Updates to these calendar bars remain dates under both date-format settings.

The shorter form

Two blocking calls do the same request without a wrapper:

let bars = client.historical_data(&spy, "", "1 D", "5 mins", "TRADES", true)?;
let same = client.bars(&spy, "1 D", "5 mins")?;

bars fills in the arguments most callers state the same way: trades, regular hours, ending now. It asks for MIDPOINT instead of TRADES on instruments that are quoted rather than traded (CASH, CFD, CMDTY), which answer a TRADES request with no history at all.

Cancelling historical data also withdraws the corporate-actions query held by that request. A separate corporate-actions request keeps running, even when it uses the same caller request id.

Limits

bar_size and what_to_show are checked before anything is sent, so a misspelling is refused here rather than answered with a different series. With keep_up_to_date: true the size must be one this client can form from the five-second bars the venue keeps sending: five seconds up to a day in whole multiples of five seconds, a week, or a month. A second is shorter than what arrives and is refused. A request kept up to date is refused, as a gateway refuses it, with an end date, on a combination, or on a series other than TRADES, MIDPOINT, BID, ASK and the two option open-interest series — an empty series name included.

How far back a series goes, and which bar sizes pair with which durations, are the venue's rules. A request outside them comes back as a stated refusal on the error callback rather than as empty bars.

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_bar_data

Source

//! Recipe: fetch 1 day of 5-minute SPY bars, print first/last bar.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_bar_data

use std::env;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use ib_dx::api::client::{Contract, EClient, EClientConfig};
use ib_dx::api::types::BarData;
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct State {
    bars: Vec<BarData>,
    done: bool,
}

struct BarsWrapper {
    state: Arc<Mutex<State>>,
}

impl Wrapper for BarsWrapper {
    fn historical_data(&mut self, _req_id: i64, bar: &BarData) {
        self.state.lock().unwrap().bars.push(bar.clone());
    }
    fn historical_data_end(&mut self, _req_id: i64, _start: &str, _end: &str) {
        self.state.lock().unwrap().done = true;
    }
    fn error(&mut self, req_id: i64, _error_time: i64, code: i64, msg: &str, _adv: &str) {
        eprintln!("[error] req_id={req_id} code={code} msg={msg}");
        // A refused request is told the error alone: no end follows it.
        if req_id == 1 {
            self.state.lock().unwrap().done = true;
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let state = Arc::new(Mutex::new(State::default()));
    let mut wrapper = BarsWrapper { state: state.clone() };

    let spy = Contract {
        con_id: 756733,
        symbol: "SPY".into(),
        sec_type: "STK".into(),
        exchange: "SMART".into(),
        currency: "USD".into(),
        ..Default::default()
    };
    client.req_historical_data(1, &spy, "", "1 D", "5 mins", "TRADES", true, 1, false);

    let deadline = Instant::now() + Duration::from_secs(30);
    while Instant::now() < deadline {
        client.process_msgs(&mut wrapper);
        if state.lock().unwrap().done { break; }
        std::thread::sleep(Duration::from_millis(20));
    }

    let s = state.lock().unwrap();
    println!("bars: {}", s.bars.len());
    if let (Some(first), Some(last)) = (s.bars.first(), s.bars.last()) {
        println!("  first: {}  O={} H={} L={} C={} V={}",
                 first.date, first.open, first.high, first.low, first.close, first.volume);
        println!("  last : {}  O={} H={} L={} C={} V={}",
                 last.date, last.open, last.high, last.low, last.close, last.volume);
    }

    drop(s);
    client.disconnect();
    Ok(())
}

Streaming Ticks

Subscribe to top-of-book on SPY, collect for five seconds, print the latest bid, ask and last.

What this shows

• req_mkt_data(req_id, &contract, generic_tick_list, snapshot, regulatory_snapshot, mkt_data_options).
• Reading prices off tick_price, where tick_type names which price it is: 1 bid, 2 ask, 4 last, 9 close.
• cancel_mkt_data(req_id) before disconnecting.

What comes back

tick_req_params (tickReqParams in Python) states the contract's price increment, exchange and snapshot permission once per request, with the first record the request is served and ahead of its ticks, as a gateway states it; a request served no record is told nothing. It reads the latest stored parameters when the callback is delivered. Where the venue names no best-bid-and-offer exchange, as for a currency, a crypto or a bond, the exchange is empty. The permission is 0 there, on a bond, a bill, a fixed-income contract or a combination, and while the frozen quote is served in place of the live one, whatever the venue stated, as a gateway states it. On a closed market whose frozen quote is served, that is the record the parameters go out with, so the permission is 0. A follower sharing the subscription gets its own callback; cancelling and reusing its request id starts a new request. A request cancelled before delivery receives no callback.

tick_price and tick_size for as long as the subscription runs.

tick_generic fires for the halt state the venue states on tick 49: 0 while the contract is trading, 1 once it has stopped.

With snapshot: true you get the first available quote, then tick_snapshot_end, and this client cancels the subscription for you. That is this client ending a subscription, not a separate request.

regulatory_snapshot: true is the venue's own one-shot snapshot. It is a different request type, and an account without the entitlement is refused by the venue. It also ends on tick_snapshot_end.

Limits

Each number in generic_tick_list is asked for, as a subscription of its own beside the prices. The number you state is the number the venue knows the series by, so there is nothing to translate. "292" additionally subscribes to news for that contract, and "292:BRFG+DJNL" asks for it from the providers it names; an entry that is not a number is reported rather than sent.

Every number the protocol will accept in that list is read here, and each arrives under the number the reference client publishes it under:

Any other number is asked for the same way, as a series of its own. What the venue states on series the TWS API has no tick for is read through the calls under Beyond the documented API.

One subscription per contract. To change the mode on a contract, cancel first.

Every subscription starts live, whatever the type set on req_market_data_type. As a gateway takes the types, 2 turns frozen data on, 3 and 4 turn delayed data on (4 with delayed-frozen, 3 without), and only 1 turns frozen data off, so a 2 asked after a 3 or a 4 still leaves the delayed feed to fall back to. With delayed data on, a bid/ask refusal that states delayed data is available switches to the delayed feed and reports 10167 without ending the request, and market_data_type reports 3. With nothing to fall back to, the refusal ends the request as a gateway ends it: under 354, "Requested market data is not subscribed.", followed by "Delayed market data is available." where the refusal says so; or under 10089, where the services the refusal names for the API reach past those it names for the data. The venue's own words follow either, as sent. Under type 2 alone the request ends there, and no frozen quote is asked for.

Where the logon enables frozen data, the market's status is watched, as a gateway watches it, for a subscription made with frozen data on while it is served live, and for one that has fallen back to delayed data with delayed-frozen data on. While the status says the market is closed, the frozen quote is asked for beside the live one and served, reported as 2; beside a delayed one the delayed-frozen quote is asked for too, and served from its first record, reported as 4, the delayed one until then. The quote asked for first is kept up meanwhile, and once the status says the market is open the frozen quotes are withdrawn and that quote is served again as it stands, reported as 1 or 3. A refusal of the live quote ends the watch on it without a word: the frozen quote beside it is withdrawn, and so is the status, unless the fallback watches it. So a login entitled to live data is served live under type 4 alone, and on a closed market its quote states what the live feed states, zero yields included; under type 2, alone or before a 4, it is served the frozen quote. A calculation's own subscription falls back to nothing: it asks the delayed feed directly where delayed data is on, and watches no status.

req_mkt_data_ex selects a feed directly: mode_9887 is 0 realtime, 1 delayed, 2 frozen, or 3 delayed-frozen. Frozen keeps thinly traded names quoting after hours, when the realtime feed is silent.

A refusal naming several requests reaches each affected caller. The bid/ask and last entries of one quote produce one subscription error. Cancelling a tick-by-tick stream uses its query identifier before acknowledgement and its assigned stream identifier afterwards; another caller sharing that stream keeps receiving data until it cancels too.

Both quote requests take mkt_data_options: &[TagValue], in req_mkt_data_ex after mode_9887. Pass &[] when there are no options. With no session, both calls report 504, Not connected, before checking the request.

The list accepts manual=0 or manual=1. An unknown key is refused under 10337, an invalid value under 10338, and a malformed list under 320. NOAPIMISCVLD at logon lifts the key and value checks; the later check that manual is zero or one remains.

Reading without the callback loop

quote(req_id) returns the latest bid, ask, last and sizes for a running subscription, with no wrapper and no lock. quote_of(&contract) does the same by contract. Both return None until the first tick has landed.

Prices and sizes on Quote are integers scaled by PRICE_SCALE and QTY_SCALE (both 10⁸). Divide when you display; the tick_price callback hands you f64 already.

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_tick_data

Source

//! Recipe: stream SPY market data for 5 seconds, print latest bid/ask/last.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_tick_data

use std::env;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use ib_dx::api::client::{Contract, EClient, EClientConfig};
use ib_dx::api::types::TickAttrib;
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct State {
    bid: f64,
    ask: f64,
    last: f64,
    ticks: u64,
}

struct TickWrapper {
    state: Arc<Mutex<State>>,
}

impl Wrapper for TickWrapper {
    fn tick_price(&mut self, _req_id: i64, tick_type: i32, price: f64, _: &TickAttrib) {
        let mut s = self.state.lock().unwrap();
        s.ticks += 1;
        match tick_type {
            1 => s.bid = price,
            2 => s.ask = price,
            4 => s.last = price,
            _ => {}
        }
    }
    fn error(&mut self, req_id: i64, _error_time: i64, code: i64, msg: &str, _adv: &str) {
        if !matches!(code, 2104 | 2106 | 2158) {
            eprintln!("[error] req_id={req_id} code={code} msg={msg}");
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let state = Arc::new(Mutex::new(State::default()));
    let mut wrapper = TickWrapper { state: state.clone() };

    let spy = Contract {
        con_id: 756733,
        symbol: "SPY".into(),
        sec_type: "STK".into(),
        exchange: "SMART".into(),
        currency: "USD".into(),
        ..Default::default()
    };

    let req_id = 1;
    println!("streaming SPY for 5s…");
    client.req_mkt_data(req_id, &spy, "", false, false, &[]);

    let deadline = Instant::now() + Duration::from_secs(5);
    while Instant::now() < deadline {
        client.process_msgs(&mut wrapper);
        std::thread::sleep(Duration::from_millis(20));
    }

    client.cancel_mkt_data(req_id);

    let s = state.lock().unwrap();
    println!("ticks: {}  bid={:.2}  ask={:.2}  last={:.2}", s.ticks, s.bid, s.ask, s.last);

    drop(s);
    client.disconnect();
    Ok(())
}

Streaming L2 Market Depth

Subscribe to Level-2 depth on two contracts at once, keep a bid and ask book per contract from the update stream, and print both books at the end.

What this shows

• req_mkt_depth(req_id, &contract, num_rows, is_smart_depth), one request id per contract.
• Applying update_mkt_depth_l2 events to a book keyed by level position.
• cancel_mkt_depth(req_id, is_smart_depth) for each subscription before disconnecting, naming the mode the book was asked in.

What comes back

update_mkt_depth_l2 per level change, carrying the level position, the market maker, and:

A level carries the maker the venue names on it. An exchange-level book often names none — many venues quote no makers — and then the field is empty; on the aggregated book the exchange stands in where the venue names no maker. That is why the example keeps market_maker alongside price and size.

The example collects for the whole window and prints each book once at the end, not on every update. DURATION_SECS sets that window; the default is 15.

After a reconnect the venue restates the book from the top. The client reports that on error as 317, the TWS API's notice that a book was reset, before the first new level arrives — as a gateway does. Empty the book on it, or the levels that follow land on top of the old ones.

Limits

A depth subscription the venue will not serve is refused, and the refusal arrives on the error callback. A book that stays empty means the subscription never started, not that the market is empty.

The example asserts at the end that both books received updates and that neither is empty, so it panics rather than reporting success on a feed that never delivered. Run it while the market is open.

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example l2_aapl_tsla

Collect for longer:

DURATION_SECS=30 cargo run --example l2_aapl_tsla

Source

//! Subscribe to L2 market depth for AAPL + TSLA and print the order book.
//!
//! Usage:
//!   IB_USERNAME=user IB_PASSWORD=pass cargo run --example l2_aapl_tsla
//!
//! Optional env vars:
//!   IB_HOST       — the venue host to log in to (default: the venue names it)
//!   DURATION_SECS — how long to collect data (default: 15)

use std::collections::HashMap;
use std::env;
use std::time::{Duration, Instant};

use ib_dx::api::client::{EClient, EClientConfig, Contract};
use ib_dx::api::wrapper::Wrapper;

// ── Book entry ──

#[derive(Debug, Clone)]
struct BookLevel {
    price: f64,
    size: f64,
    market_maker: String,
}

// ── Per-ticker book ──

struct TickerBook {
    symbol: String,
    bids: HashMap<i32, BookLevel>,  // position → level
    asks: HashMap<i32, BookLevel>,
    update_count: u64,
}

impl TickerBook {
    fn new(symbol: &str) -> Self {
        Self {
            symbol: symbol.into(),
            bids: HashMap::new(),
            asks: HashMap::new(),
            update_count: 0,
        }
    }

    fn apply(&mut self, position: i32, market_maker: &str, operation: i32, side: i32, price: f64, size: f64) {
        self.update_count += 1;
        let book = if side == 1 { &mut self.bids } else { &mut self.asks };
        match operation {
            0 | 1 => { book.insert(position, BookLevel { price, size, market_maker: market_maker.into() }); }
            2 => { book.remove(&position); }
            _ => {}
        }
    }

    fn print_summary(&self) {
        let mut bids: Vec<_> = self.bids.values().collect();
        let mut asks: Vec<_> = self.asks.values().collect();
        bids.sort_by(|a, b| b.price.partial_cmp(&a.price).unwrap());
        asks.sort_by(|a, b| a.price.partial_cmp(&b.price).unwrap());

        println!("\n── {} ── ({} updates)", self.symbol, self.update_count);
        println!("  Top 5 Asks:");
        for level in asks.iter().take(5).rev() {
            println!("    {:>10.2} x {:<10.0}  {}", level.price, level.size, level.market_maker);
        }
        println!("  ─────────────────────────────");
        println!("  Top 5 Bids:");
        for level in bids.iter().take(5) {
            println!("    {:>10.2} x {:<10.0}  {}", level.price, level.size, level.market_maker);
        }
    }
}

// ── Wrapper that collects depth for 2 tickers ──

struct DepthWrapper {
    books: HashMap<i64, TickerBook>,  // req_id → book
    errors: Vec<(i64, i64, String)>,
}

impl DepthWrapper {
    fn new(tickers: &[(i64, &str)]) -> Self {
        let mut books = HashMap::new();
        for &(req_id, symbol) in tickers {
            books.insert(req_id, TickerBook::new(symbol));
        }
        Self { books, errors: Vec::new() }
    }

    fn total_updates(&self) -> u64 {
        self.books.values().map(|b| b.update_count).sum()
    }
}

impl Wrapper for DepthWrapper {
    fn error(&mut self, req_id: i64, _error_time: i64, error_code: i64, error_string: &str, _: &str) {
        eprintln!("  error req_id={req_id} code={error_code} msg={error_string}");
        self.errors.push((req_id, error_code, error_string.into()));
    }

    fn update_mkt_depth(
        &mut self, req_id: i64, position: i32, operation: i32,
        side: i32, price: f64, size: ib_dx::api::Decimal,
    ) {
        if let Some(book) = self.books.get_mut(&req_id) {
            book.apply(position, "", operation, side, price, size.into());
        }
    }

    fn update_mkt_depth_l2(
        &mut self, req_id: i64, position: i32, market_maker: &str,
        operation: i32, side: i32, price: f64, size: ib_dx::api::Decimal, _is_smart_depth: bool,
    ) {
        if let Some(book) = self.books.get_mut(&req_id) {
            book.apply(position, market_maker, operation, side, price, size.into());
        }
    }
}

// ── Contracts ──

fn aapl() -> Contract {
    Contract {
        con_id: 265598,
        symbol: "AAPL".into(),
        sec_type: "STK".into(),
        exchange: "SMART".into(),
        currency: "USD".into(),
        ..Default::default()
    }
}

fn tsla() -> Contract {
    Contract {
        con_id: 76792991,
        symbol: "TSLA".into(),
        sec_type: "STK".into(),
        exchange: "SMART".into(),
        currency: "USD".into(),
        ..Default::default()
    }
}

fn main() {
    let username = env::var("IB_USERNAME").expect("IB_USERNAME required");
    let password = env::var("IB_PASSWORD").expect("IB_PASSWORD required");
    let host = env::var("IB_HOST").unwrap_or_default();
    let duration_secs: u64 = env::var("DURATION_SECS")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(15);

    println!("Connecting to {host}...");
    let client = EClient::connect(&EClientConfig {
        username,
        password,
        host,
        paper: true,
        ..Default::default()
    }).expect("Failed to connect");
    println!("Connected.");

    // Subscribe to L2 depth for both tickers (5 rows, SmartDepth)
    let num_rows = 5;
    let is_smart = true;

    let aapl_id: i64 = 1;
    let tsla_id: i64 = 2;

    println!("Subscribing AAPL (req_id={aapl_id})");
    client.req_mkt_depth(aapl_id, &aapl(), num_rows, is_smart);

    println!("Subscribing TSLA (req_id={tsla_id})");
    client.req_mkt_depth(tsla_id, &tsla(), num_rows, is_smart);

    // Poll for updates
    let mut wrapper = DepthWrapper::new(&[(aapl_id, "AAPL"), (tsla_id, "TSLA")]);
    let start = Instant::now();
    let timeout = Duration::from_secs(duration_secs);

    println!("Collecting depth data for {duration_secs}s...");
    while start.elapsed() < timeout {
        client.process_msgs(&mut wrapper);
        std::thread::sleep(Duration::from_millis(50));
    }

    // Print results
    for book in wrapper.books.values() {
        book.print_summary();
    }

    let total = wrapper.total_updates();
    println!("\nTotal depth updates: {total}");

    // Cancel subscriptions
    client.cancel_mkt_depth(aapl_id, is_smart);
    client.cancel_mkt_depth(tsla_id, is_smart);

    // Validate
    for (req_id, book) in &wrapper.books {
        assert!(
            book.update_count > 0,
            "No depth updates received for {} (req_id={})", book.symbol, req_id
        );
        assert!(
            !book.bids.is_empty() || !book.asks.is_empty(),
            "Empty book for {} (req_id={})", book.symbol, req_id
        );
        println!("✓ {} — {} updates, {} bid levels, {} ask levels",
            book.symbol, book.update_count, book.bids.len(), book.asks.len());
    }
    assert!(total > 0, "Expected depth updates but got none");
    println!("\nAll validations passed.");
}

Market Scanner

Run the TOP_PERC_GAIN scan over US major stocks, filtered to names above $5, and print the top ten.

What this shows

• req_scanner_subscription(req_id, instrument, location_code, scan_code, max_items, filters, scanner_setting_pairs), with scanner_setting_pairs "" when there are none.
• Filters as TagValue pairs. The tag names are the ones req_scanner_parameters publishes, for example priceAbove = "5" or stkTypes = "inc:ETF". They are carried to the venue, not dropped.
• Reading scanner_data rows, each a rank and a ContractDetails, until scanner_data_end.
• cancel_scanner_subscription(req_id) before disconnecting.

What comes back

One scanner_data callback per row, then scanner_data_end for the request id. Rows are ranked; the example sorts by rank before printing because it collects them into a Vec first.

A scanner subscription keeps answering until it is cancelled. The example cancels; if you leave one running it goes on delivering into a session nobody is reading.

The shorter form

scan runs the scan, waits, and withdraws the subscription before returning:

let rows = client.scan("STK", "STK.US.MAJOR", "TOP_PERC_GAIN", 25)?;

It sends no filters. Use req_scanner_subscription when the scan needs them.

Limits

Which scan codes and locations are valid is the venue's list. req_scanner_parameters fetches it, and an unknown code comes back as a stated refusal on the error callback. When the historical connection drops, a running scan is told 165 as it drops, at each attempt to bring it back that fails and once it is back, and is then subscribed again and goes on under its number, as a gateway does; a 165 ends nothing.

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_scanner

Source

//! Recipe: subscribe to TOP_PERC_GAIN scanner, print first 10 results.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_scanner

use std::env;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use ib_dx::api::client::{EClient, EClientConfig};
use ib_dx::api::types::{ContractDetails, TagValue};
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct State {
    rows: Vec<(i32, ContractDetails)>,
    end_seen: bool,
}

struct ScannerWrapper {
    state: Arc<Mutex<State>>,
}

impl Wrapper for ScannerWrapper {
    fn scanner_data(
        &mut self, _req_id: i64, rank: i32, details: &ContractDetails,
        _distance: &str, _benchmark: &str, _projection: &str, _legs: &str,
    ) {
        self.state.lock().unwrap().rows.push((rank, details.clone()));
    }
    fn scanner_data_end(&mut self, _req_id: i64) {
        self.state.lock().unwrap().end_seen = true;
    }
    fn error(&mut self, req_id: i64, _error_time: i64, code: i64, msg: &str, _adv: &str) {
        if !matches!(code, 2104 | 2106 | 2158) {
            eprintln!("[error] req_id={req_id} code={code} msg={msg}");
        }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let state = Arc::new(Mutex::new(State::default()));
    let mut wrapper = ScannerWrapper { state: state.clone() };

    let req_id = 1;
    println!("subscribing TOP_PERC_GAIN, STK.US.MAJOR…");
    let filters = [TagValue { tag: "priceAbove".into(), value: "5".into() }];
    client.req_scanner_subscription(req_id, "STK", "STK.US.MAJOR", "TOP_PERC_GAIN", 25, &filters, "");

    let deadline = Instant::now() + Duration::from_secs(30);
    while Instant::now() < deadline {
        client.process_msgs(&mut wrapper);
        if state.lock().unwrap().end_seen { break; }
        std::thread::sleep(Duration::from_millis(20));
    }

    let mut s = state.lock().unwrap();
    s.rows.sort_by_key(|(rank, _)| *rank);
    println!("results: {}", s.rows.len());
    for (rank, d) in s.rows.iter().take(10) {
        println!("  #{rank:<3}  {:<8} {:<6} con_id={}", d.contract.symbol, d.contract.primary_exchange, d.contract.con_id);
    }

    drop(s);
    client.cancel_scanner_subscription(req_id);
    client.disconnect();
    Ok(())
}

Request Account PnL

Subscribe to the account-level PnL stream, take the first update, cancel and disconnect.

What this shows

• Reading the account name off client.account_id, which connect populates.
• req_pnl(req_id, account, model_code).
• Reading daily_pnl, unrealized_pnl and realized_pnl off the pnl callback.
• cancel_pnl(req_id) before disconnecting.

account empty means the account this session opened under.

What comes back

The venue states what each holding was worth at midnight and what it has realised since. The three figures on the pnl callback are worked out from those against the prices this session is being told, so they move as the session's quotes move.

Limits

account is checked as a gateway checks it, in its order and words: a blank one is refused (Account must not be empty, 321); one the login does not hold is refused (Invalid account code, 321), and so is All on a login holding one account or where the logon says the login may not ask for every account; All on a login the venue adds accounts to is refused (This API request for All is not supported for Dynamic Account Addition, 321). Another account the login holds, and All where a gateway would take it, are refused too, on both clients: the figures are worked out from one account's midnight seeds and holdings, the one this session opened under. Nothing is subscribed for a refused request.

model_code is taken and not applied. There is no model portfolio to name here, so pass "".

cancel_pnl stops the updates. The venue has no message withdrawing the subscription itself, on a gateway as here, so the updates stopping is what the call does.

An account with no position reports zeros. Pair this with the limit-order recipe if you want to watch the numbers move.

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_pnl

Source

//! Recipe: subscribe to account-level PnL, take one update, then cancel.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_pnl

use std::env;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use ib_dx::api::client::{EClient, EClientConfig};
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct State {
    pnl: Option<(f64, f64, f64)>,
}

struct PnlWrapper {
    state: Arc<Mutex<State>>,
}

impl Wrapper for PnlWrapper {
    fn pnl(&mut self, _req_id: i64, daily: f64, unrealized: f64, realized: f64) {
        self.state.lock().unwrap().pnl = Some((daily, unrealized, realized));
    }
    fn error(&mut self, req_id: i64, _error_time: i64, code: i64, msg: &str, _adv: &str) {
        eprintln!("[error] req_id={req_id} code={code} msg={msg}");
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let account = client.account_id.clone();
    println!("account: {account}");

    let state = Arc::new(Mutex::new(State::default()));
    let mut wrapper = PnlWrapper { state: state.clone() };

    let req_id = 1;
    client.req_pnl(req_id, &account, "");

    let deadline = Instant::now() + Duration::from_secs(15);
    while Instant::now() < deadline {
        client.process_msgs(&mut wrapper);
        if state.lock().unwrap().pnl.is_some() { break; }
        std::thread::sleep(Duration::from_millis(20));
    }

    match state.lock().unwrap().pnl {
        Some((daily, unrealized, realized)) => {
            println!("daily={daily:.2}  unrealized={unrealized:.2}  realized={realized:.2}");
        }
        None => println!("no pnl update within 15s — try again with an open position"),
    }

    client.cancel_pnl(req_id);
    client.disconnect();
    Ok(())
}

Send a Limit Order

Place a BUY LMT on SPY far below market, watch it acknowledge, then cancel it. Connect, take an id, place, read status, cancel, disconnect.

What this shows

• client.next_order_id(), which reserves one id.
• An Order with order_type: "LMT" and lmt_price set. outside_rth: true is what lets it be acknowledged outside regular hours.
• order_status callbacks. PreSubmitted then Submitted while it rests, Cancelled once the cancel lands.
• cancel_order(order_id, order_cancel). The second argument is what the withdrawal states about itself: an OrderCancel (who is withdrawing it, whether a person entered it, a manual time), or a time alone; "" states nothing. The operator and who entered it travel on the cancel. A time does not, and the caller is told so on error; a time a gateway cannot read is refused under 10301 and the order keeps working.

What comes back

order_status on every change and again on each fill. filled and remaining are quantities, avg_fill_price is the average of what has filled so far. An order that rests will sit at Submitted until you cancel it.

The perm_id on that callback is the number the order goes to the venue under, as a gateway states it, which for this order is its own order id. It is stated from the moment the order is sent and stays the same for the life of the order, including across a modify.

Limits

next_order_id counts from one past the highest id the account is working an order under, which the venue names at every connect, from every session. So it does not collide with an order placed elsewhere.

tif is checked against what the venue carries: DAY, GTC, IOC, FOK, OPG, GTD, GTX, DTC, AUC, NMIN, spelled exactly. An unrecognised value is refused here rather than sent as DAY and quietly expiring at the close.

Paper account only. The price is set far below market so it will not fill.

The shorter form

place takes the id itself, sends the order, and waits up to five seconds for the venue to settle it:

let report = client.place(&spy, &order)?;
println!("{} {} filled", report.status, report.filled);

It reports what is known either way. An order still working is reported as working; it is not cancelled.

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_limit_order

Source

//! Recipe: place a non-marketable BUY LMT on SPY, watch Submitted, then cancel.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_limit_order

use std::env;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use ib_dx::api::client::{Contract, EClient, EClientConfig, Order};
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct State {
    statuses: Vec<(i64, String)>,
}

struct OrderWrapper {
    state: Arc<Mutex<State>>,
}

impl Wrapper for OrderWrapper {
    fn order_status(
        &mut self, order_id: i64, status: &str, _filled: ib_dx::api::Decimal, _remaining: ib_dx::api::Decimal,
        _avg_fill: f64, _perm_id: i64, _parent_id: i64, _last_fill: f64,
        _client_id: i64, _why_held: &str, _mkt_cap_price: f64,
    ) {
        println!("[status] oid={order_id} status={status}");
        self.state.lock().unwrap().statuses.push((order_id, status.into()));
    }
    fn error(&mut self, req_id: i64, _error_time: i64, code: i64, msg: &str, _adv: &str) {
        eprintln!("[error] req_id={req_id} code={code} msg={msg}");
    }
}

fn pump_until<F: Fn(&State) -> bool>(
    client: &EClient, wrapper: &mut OrderWrapper, state: &Arc<Mutex<State>>,
    timeout: Duration, done: F,
) -> bool {
    let deadline = Instant::now() + timeout;
    while Instant::now() < deadline {
        client.process_msgs(wrapper);
        if done(&state.lock().unwrap()) { return true; }
        std::thread::sleep(Duration::from_millis(20));
    }
    false
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let order_id = client.next_order_id();

    let state = Arc::new(Mutex::new(State::default()));
    let mut wrapper = OrderWrapper { state: state.clone() };

    let spy = Contract {
        con_id: 756733,
        symbol: "SPY".into(),
        sec_type: "STK".into(),
        exchange: "SMART".into(),
        currency: "USD".into(),
        ..Default::default()
    };
    let order = Order {
        action: "BUY".into(),
        total_quantity: 1.0,
        order_type: "LMT".into(),
        lmt_price: 1.00,
        tif: "DAY".into(),
        outside_rth: true,
        ..Default::default()
    };

    println!("placing BUY 1 SPY LMT 1.00 (oid={order_id})");
    client.place_order(order_id, &spy, &order);

    pump_until(&client, &mut wrapper, &state, Duration::from_secs(15),
               |s| s.statuses.iter().any(|(id, st)| *id == order_id && st == "Submitted"));

    println!("cancelling oid={order_id}");
    client.cancel_order(order_id, "");

    pump_until(&client, &mut wrapper, &state, Duration::from_secs(15),
               |s| s.statuses.iter().any(|(id, st)| *id == order_id && st == "Cancelled"));

    client.disconnect();
    Ok(())
}

Send a Stop Order

Place a BUY STOP on SPY far above market. The trigger never fires, so the order rests. Watch it acknowledge, then cancel it.

What this shows

• client.next_order_id(), which reserves one id.
• An Order with order_type: "STP" and the trigger price in aux_price. lmt_price is unused for a plain stop.
• tif: "GTC", so it survives the close rather than expiring with the day.
• order_status callbacks: PreSubmitted then Submitted while it rests, Cancelled once the cancel lands.
• cancel_order(order_id, "").

What comes back

The same order_status stream as any other order. A resting stop shows no fills: filled stays 0 and remaining stays at the full quantity until the trigger is touched.

Limits

A stop is held until its trigger is touched, then goes to the market as a market order. This example sets the trigger far above market so that never happens. On a real stop, the fill price is whatever the market gives you at that moment, not the trigger.

Paper account only.

Run it

IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_stop_order

Source

//! Recipe: place a BUY STP on SPY far above market, watch Submitted, then cancel.
//!
//! Usage: IB_USERNAME=... IB_PASSWORD=... cargo run --example hello_stop_order

use std::env;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};

use ib_dx::api::client::{Contract, EClient, EClientConfig, Order};
use ib_dx::api::wrapper::Wrapper;

#[derive(Default)]
struct State {
    statuses: Vec<(i64, String)>,
}

struct OrderWrapper {
    state: Arc<Mutex<State>>,
}

impl Wrapper for OrderWrapper {
    fn order_status(
        &mut self, order_id: i64, status: &str, _filled: ib_dx::api::Decimal, _remaining: ib_dx::api::Decimal,
        _avg_fill: f64, _perm_id: i64, _parent_id: i64, _last_fill: f64,
        _client_id: i64, _why_held: &str, _mkt_cap_price: f64,
    ) {
        println!("[status] oid={order_id} status={status}");
        self.state.lock().unwrap().statuses.push((order_id, status.into()));
    }
    fn error(&mut self, req_id: i64, _error_time: i64, code: i64, msg: &str, _adv: &str) {
        eprintln!("[error] req_id={req_id} code={code} msg={msg}");
    }
}

fn pump_until<F: Fn(&State) -> bool>(
    client: &EClient, wrapper: &mut OrderWrapper, state: &Arc<Mutex<State>>,
    timeout: Duration, done: F,
) -> bool {
    let deadline = Instant::now() + timeout;
    while Instant::now() < deadline {
        client.process_msgs(wrapper);
        if done(&state.lock().unwrap()) { return true; }
        std::thread::sleep(Duration::from_millis(20));
    }
    false
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = EClient::connect(&EClientConfig {
        username: env::var("IB_USERNAME")?,
        password: env::var("IB_PASSWORD")?,
        paper: true,
        ..Default::default()
    })?;

    let order_id = client.next_order_id();

    let state = Arc::new(Mutex::new(State::default()));
    let mut wrapper = OrderWrapper { state: state.clone() };

    let spy = Contract {
        con_id: 756733,
        symbol: "SPY".into(),
        sec_type: "STK".into(),
        exchange: "SMART".into(),
        currency: "USD".into(),
        ..Default::default()
    };
    let order = Order {
        action: "BUY".into(),
        total_quantity: 1.0,
        order_type: "STP".into(),
        aux_price: 9999.0,
        tif: "GTC".into(),
        outside_rth: true,
        ..Default::default()
    };

    println!("placing BUY 1 SPY STP 9999.00 (oid={order_id})");
    client.place_order(order_id, &spy, &order);

    pump_until(&client, &mut wrapper, &state, Duration::from_secs(15),
               |s| s.statuses.iter().any(|(id, st)| *id == order_id && st == "Submitted"));

    println!("cancelling oid={order_id}");
    client.cancel_order(order_id, "");

    pump_until(&client, &mut wrapper, &state, Duration::from_secs(15),
               |s| s.statuses.iter().any(|(id, st)| *id == order_id && st == "Cancelled"));

    client.disconnect();
    Ok(())
}

Python API

ib_dx.EClient / ib_dx.EWrapper is the TWS API shape: a request under an id, an answer later on a callback. The same EClient also carries the calls that answer and the calls beyond the documented API.

On EClient, EWrapper and the records a call or callback hands over, both naming conventions resolve: reqMktData and req_mkt_data, secType and sec_type, conId and con_id. dir() lists both, so an editor or a notebook completing from it offers either. The plain Python classes a program only builds — ExecutionFilter, ScannerSubscription, WshEventData, OrderCancel, RealTimeBar, ScanData, FamilyCode and HistoricalSession — carry the reference client's spelling alone, as that client's own do; the family codes and sessions a callback hands over answer to both.

A wrapper is called with the shape the ibapi release it was written for calls. error receives reqId, errorCode, errorString where it declares three parameters (ibapi 9.81), advancedOrderRejectJson after them where it declares four, and reqId, errorTime, errorCode, errorString, advancedOrderRejectJson, the current release's shape, otherwise. A wrapper whose class declares commissionReport, the name before the fees were reported beside the commission, and neither commissionAndFeesReport nor commission_and_fees_report, receives each charge on commissionReport. Both are read once, when EClient.__init__ binds the wrapper.

A new Order starts each figure the reference client's Order starts unset — the limit and auxiliary prices, the trailing percentage, the cash quantity, the trigger and adjusted prices, the filled quantity, the minimum quantity, the volatility and reference price kinds — at UNSET_DOUBLE or UNSET_INTEGER, as that client's does, so a program comparing with them reads what it would there, and the Rust Order starts them at the same values. A price left there is sent as none, as a gateway sends it; see a price the order does not state.

ib_dx.configure() carries what a gateway would hold in a configuration file: the session time zone, the build announced at logon, which executions arrive when a session opens, and the rest. ib_dx.describe() lists them, and ib_dx.UNAVAILABLE names the gateway settings that mean nothing without a local process — a port to listen on, the addresses allowed to reach it, how much heap the runtime may take — so a program being migrated finds an answer rather than silence.

Settings given to connect(settings=...) belong to that session; those given to configure() belong to the process and are what a session that states none falls back to. They are read when a session opens, so set them before connect().

order_id_file selects the durable counter shared by sessions with the same account and API client ID; an empty path disables it. See order IDs across sessions for its default location, reservations and moving the file.

Logging is settled at import: a process has one logger and importing ib_dx installs it, reading IB_DX_LOG_LEVEL (with or without a log directory; one that is not a level is said in the log), IB_DX_LOG_DIR and IB_DX_LOG_QUEUE. The level can be moved afterwards: configure(log_level=...) and connect(settings={"log_level": ...}) move the logger ib_dx installed, and raise where the program installed its own; configure(log_level=None) or "" moves it back to the level it was installed at. A connect refused for another of its settings leaves the level where it was. Where the logger writes and how much it buffers are fixed once it runs, so log_dir and log_queue belong in the environment before the import, and both ways in refuse them afterwards.

The reference

Below is generated by scripts/gen_api_docs.py from the same source the Rust surface is generated from. CI regenerates it on every push and fails if what is committed has drifted.

Python API Reference (v0.1.0)

Auto-generated from source — do not edit.

Table of Contents

• EClient: Connection
• EClient: Calls That Answer
• EClient: Account & Portfolio
• EClient: Orders
• EClient: Market Data
• EClient: Reference Data
• EClient: Gateway-Local & Stubs
• EWrapper Callbacks

Connection

__init__

Bind the wrapper the callbacks are delivered to. EClient(wrapper) lands here through the interpreter; a subclass with a constructor of its own calls EClient.__init__(self, wrapper), as the reference sample does with wrapper=self. Bound once: a second, different wrapper is refused, since callbacks may already be on their way to the first.

def __init__(wrapper)

connect

Connect to IB and start the engine. Live logins (paper=False) enter a second-factor approval window and block until the factor is approved (mobile push) or the deadline fires (ib_key_timeout_secs, default ~18 min). This is a human approval gate, not a hang. To bound or avoid it: use paper=True, pass a smaller ib_key_timeout_secs, or run connect() on a worker thread with your own timeout. Paper logins skip the gate entirely. Set RUST_LOG=info to see a log line when the wait begins. code_provider answers that factor with a typed code instead: code_provider(factor, display_id, avth_url) -> str, where factor is "ibkey" (return the code shown for display_id) or "authenticator" (return the account's current code; display_id and avth_url are empty). An authenticator account has no push to fall back to and cannot log in without this. It is called once, on a thread of its own, and holds the GIL while it runs — return the code, don't block on input. It is asked once and the login carries whatever it returns; what the venue does with a wrong code has not been exercised from here. Multiple EClient instances can run concurrently in one process; each owns its own state, sockets, and engine thread, and connect() does not serialize across instances. If you pin engines via core_id, give each a distinct value. port is kept and read back on port, as the reference client keeps it. The session connects to the venue directly, so there is no local socket for it to open.

def connect(host, port=0, client_id=0, username="", password="", paper=True, core_id=None, ib_key_timeout_secs=None, ib_key_token_sub_type=None, code_provider=None, readonly=False, settings=None, session_file=None, *, clientId=None)

disconnect

Disconnect from IB.

def disconnect()

is_connected

Whether there is a session to make requests on. False before connect and after disconnect, and false from the moment the engine gives the session up — which it writes down itself. True while a lost connection to the venue is being rebuilt, between the 1100 and the 1102, as a program connected to a gateway reads it: the gateway's socket stays up. The record saying so is delivered only by a read, and a program that drives its own loop, or none at all, is told nowhere else: it read connected on a session that was over, and went on issuing requests into it. The Rust surface answers this the same way.

def is_connected()

conn_state

Which of DISCONNECTED, CONNECTING and CONNECTED this client is in. CONNECTING is the span of connect, as read from another thread: the connection is claimed at the top of that call and the session's state handed over at the bottom, and is_connected reads true for the whole of it. A session that ended without being closed is connecting again from the moment connect is called on it, though what it held stays in place until the logon answers. A session the engine has given up is DISCONNECTED from the moment it writes that down, however the caller drives its loop — read from the cached flags alone it stayed CONNECTED for as long as the program went without dispatching.

client.conn_state  # read-only attribute

client_id

The number this session connected under, as the caller gave it, and None when there is no session.

client.client_id  # read-only attribute

host

The server this session connected to, and None when there is no session. The one it knocked on, which is the one the caller named — the venue may then send it elsewhere, and the rest of that list is where. The reference client holds what its caller passed here too.

client.host  # read-only attribute

port

The port connect was given, and None when there is no session. Kept as the caller gave it, as the reference client keeps it. This session speaks to the venue's servers on the ports the venue names, so the number opens nothing; a program that reads it back gets what it passed.

client.port  # read-only attribute

conn

The client itself while a session is held, and None without one. The reference client keeps its connection here, and what a program reads off it is isConnected(), host and port — which this client answers, following the session. Its socket is not here: this client's connections are opened, read and kept alive inside its engine.

client.conn  # read-only attribute

asynchronous

False: there is no asynchronous mode. The reference client sets this nowhere either; its sample program reads it in connect_ack to decide whether to start the exchange itself. Here connect returns with the session up and its engine running, and connect_ack is announced from inside it, so there is nothing left for a caller to start.

client.asynchronous  # read-only attribute

server_version

The protocol level this client implements: 217, the reference client's MIN_SERVER_VER_ADDITIONAL_ORDER_PARAMS_2. None before a session and after one, as the reference client answers before its greeting — and held while a lost connection is recovered, which the reference client rides out holding the number. In the reference architecture this number is the API level of the process a program is talking to. That process was a gateway, which announced it and had every request gated on it; here it is this client, so the number is a statement about this client and not a reading off the venue, whose logon names no such level. Attached orders (218) load the selected account preset and construct the parent and children. Percentage allocations still need positions by account and model and the applicable allocation-group state, so the level remains 217. A percentage allocation cannot yet determine the quantities of its attached children here; supply explicitly sized parent and child orders when those quantities depend on group or model holdings. Configuration requests (219, 221) and the last price and size stated to their precision (222, 224) are absent. hedgeMaxSize (223) is sent on a beta hedge, and odd-lot quotes (225) are served: generic tick 787 is asked for and its prices, sizes and venues delivered. conditionsIncludeOvernight (226) is sent with an order's conditions, and refused under 10371 when the order is placed where the logon does not enable it or the contract trades on no overnight venue. 226 is the highest level a gateway announces. Below it, a program that believes the number is wrong about the following, and each is said on use rather than passed over: * An order field this client does not carry, refused by name on error under 321 when the order is placed: smartComboRoutingParams (57). * A withdrawal stating a manual time (169): the withdrawal goes, with its operator and who entered it, and the caller is told on error that the time did not travel. Every other gate at or below 217 names a request, field or callback that is here and does what it does through a gateway.

def server_version()

tws_connection_time

When the venue says this session logged in, by its own clock and in its own spelling; None when there is no session, and held while a lost connection is recovered, as the level is. The reference client answers the time its gateway stamped on its greeting. The venue stamps every message it sends with the time it sent it, the answer to the logon included, and this is that stamp — the clock competing_session reads the other session's logon off. Where the venue stamped none, connect holds this machine's clock instead and says so in the log.

def tws_connection_time()

set_connect_options

The reference client carries these on its greeting to its gateway, which reads them; there is no gateway between this client and the venue to read them, so an option a caller states cannot be carried. Said rather than swallowed. Every one of these options changes how the session behaves — how fast it may ask, what it is told — and a caller who set one and heard nothing has a session that is not the one they asked for and no way to know it. Stating none is stating nothing, which is what the reference client's own is on an ordinary call.

def set_connect_options(opts)

set_optional_capabilities

The capabilities a program asks its gateway to switch on, which the reference client keeps and sends on its handshake. There is no gateway between this client and the venue to read them, so capabilities stated cannot be carried — answered as set_connect_options answers, and for the same reason said rather than swallowed.

def set_optional_capabilities(opt_capab)

validate_order_parameters

The parameter an order states that a session at the level this client answers cannot carry, named as the reference client names it, or None where the order states none. Its own check ported (ibapi/client.py:2819): a field counts as stated where it carries something — a flag set, an option present, a number off the unset value it is born with — and the gates are the levels the reference client gates them at: 216 for the first block of additional parameters, 217 for the second, 223 for hedgeMaxSize and 226 for conditionsIncludeOvernight. Before a session the level reads as nought, as it does there, and every gate asks.

def validate_order_parameters(order)

validate_attached_orders_parameters

The attached-order field a session below level 218 cannot carry, named as the reference client names it, or None. Its own check ported (ibapi/client.py:2853), read against the order's own fields: an id counts as stated when it is off the unset value it is born with and a type when it is not empty.

def validate_attached_orders_parameters(attached_orders)

validate_invalid_symbols

The reference client's own check (ibapi/client.py:352) of a string before it goes on the wire, as [host_carriable] runs it — and where it fails, said on error under 579 naming the string, rather than raised: this client states its refusals on the wrapper. The options that client checks beside the host are never kept here, so there is nothing else to check. connect runs it on the host and returns on the refusal, as the reference client's connect does.

def validate_invalid_symbols(host)

start_api

Nothing to start, once there is a session. The reference client sends its client id here and its gateway begins the exchange on receiving it. Here the id is kept on the client and never sent — one session holds the account — and connect announces connect_ack, the accounts and the next order id itself before it returns. Before a session exists this is reported the way the reference client reports it: on error, under 504.

def start_api()

check_connected

Raises when there is a session, with the words the reference client raises its own check under. Nothing otherwise.

def check_connected()

reset

Forget the session — which here is closing it. The reference client drops its hold on the socket and leaves the socket to its reader thread; a session here is an engine that stays logged in at the venue until it is stopped, so this is disconnect. Nothing to forget is fine.

def reset()

events_lost

How many engine events this session's channel discarded: none. This surface reads every engine callback through the session's one order, which keeps each record until a read delivers it, and attaches no event channel that could drop one.

def events_lost()

refuse

Put a refusal the program makes itself into the session's order. Delivered by a pass on error, or error_from, under the number origin names: after everything the session queued before this call and before everything after it, as a gateway's rejection arrives after everything the gateway wrote before it. Said at the call instead, it reaches the wrapper ahead of the refusals of requests made before it. origin is an ErrorOrigin, ErrorOrigin("Request", 7) for a request's number. With no session, or one that is over, there is no order to put it in and nothing is delivered.

def refuse(origin, code, msg)

poll

Deliver everything waiting, once, and return. run owns the thread it is called on, which a program with an event loop of its own cannot give it: an asyncio framework has to drive the callbacks from its own loop, and a blocking loop leaves it nowhere to stand. This is one pass of the same dispatch.

def poll()

run

Deliver callbacks until the session ends. Blocks the calling thread. Everything a program receives arrives from here, so it runs on a thread of its own or is the last call a program makes. poll does one pass instead, for a program that owns its loop.

def run()

wait_for_data

Wait for the engine to signal, for at most timeout seconds: True when it signalled, False when the wait ran out. The engine signals at the end of each pass of its loop, and when a connection goes or comes back. One waiter takes each signal. A thread that wakes a loop of its own waits here and then has that loop call poll: True is a reason to poll, not a promise that the poll delivers anything. Waits with the interpreter released, so other threads run meanwhile. Raises when there is no session.

def wait_for_data(timeout)

get_account_id

Get the account ID.

def get_account_id()

session_over

Whether this session is finished rather than merely disconnected: closed by disconnect(), or given up on by the engine. A loss the engine is still working on is neither — is_connected() reads true between the 1100 and the 1102, and a request made then is carried when the transports come back.

def session_over()

instrument_of

Which slot a contract holds on this session, if it holds one. Read through the lookup every other reader uses, which drops what the engine has given back, so a slot that has gone to the next contract is not named.

def instrument_of(con_id)

unread_wire

What the venue sent this session that nothing here reads, as pairs of the connection and what arrived: each kind of message named once, the first time it arrives. With IB_DX_CAPTURE_WIRE set, every frame is kept here as well, whole and as sent.

def unread_wire()

competing_session

Another session that already held this account when this one connected. None when this session is alone. Otherwise where the other one connected from, when it logged in, and whether this session is held to reading only because the other has the account. Worth asking before starting work: the venue permits one logon at a time and takes the account from the older session without saying which it dropped, so a second client reads as data that stops arriving.

def competing_session()

ccp_session_id

Session ID surfaced to webapp REST clients as x-ccp-session-id.

def ccp_session_id()

misc_url

Logical-name → host URL lookup from the MiscUrls block of the logon response (e.g. region_dam). None when the logon did not carry the key.

def misc_url(key)

Calls That Answer

contract_details

Everything the venue knows about the contracts matching a description. Sends the lookup, waits for the venue to say it has finished, and hands back every match. A description matching nothing returns an empty list; a venue that refuses the lookup raises with the reason it gave.

def contract_details(contract)

corporate_actions

A contract's corporate actions, asked for and waited on. One dict per action, stating what the venue stated: its kind as the two-letter name the venue uses, the day it takes effect, its value, and the dates and dividend descriptions the kind carries. A field the kind does not carry is empty rather than invented. contract must carry the venue's id for it. Days are YYYYMMDD.

def corporate_actions(contract, start_date, end_date)

historical_data

Bars for a contract over a period, handed back rather than delivered a bar at a time to a callback. The venue has no adjusted series to pass through: what it serves is raw bars, and the two series the vendor states as adjusted — TRADES and ADJUSTED_LAST — are those folded with the contract's own actions. For a stock or a fund, whatever the series, the actions are asked for first, as a gateway asks them, once a day for each contract, and their answer states the ids the contract traded under: the bars are asked one id at a time, the newest first, each for the days the contract traded as it — a week or a month split at every split as well, and its two parts joined into one bar — and joined into one series. The fold is made once the series is whole, before a bar is handed to anyone, with the actions dated up to the day it is made, that day on UTC's calendar included, as a gateway folds them: a series priced as the contract trades is put on the scale of its splits, stock dividends and spin-offs, and every series has the bars before a rights offer multiplied by the value it states. Any other kind of contract is asked as the request was made, and its bars handed back as the venue served them. ADJUSTED_LAST also has each cash dividend taken off the bars before it, as a gateway takes it off: the amount restated on the scale of the splits, spin-offs and rights offers listed after it, to four places, taken off the last bar before the one dated its day, and every bar before that one multiplied by what it took off that bar's close. This call waits and hands the series back in one piece; reqHistoricalData delivers the same bars one at a time on its callbacks. Both ask for the actions by the venue's id for the contract, which the venue is asked for first where the contract is named some other way.

def historical_data(contract, end_date_time, duration_str, bar_size_setting, what_to_show, use_rth=1)

head_timestamp

The earliest moment the venue holds data for a contract.

def head_timestamp(contract, what_to_show="TRADES", use_rth=1)

matching_symbols

Contracts whose symbol or name matches a pattern.

def matching_symbols(pattern)

news_headlines

The headlines the venue holds for a contract. Answers rather than reporting through the wrapper, because a program written against the reference client reads the return value.

def news_headlines(con_id, provider_codes, start_date_time, end_date_time, total_results)

trading_schedule

When a contract trades, over a stretch of days. Each session is its opening, its close, and the day it belongs to; the time zone they are stated in comes with them.

def trading_schedule(contract, end_date_time, duration_str, use_rth)

option_chains

Every venue's option chain for an underlying, returned rather than delivered on a callback: expiries and strikes, per venue and trading class.

def option_chains(underlying_symbol, fut_fop_exchange, underlying_sec_type, underlying_con_id)

histogram_data

How a contract's traded volume is spread across prices over a period.

def histogram_data(contract, use_rth=True, time_period="3 days")

fundamental_data

A fundamental report on a contract, as the venue supplies it.

def fundamental_data(contract, report_type)

positions

Every holding in the account: one tuple per holding, its account, its contract, the position and its average cost — what position states, handed back rather than delivered. Read once the account has finished stating its holdings, as req_positions reads them; where it had not within the wait, what this session already held is answered and the log says so. A holding named by id alone is given a moment for its definition to land, as there. Nothing is subscribed: asking again reads again.

def positions()

what_if_order

What the venue says an order would cost, without placing it: the order's own placement with the question marked on it, answered with the state the venue states for it. Numbered in the band these calls take, so the answer is this call's and the dispatch loop leaves it, with anything said about it. A placement this client refuses raises at once, with the refusal's words.

def what_if_order(contract, order)

scan

Run a scan and hand back what it found: one tuple per row, its rank and the contract's details, then the distance, benchmark and projection the venue states beside it, empty where it states none. The subscription is withdrawn before this returns: a scan asked for once is a question, and left running it keeps answering into a session nobody is reading. A scan the venue will not run raises with its words.

def scan(instrument, location_code, scan_code, most)

calendar_schema

What the corporate-events calendar says it carries, as the venue's JSON.

def calendar_schema()

calendar_events

The calendar's events for one contract, as the venue's JSON.

def calendar_events(con_id)

qualify_contract

Fill in what the venue knows about a contract, above all its id. Most of what this client sends carries a contract, and a contract with an id is worth more than one without: market data is answered only for a contract named by id, and an order carrying one needs to state nothing else. A description matching more than one contract is refused rather than resolved to whichever came back first — the same symbol on the same venue exists in more than one currency, and picking one silently is how an order reaches the wrong one.

def qualify_contract(contract)

qualify_contracts

Fill in a whole list of contracts, keeping their order. One that cannot be resolved fails the call rather than being dropped: a list quietly shorter than it was asked for is how a program trades something other than what it named.

def qualify_contracts(contracts)

Account & Portfolio

req_pnl

Subscribe to the named account's profit. The account is checked as a gateway checks it. Each request has its own subscription; a repeated active request number is refused under 102. A model is taken and not applied, with a log notice once per session.

def req_pnl(req_id, account, model_code="")

cancel_pnl

Cancel P&L subscription.

def cancel_pnl(req_id)

req_pnl_single

Subscribe to a position's profit in the named account. The account is checked as for the account-level profit. A model is taken and not applied, with a log notice once per session.

def req_pnl_single(req_id, account, model_code, con_id)

cancel_pnl_single

Cancel single-position P&L subscription.

def cancel_pnl_single(req_id)

req_account_summary

Request an account summary. All answers for every account the login holds. Account groups and AllNonProp are taken and not applied, with a log notice once per session. Validation and the limit of two standing summary requests follow a gateway.

def req_account_summary(req_id, group_name, tags)

cancel_account_summary

Cancel account summary.

def cancel_account_summary(req_id)

req_positions

Request all positions. Before a session exists this is reported on the error callback and the call returns, as every other request made before connecting is. A program written against the reference client has no exception handling around a request, because that client does not raise there. include_fx_positions (default true) controls CASH rows. send_zero_positions_for_todays_opening_only (default false) omits flat rows only when the venue states a zero opening quantity. A nonzero or unknown opening quantity still passes. Both settings apply to the initial answer and later updates; end callbacks still arrive.

def req_positions()

cancel_positions

Cancel positions.

def cancel_positions()

req_account_updates

Subscribe to the named account's figures and holdings, or withdraw the subscription. A single-account login ignores the name as a gateway does. Subscribing asks the venue to restate that account now; the engine holds the answer until its download ends or the existing wait expires. include_fx_positions (default true) controls CASH rows. send_zero_positions_for_todays_opening_only (default false) omits flat rows only when the venue states a zero opening quantity. A nonzero or unknown opening quantity still passes. Both settings apply to the initial answer and later updates; end callbacks still arrive.

def req_account_updates(subscribe, acct_code="")

req_managed_accts

Request managed accounts list. Answered with every account this login holds, comma separated, matching the reference client. Before a session exists there are no accounts to name, and an empty list reads as a login holding none rather than as a question asked too early.

def req_managed_accts()

req_account_updates_multi

Subscribe to the named account's figures under this request number. ledger_and_nlv selects the per-currency ledger and net liquidation. A model is taken and not applied, with a log notice once per session. The initial batch ends with account_update_multi_end; changes keep arriving until the request is cancelled.

def req_account_updates_multi(req_id, account, model_code, ledger_and_nlv=False)

cancel_account_updates_multi

Cancel multi-account updates. The request stops being reported to. The venue keeps the account current whether or not anyone is listening; what stops is the reporting — a figure that moves after this is no longer delivered on accountUpdateMulti for this request. A request the engine still holds is withdrawn, never answered; one it answered stops where the withdrawal stands, after its answer.

def cancel_account_updates_multi(req_id)

req_positions_multi

Subscribe to holdings of the named account under this request number. A model is taken and not applied, with a log notice once per session. include_fx_positions (default true) controls CASH rows. send_zero_positions_for_todays_opening_only (default false) omits flat rows only when the venue states a zero opening quantity. A nonzero or unknown opening quantity still passes. Both settings apply to the initial answer and later updates; end callbacks still arrive.

def req_positions_multi(req_id, account, model_code)

cancel_positions_multi

Cancel multi-account positions.

def cancel_positions_multi(req_id)

account_snapshot

Read account state snapshot. Returns a dict with all account values.

def account_snapshot()

positions_elsewhere

Holdings the venue reports that this broker does not hold itself: positions held away at another broker, and rows it marks as shown but not held. Kept apart from req_positions, which answers what the account itself holds. The reference client has no call for these — its own front end shows them in a separate table — so this is the only way to reach them. One dict per holding: con_id, symbol, sec_type, currency, position, avg_cost, and held, which is "Away" for a position held at another broker, "DisplayOnly" for a row shown but not held, and "Aside" for one reported apart without saying why. Empty with no session.

def positions_elsewhere()

values_elsewhere

The account figures describing one of the sets of holdings the account does not hold itself, as name, value and the currency each is stated in. A figure stated in two currencies is two figures. held names the set as positions_elsewhere does: "Away", "DisplayOnly" or "Aside". The venue states these the same way it states the account's own, and mixing them in would overstate what the account is worth, so they are kept where the holdings they describe are kept. Empty with no session.

def values_elsewhere(held)

Orders

place_order

Place an order. A request the client will not send is reported under the number the reference client reports it under, and the call returns. A program moved from that client has an error handler and no exception handling around a request, because nothing it was written against raises there. A send the engine can no longer take is reported the same way, stating what has already reached the engine and what has not. slOrderId / slOrderType and ptOrderId / ptOrderType construct children from the selected account preset. State each child id with PRESET (case-insensitive). Preset loading and any quote wait run in the engine; the call returns without waiting. The parent goes first, then stop loss and profit taker. transmit=False holds the family until a parent or child transmits it. Replacing the parent preserves its existing children. Percentage-allocation sizing from group or model holdings is not carried; use explicitly sized parent and child orders where their quantities depend on it.

def place_order(order_id, contract, order)

exercise_options

Exercise or lapse a long option position.

def exercise_options(req_id, contract, exercise_action, exercise_quantity, account, override, manual_order_time, customer_account, professional_customer)

cancel_order

Cancel an order. The second argument is what the reference client states about the withdrawal itself — when a person entered it, on whose authority, and whether a person entered it at all. It is taken as that object or as the time alone. Who is withdrawing it and whether a person entered it travel on the cancel, as a gateway writes them: from the withdrawal, not from the placement. A time does not travel. A gateway sends it only where the venue has turned that record on for the login, and this client does not read whether it has. The cancel goes anyway and the caller is told the time did not: refused outright, a live order would be left standing over a record this client does not send. Taken silently it would be withdrawn without the record while the caller had given one, so it is said. A time a gateway cannot read is refused as a gateway refuses it, under 10301, and nothing is withdrawn. Nothing is said as the cancel goes out, as a gateway says nothing then: asked for, the order reads PendingCancel, and the venue's next report on it states it.

def cancel_order(order_id, order_cancel=None)

req_global_cancel

Cancel every order the account is working. This wire carries no request to withdraw everything, so it is composed here: one cancel for each order held, which is what a caller asking for everything back is asking for. What is held is what the venue named as working at connect and what this session placed since. The venue names the former after the connect returns, so a global cancel issued straight away waits for that naming, as asking for the open orders does, and covers what was named. Where the naming does not finish within the wait, what had been named is still withdrawn and the call says so rather than returning as though every order were covered: a partial cancel that reads as one beats the same cancel in silence, which reads as a complete answer. What the withdrawal states — who is withdrawing and whether a person entered it — travels on every cancel, as a gateway states it on every order it withdraws. A time does not: the reference client writes none on a withdrawal of everything, so a gateway never reads one, and one stated here goes the same way.

def req_global_cancel(order_cancel=None)

req_ids

Request next valid order ID. num_ids has no effect, as on a gateway: the next valid id is answered whatever number is asked for. Before a session exists there is no counter to answer from: the id an account may next use is the venue's to state. Answering announces zero, which names no order the venue will hold and is refused on placement. Reported the way the reference client reports every request made before connecting.

def req_ids(num_ids=1)

next_order_id

Reserve the next order ID above the saved counter and venue replay. The account and API client's counter is written under an exclusive lock before returning. A storage failure warns once in the log and leaves allocation using session memory and venue replay.

def next_order_id()

next_shared_id

The first id past everything the account has used that a request can also carry. A caller that numbers its orders and its requests out of one counter — which is how ib_async is written — needs both at once: clear of every id an order has spent, and inside the numbers a request can carry. An account that has been given a wider order id than that has no such number above it, so this answers with one past the widest the account has used that a request can carry, and the counting goes on from there. After a connect it waits, for at most three seconds in all, for the venue to name the orders the account is working. Raises RuntimeError where even that is not a number a request can carry. Answers 1 where there is no session.

def next_shared_id()

req_open_orders

Request the open orders of this client. The answer is this client's own orders alone, as a gateway narrows it. An order the venue states held is among them only where this session placed it: a gateway holds an order it sent working whatever the venue states of it later, and leaves out one it first learns of held.

def req_open_orders()

req_all_open_orders

Request all open orders across all clients. Every client's orders on the account, where req_open_orders answers with this client's own, as a gateway narrows that one.

def req_all_open_orders()

req_auto_open_orders

Binding orders entered elsewhere to this client. For client 0, b_auto_bind turns binding on or off, as on a gateway: while it is on, each order placed elsewhere that the venue states after it has named what was already working is bound to client 0, under the next negative number, or the next order id where use_negative_auto_range is off. Turning it off keeps the numbers already given. The venue is asked to bind each one, and order_bound follows when it accepts. Any other client is refused, as a gateway refuses a client other than 0: asked to bind, with 321, as a request that fails validation; asked not to, with 327.

def req_auto_open_orders(b_auto_bind)

req_executions

Request execution reports. Before a session exists this is reported on the error callback, as every other request made before connecting is. Answered instead, the answer waits for a dispatch pass no session is there to make, and the caller hears nothing at all. lastNDays and specificDates select days as a gateway selects them, counted on the session's time zone. A date that does not read as a number, or is not a day of the calendar, is refused under 320, as a gateway refuses it. The executions answered from reach back to midnight six days before the logon in UTC, or to the logon's own day for a session set to today's executions, so the earliest days asked for can be missing some; those days are named on error under 321 ahead of the answer, which still comes. acctCode is ignored on a login holding one account and refused on one holding several where the login does not hold it, as a gateway does both.

def req_executions(req_id, exec_filter=None)

req_completed_orders

Request completed orders. api_only asks for the orders entered through an API rather than by hand. The venue states no origin beside a finished order, and it does number the ones an API placed: an order that went out through one carries the number that API gave it, and one typed in carries none. So true is answered with the orders the venue numbered.

def req_completed_orders(api_only=False)

Market Data

set_news_providers

Set news provider codes for per-contract news ticks (e.g. "BRFG*BRFUPDN").

def set_news_providers(providers)

req_mkt_data

Request market data for a contract. With snapshot, tickSnapshotEnd follows once the snapshot is whole, as a gateway ends one: when the venue has stated the bid, the ask, the last, the open and the close; on a contract of a type a gateway marks as an option (OPT, FOP, IOPT, WAR, EC) also the option model, 13 (83 delayed); on a delayed feed also the last trade's time, 88; or eleven seconds after the request. Ticks 10, 11 and 12 (80, 81 and 82 delayed), the bid's, the ask's and the last's option computations, are not stated by the venue: a gateway works them out with an option model of its own, and so does this client, for an option on a share once its inputs are in hand. A gateway's snapshot of an option also waits for them; this client's does not. mkt_data_options is checked as a gateway checks it: manual, 0 or 1, is taken and changes nothing a gateway sends; any other key is refused under 10337, another value under 10338, and an entry not written key=value under 320. Where the venue has lifted the key checks, a manual that does not read as the number nought or one is refused under 321.

def req_mkt_data(req_id, contract, generic_tick_list="", snapshot=False, regulatory_snapshot=False, mkt_data_options=None)

req_mkt_data_ex

Like req_mkt_data, but names the market-data mode on the request itself (0=realtime, 1=delayed, 2=frozen, 3=delayed-frozen) rather than taking the one the session is set to. The frozen one keeps thinly-traded names quoting after hours, when the realtime feed is silent. A contract holds one subscription at a time, so this states the mode for that subscription rather than adding a second alongside it: a later request for a contract already subscribed follows the one that is up and is handed its quotes. To compare two modes on one contract, withdraw between them. regulatory_snapshot asks for the venue's own chargeable one-shot snapshot: a request type of its own rather than a mode on an ordinary quote. It needs the entitlement, and an account without it is refused by the venue, which names the request type back through error. It ends the way an ordinary snapshot does, so tickSnapshotEnd fires either way.

def req_mkt_data_ex(req_id, contract, generic_tick_list="", snapshot=False, regulatory_snapshot=False, mode_9887=0, mkt_data_options=None)

cancel_mkt_data

Cancel market data. A number a gateway cannot read, past four bytes signed, is refused under -1 with 320, as a gateway refuses it, and withdraws nothing.

def cancel_mkt_data(req_id)

req_tick_by_tick_data

Request tick-by-tick data. number_of_ticks and ignore_size are sent as stated: a count of past ticks goes out as the length of the run the stream opens with, and the size filter as the query's filter term. Neither goes out at its default — no prelude, sizes included — which is what the venue does on its own. Whether the venue honours the size filter is the venue's, and what it sends is passed on as it stands, as a gateway passes it: one session saw size-only changes still arrive on a stream that asked to leave them out.

def req_tick_by_tick_data(req_id, contract, tick_type, number_of_ticks=0, ignore_size=False)

cancel_tick_by_tick_data

Cancel tick-by-tick data.

def cancel_tick_by_tick_data(req_id)

req_ping

Request an auth-connection round-trip time sample: sends a lightweight liveness probe with no side effects on subscriptions, contract caches, or pacing budgets. Poll last_rtt_ms() after a moment for the result.

def req_ping()

last_rtt_ms

Last measured auth-connection round-trip time in milliseconds, or None if never measured. A gauge, not a benchmark req_ping. Also sampled automatically by the engine's own liveness probes.

def last_rtt_ms()

req_market_data_type

Name the feeds every subscription after this one may be served: 1 live, 2 frozen, 3 delayed, 4 delayed-frozen. A type turns feeds on, as a gateway takes it: 2 turns frozen data on; 3 and 4 turn delayed data on, 4 with delayed-frozen and 3 without; only 1 turns frozen data off, and it turns all three off. A subscription starts live whatever the type, falls back to delayed data on a refusal where delayed data is on, and is served the frozen or delayed-frozen quote while the market is closed, where the logon enables frozen data; the market_data_type callback reports the type served. A number naming no type is refused under -1 with 321, Invalid market data type, as a gateway refuses it, and leaves the feeds as they were. req_mkt_data_ex names a feed per request, which allows two feeds on one contract at once.

def req_market_data_type(market_data_type)

req_mkt_depth

Request market depth (L2 order book). mkt_depth_options is checked as a gateway checks it: manual, 0 or 1, is taken and changes nothing a gateway sends; any other key is refused under 10337, another value under 10338, and an entry not written key=value under 320. Where the venue has lifted the key checks, a manual that does not read as the number nought or one is refused under 321.

def req_mkt_depth(req_id, contract, num_rows=5, is_smart_depth=False, mkt_depth_options=None)

cancel_mkt_depth

Cancel market depth. is_smart_depth names which of the two books under the number is withdrawn — the smart one or the regular one — as it does for a gateway: the two are held apart, both run, and the withdrawal takes the book of the mode it names. A mode no book was asked in is refused under 310 rather than answered with the other mode's book.

def cancel_mkt_depth(req_id, is_smart_depth=False)

req_real_time_bars

Request real-time 5-second bars. bar_size has no effect, as on a gateway: a real-time bar is five seconds, and the venue's request carries no bar size. A gateway reads the number and does not use it. Requests for the same bars of one contract — this call's, or the stream a historical request kept up to date rides — read one stream, as on a gateway: the venue serves it under one number, each request is handed every bar under its own id, and a cancel withdraws its own request alone. The stream is withdrawn when the last of them leaves. real_time_bars_options is checked as a gateway checks it: manual, 0 or 1, is taken and changes nothing a gateway sends; any other key is refused under 10337, another value under 10338, and an entry not written key=value under 320. Where the venue has lifted the key checks, a manual that does not read as the number nought or one is refused under 321.

def req_real_time_bars(req_id, contract, bar_size=5, what_to_show="TRADES", use_rth=0, real_time_bars_options=None)

cancel_real_time_bars

Cancel real-time bars.

def cancel_real_time_bars(req_id)

quote

Zero-copy SeqLock quote read by req_id. Returns a dict with bid, ask, last, bid_size, ask_size, last_size, volume, high, low, open, close, or None if the req_id is not mapped.

def quote(req_id)

quote_by_instrument

Zero-copy SeqLock quote read by InstrumentId. Returns a dict with bid, ask, last, bid_size, ask_size, last_size, volume, high, low, open, close, and whether the venue has halted the contract and why — or None if not connected, or for an id past every slot the instrument table holds. Whether it is restricting short sales in it is shortSaleRestrictedByInstrument, which is stated on the same record and kept off this one.

def quote_by_instrument(instrument)

option_model

What the venue's own model last made of an option, whole. tickOptionComputation carries its greeks and its price, beside the volatility and the underlying's price a gateway takes from the venue's other series. The venue states eighteen figures on this record, and every one is in this dict, its own volatility and underlying price among them. A figure the venue did not state is this API's own unset double; zero is a real greek. None where the request names no subscription, or the venue has not stated a model for it yet.

def option_model(req_id)

short_sale_restricted

Whether the venue is restricting short sales in the contract a request is watching. The circuit breaker a venue puts on a contract that has fallen far enough in a day, which stops a short from resting below the bid. Stated on the same record as the halt, and with no field anywhere in the documented API. Not the same question as whether the contract can be borrowed, which ticks 46 and 89 already answer beside it.

def short_sale_restricted(req_id)

short_sale_restricted_by_instrument

The same, by InstrumentId, for callers who track them themselves.

def short_sale_restricted_by_instrument(instrument)

contract_figures

What the venue says about the contract itself, beside its prices: how many shares are on issue, and what it opened at a year ago. Both arrive on the tick carrying the price extremes and neither has a tick of its own in the documented API — a share count is a fundamentals request there, and a year-ago open has no call at all.

def contract_figures(req_id)

contract_figures_by_instrument

The same, by InstrumentId, for callers who track them themselves.

def contract_figures_by_instrument(instrument)

stated_figures

What one of the venue's own series last stated for a subscription, in the order the series states it. The venue runs dozens of series the documented API has no call for: a bond's analytics, an option's model volatility, the volume a contract usually opens on, what margin a future takes. Ask for one by its own number in the generic tick list, and read what it stated here. A figure the venue holds nothing for comes as the largest number its field carries.

def stated_figures(req_id, series)

numbered_figures

What one of the venue's numbered-table series last stated for a subscription: its figures under the venue's own numbering. Four series state their figures as two tables, whole numbers and fractional ones, each entry naming what it is before stating it. fractional picks the table; the venue numbers the two separately, so the same number in each is not the same figure.

def numbered_figures(req_id, series, fractional=False)

paired_figures

The run of paired figures one series last stated for a subscription. Two series state their figures as a count and then that many pairs: the volatility the venue's own model puts on each point of a curve, and the weight it puts on each price a contract might reach.

def paired_figures(req_id, series)

req_spread_scan

Ask the venue to scan an underlying for strategies worth putting on. The scan goes out beside a subscription for the series the venue states its answer on, because that is how it is asked for: the series carries the answer and the scan tells the venue what to look for. Read the answer with scanned_strategies under the same request, and withdraw it with cancel_mkt_data. The documented API has no call for this at all. What the scan states about each strategy is the venue's own, in the venue's own words, and nothing here translates them.

def req_spread_scan(req_id, contract, scan)

scanned_strategies

The strategies a spread scan stated for a request, as the venue stated them. Each is a dict of its legs, which shape of strategy it is and how pressing, the thirteen figures the venue states about it, where it comes out even, and one figure behind those. Empty until a scan has been asked for and answered. The documented API has no call for this.

def scanned_strategies(req_id)

stated_rows

The rows of three figures one series last stated for a subscription. What the three are is the series' own: | Series | The three figures | | --- | --- | | 547 | A quantity, what it is offered at, and a second price where the form states one | | 491 | Which strategy the leg belongs to, the contract it names, and its size | | 320, 376, 530, 532 | The venue's number for a field of a packed quote, its figure, and how far that figure's decimal point moves | On the packed quotes the venue numbers its fields itself: nought and one are the two sides of the quote and four and five the size behind each, read off a live session. A side the venue is not standing behind reads as minus one hundred. Those figures are counted in the contract's own increments, as every packed figure is — 75815 against an increment of a hundredth is 758.15 — and no scale is put on them here, because which fields are prices and which are counts is the venue's to change. f64::MAX stands where a form states no third figure. The documented API has no call for any of these.

def stated_rows(req_id, series)

chain_model_parameters

What one of the option model's chain series last stated for a subscription on an underlying. A list with one dict per class of the underlying's options: the underlying's price, the dividends expected, and per expiry the yield, the interest rate, the forward and the at-the-money volatilities the model works from. Ask for series 687 for the standing set, or 691 for the set as the chain closed, in the generic tick list of a subscription on the underlying. The documented API has no call for either: a gateway reads them for its own option model and hands none of it on. Empty where the request names no subscription, or the series has stated nothing for it.

def chain_model_parameters(req_id, series)

stated_rows_series

Which series have stated rows for a subscription, in order.

def stated_rows_series(req_id)

paired_figures_series

Which series have stated paired figures for a subscription, in order.

def paired_figures_series(req_id)

numbered_figures_series

Which series have stated numbered figures for a subscription, in order.

def numbered_figures_series(req_id)

stated_figures_series

Which series have stated figures for a subscription, in order.

def stated_figures_series(req_id)

closing_option_model

What the venue's model made of an option as it closed. The same model as option_model and in the same shape — every greek it states, the ones the documented API has no field for included — but worked out as the contract closed rather than as it stands. The documented API has no call for it at all. Ask for it by the venue's own number for the series in the generic tick list.

def closing_option_model(req_id)

closing_option_model_by_instrument

The same, by InstrumentId, for callers who track them themselves.

def closing_option_model_by_instrument(instrument)

option_model_by_instrument

The same, by InstrumentId, for callers who track them themselves.

def option_model_by_instrument(instrument)

Reference Data

req_historical_data

Request historical bar data. chart_options is checked as a gateway checks it: manual, 0 or 1, is taken and changes nothing a gateway sends; any other key is refused under 10337, another value under 10338, and an entry not written key=value under 320. Where the venue has lifted the key checks, a manual that does not read as the number nought or one is refused under 321.

def req_historical_data(req_id, contract, end_date_time, duration_str, bar_size_setting, what_to_show, use_rth, format_date=1, keep_up_to_date=False, chart_options=None)

cancel_historical_data

Cancel historical data.

def cancel_historical_data(req_id)

req_head_time_stamp

Request head timestamp.

def req_head_time_stamp(req_id, contract, what_to_show, use_rth, format_date=1)

cancel_head_time_stamp

Cancel head timestamp request.

def cancel_head_time_stamp(req_id)

req_contract_details

Request contract details.

def req_contract_details(req_id, contract)

cancel_contract_data

Withdraw a contract lookup. Nothing is sent and nothing answers: there is nothing to withdraw. A gateway asks the venue nothing for this either: it only stops re-sending a lookup it held back while its connection to the venue was down, and this client holds none back — a lookup made with no connection is refused there and then. A lookup already asked for is still answered, as it is through a gateway.

def cancel_contract_data(req_id)

req_mkt_depth_exchanges

Request available exchanges for market depth.

def req_mkt_depth_exchanges()

req_matching_symbols

Search for matching symbols.

def req_matching_symbols(req_id, pattern)

req_sec_def_opt_params

Request option chain parameters. Every argument is stated by the caller, as the reference client requires them to be. With underlying_sec_type defaulted to stocks, a caller who left it off asked about the chains of a stock by that name rather than being told they had left it off.

def req_sec_def_opt_params(req_id, underlying_symbol, fut_fop_exchange, underlying_sec_type, underlying_con_id)

req_scanner_subscription

Request scanner subscription. scanner_subscription_options is checked as a gateway checks it: manual, 0 or 1, is taken and changes nothing a gateway sends; any other key is refused under 10337, another value under 10338, and an entry not written key=value under 320. Where the venue has lifted the key checks, a manual that does not read as the number nought or one is refused under 321.

def req_scanner_subscription(req_id, subscription, scanner_subscription_options=None, scanner_subscription_filter_options=None)

cancel_scanner_subscription

Cancel scanner subscription.

def cancel_scanner_subscription(req_id)

req_scanner_parameters

Request scanner parameters XML.

def req_scanner_parameters()

req_news_article

Request a news article. news_article_options is checked as a gateway checks it: manual, 0 or 1, is taken and changes nothing a gateway sends; any other key is refused under 10337, another value under 10338, and an entry not written key=value under 320. Where the venue has lifted the key checks, a manual that does not read as the number nought or one is refused under 321.

def req_news_article(req_id, provider_code, article_id, news_article_options=None)

req_historical_news

Request historical news. A nonempty start requests newer headlines from that bound; otherwise the end requests older headlines. The selected bound is sent as stated, without parsing it locally. When both are empty, the request asks for the latest headlines. historical_news_options is checked as a gateway checks it: manual, 0 or 1, is taken and changes nothing a gateway sends; any other key is refused under 10337, another value under 10338, and an entry not written key=value under 320. Where the venue has lifted the key checks, a manual that does not read as the number nought or one is refused under 321.

def req_historical_news(req_id, con_id, provider_codes, start_date_time, end_date_time, total_results, historical_news_options=None)

cancel_historical_news

Withdraw a historical news query. The TWS API has no call for this; the venue has a message for it. One message carrying the number the query went out under, sent for a query still waiting on its answer. Nothing of a query is kept once it is answered, as a gateway keeps nothing of one: withdrawn after its answer, it is refused as naming nothing.

def cancel_historical_news(req_id)

req_adjustments

Ask for a contract's corporate actions over a range of days. No callback carries the answer; a refusal arrives on error under this id, as any request's does, and gives the request up: nothing is held for it after, and there is nothing to withdraw. The answer is held under the id until adjustments_for takes it or cancel_adjustments gives it up, so a request that is neither taken nor withdrawn holds its answer for the rest of the session. corporate_actions asks and waits in one call; this is the request on its own.

def req_adjustments(req_id, con_id, sec_type, exchange, start_date, end_date)

adjustments_for

The corporate actions answering a req_adjustments under this id, once they have arrived: one dict per action, as corporate_actions states them. Taken rather than read: the answer is handed over once and the request holds nothing after it. None until the answer arrives, and for a request this session is not holding one for. A contract the venue states nothing for answers with an empty list, which is an answer.

def adjustments_for(req_id)

cancel_adjustments

Give up on a req_adjustments: whatever it holds is let go of, and the venue is told to stop serving the query. For a request whose answer has not come and is no longer wanted: the venue serves the query until it is withdrawn. A withdrawal naming no query this client is waiting on, one already answered included, is reported on error under 300.

def cancel_adjustments(req_id)

req_fundamental_data

Request fundamental data. The report is asked about the stock the venue's id names: a contract given by its description is looked up first, as a gateway looks it up. A contract not stated as a stock is refused, as a gateway refuses it. fundamental_data_options is taken and nothing in it is checked or applied, as through a gateway: a gateway reads no option list on this request.

def req_fundamental_data(req_id, contract, report_type, fundamental_data_options=None)

cancel_fundamental_data

Cancel fundamental data.

def cancel_fundamental_data(req_id)

req_historical_ticks

Request historical tick data. ignore_size asks the venue to leave out a bid/ask change that moves only a size, and what it answers is passed on as it stands, as a gateway passes it: nothing is filtered here. A gateway asks for midpoint ticks that way whatever the caller asked, and so does this client; for trades it is not asked. One session saw the venue answer the same with the filter as without it. misc_options is checked as a gateway checks it: manual, 0 or 1, is taken and changes nothing a gateway sends; any other key is refused under 10337, another value under 10338, and an entry not written key=value under 320. Where the venue has lifted the key checks, a manual that does not read as the number nought or one is refused under 321.

def req_historical_ticks(req_id, contract, start_date_time="", end_date_time="", number_of_ticks=1000, what_to_show="TRADES", use_rth=1, ignore_size=False, misc_options=None)

cancel_historical_ticks

Withdraw a historical ticks request. Nothing is sent and nothing answers: there is nothing to withdraw, as for cancel_contract_data. A gateway only stops re-sending a request it held back while its connection to the venue was down, which this client never does. Ticks already asked for still arrive, and a request waiting for its contract to be named still goes once it is, as through a gateway.

def cancel_historical_ticks(req_id)

req_market_rule

Request market rule details.

def req_market_rule(market_rule_id)

req_histogram_data

Request histogram data.

def req_histogram_data(req_id, contract, use_rth, time_period)

cancel_histogram_data

Cancel histogram data.

def cancel_histogram_data(req_id)

req_historical_schedule

Request historical trading schedule.

def req_historical_schedule(req_id, contract, end_date_time="", duration_str="1 M", use_rth=True)

Gateway-Local & Stubs

req_config_proto_buf

Request configuration. Reports 10357 on the request's error callback.

def req_config_proto_buf(config_request_proto)

update_config_proto_buf

Request a configuration update. Reports 10357 on the request's error callback.

def update_config_proto_buf(update_config_request_proto)

order_permissions

Security type → the order types the venue permits for it, as stated at logon. Empty until the session is up.

def order_permissions()

permitted_order_types

The order types permitted for one security type, or None when the type is not permitted at all. A combination is named COMB.

def permitted_order_types(sec_type)

enabled_features

Feature tokens the venue enables for this account.

def enabled_features()

algorithms

Which algorithms the venue offers, keyed PROVIDER/SECTYPE.

def algorithms()

algorithms_for

The algorithms offered for one security type, across every provider.

def algorithms_for(sec_type)

order_presets

The sets of order defaults this account holds, as (key, attributes, when it last changed). The venue keeps one per security type and fills parts of an order the caller left unstated from them, so the same call on two accounts is not the same order. The key is the venue's own. The attributes are as the venue writes them, & between them: v= names the set's variant and a=1 marks it active. The values in a set are asked for separately. The moment says when a set last changed, which is what tells a caller whether an order it sent at a given time was filled in from the old defaults or the new. Empty where the venue stated none.

def order_presets()

company_data

What the venue states about a contract's company or its terms on one series, as the pairs it wrote. Ask for the series on the market data request by the venue's own number for it. Seventeen of them carry this text: 386 is what the company has coming and when; 434 and 548 are the two analyst ratings; 454 is how much of the company institutions and insiders hold, on what date each was counted, and how many shares are on issue, from which a float is worked out rather than stated; 505 is what a fund will take part in; 628 and 633 are a fund family's figures and the same by financial year; 631 the technical readings taken on the contract; 669 the ratios the venue keeps a history of; 678 and 699 two scores worked out from what is written about the company; 700 and 705 how it scores against the principles an account can screen on; 703 what margin dealing in it takes; 726 the lens the venue publishes over its accounts; 750 the price the venue holds it against for reference; and 752 whether it passes a religious screen. The keys are the venue's own, unchanged.

def company_data(con_id, series)

company_data_series

Which of those series have been stated for a contract.

def company_data_series(con_id)

calculate_implied_volatility

What volatility a price implies for an option, under the model the venue publishes for that contract. Answered on tick_option_computation. implied_vol_options is checked as a gateway checks it: this request takes no key, so any is refused under 10337, and an entry not written key=value under 320. Where the venue has lifted the key checks, a list that reads is taken. Nothing in it is sent: this client answers the calculation itself, from the venue's model.

def calculate_implied_volatility(req_id, contract, option_price, under_price, implied_vol_options=None)

calculate_option_price

What an option is worth at a stated volatility, under the same model. Answered on tick_option_computation. opt_prc_options is checked as a gateway checks it: this request takes no key, so any is refused under 10337, and an entry not written key=value under 320. Where the venue has lifted the key checks, a list that reads is taken. Nothing in it is sent: this client answers the calculation itself, from the venue's model.

def calculate_option_price(req_id, contract, volatility, under_price, opt_prc_options=None)

cancel_calculate_implied_volatility

Stop waiting on an implied-volatility request. A question answered in the call it was asked in leaves nothing to withdraw. One that opened a watch is holding a subscription the caller never asked for by name, and this is what releases it.

def cancel_calculate_implied_volatility(req_id)

cancel_calculate_option_price

As for cancel_calculate_implied_volatility.

def cancel_calculate_option_price(req_id)

req_news_bulletins

Ask for the notices the venue broadcasts to everyone. Answered on update_news_bulletin. all_msgs asks for the day's bulletins as well as the ones still to come. Nothing is sent to the venue: it broadcasts these unasked and has been doing so since the session opened, so the day's are answered from what is cached — without consuming it: the cache is the day's, a gateway clears it only at day rollover, and asking again restates it. Asking only for what follows starts the subscription where the call is made and leaves the cache to a later ask. What cannot be had either way is anything from before the session existed, because there is no request to ask for it with. The last NEWS_BULLETIN_LIMIT are kept for a caller who has not asked yet.

def req_news_bulletins(all_msgs=True)

cancel_news_bulletins

Stop receiving broadcast notices.

def cancel_news_bulletins()

req_current_time

Ask for the venue's own clock. Answered on current_time. Before a session exists this is reported on error, the way every request made before connecting is: an answer waits for a dispatch pass, and with no session there is nothing to make one.

def req_current_time()

req_current_time_in_millis

Ask for the venue's own clock in milliseconds. Answered on current_time_in_millis. The same clock req_current_time reports and worked out the same way. What differs is the precision kept: asking in seconds throws away the fraction this one keeps. Before a session exists this is reported on error, as req_current_time is.

def req_current_time_in_millis()

request_fa

Ask the venue for a partition of the advisor's own configuration. The reference client names the partition by a number: its groups, its allocation profiles, its aliases. The allocation profiles are refused at the door under 585, with nothing sent, as the reference client refuses them. For the rest, the venue names the partition by a word, so the number is turned into the word it stands for; a number that stands for nothing draws the intake's own refusal rather than being sent as an empty partition. The venue's answer reaches receive_fa under the same number the partition was asked for by.

def request_fa(fa_data_type)

replace_fa

Replace a partition of the advisor's configuration with the one given. The allocation profiles are refused at the door under 585, as the reference client refuses them. replace_fa_end fires with req_id once the venue has taken it, and a venue that refuses states why on error under the same number.

def replace_fa(req_id, fa_data_type, cxml)

query_display_groups

Ask which display groups exist. Answered on display_group_list.

def query_display_groups(req_id)

subscribe_to_group_events

Watch what a display group is showing. Answered on display_group_updated.

def subscribe_to_group_events(req_id, group_id)

unsubscribe_from_group_events

Stop watching a display group.

def unsubscribe_from_group_events(req_id)

update_display_group

Tell a display group what to show.

def update_display_group(req_id, contract_info)

verify_request

Answered as the reference client answers it: on error, under 508 and no request, because intent to authenticate is stated on the initial connect and was not. Nothing is sent, so api_name and api_version reach nothing.

def verify_request(api_name, api_version)

verify_and_auth_request

As verify_request: api_name, api_version and opaque_isv_key reach nothing.

def verify_and_auth_request(api_name, api_version, opaque_isv_key)

verify_message

Nothing is sent and nothing answers. A gateway reads this message and discards it, so a program on one is answered by nothing either, and api_data reaches nothing there or here.

def verify_message(api_data)

verify_and_auth_message

As verify_message: api_data and xyz_response reach nothing.

def verify_and_auth_message(api_data, xyz_response)

req_smart_components

Ask which venue each bit of a quote's exchange mask refers to. The venue states the map beside the quote, so a quote has to have been asked for first. Answered on smart_components. bbo_exchange names the map: the one tick_req_params states for the contract. The venue states a map per BBO exchange and security type, so one contract's venues are not another's. A BBO exchange no subscription named is refused as a gateway refuses it; one whose map has not arrived yet is waited for up to two seconds, as a gateway waits, and answered from the dispatch loop rather than by holding this call.

def req_smart_components(req_id, bbo_exchange)

req_news_providers

Ask which news providers this account may read. Answered on news_providers.

def req_news_providers()

req_soft_dollar_tiers

Ask which soft dollar tiers this account may direct commission to. Answered on soft_dollar_tiers.

def req_soft_dollar_tiers(req_id)

req_family_codes

Ask which account families this login belongs to. Answered on family_codes.

def req_family_codes()

set_server_log_level

How much to log about this session, 1 to 5. 1 to 5 are a gateway's System, Error, Warning, Info and Detail, and set this client's logger to error, error, warn, info and trace. A gateway applies the level to its own log; this client, which serves the caller in its place, applies it to the logger it installed. Nothing goes to the venue, which has no message for it. Where the program installed a logger of its own, the call says so on error rather than reporting a level it did not set. A level outside 1 to 5 is refused rather than reported back as warn, which would tell a caller they had a level that does not exist.

def set_server_log_level(log_level=2)

req_user_info

Ask what this login is entitled to. Answered on user_info.

def req_user_info(req_id)

req_wsh_meta_data

What event types the corporate-events calendar carries. Answered on wshMetaData.

def req_wsh_meta_data(req_id)

cancel_wsh_meta_data

Stop waiting on the event types. The query is one message and one answer, so there is nothing at the venue to withdraw: what is withdrawn is the answer, which would otherwise reach a caller who has said they are done with it. A cancel naming no waiting request says so rather than returning as though it acted.

def cancel_wsh_meta_data(req_id)

cancel_wsh_event_data

Stop waiting on the calendar's events. As above.

def cancel_wsh_event_data(req_id)

req_wsh_event_data

The calendar's events. Answered on wshEventData. wsh_event_data is the object the public API takes: a contract id, or a filter the caller writes, plus the window and what to fill from.

def req_wsh_event_data(req_id, wsh_event_data=None)

EWrapper Callbacks

new

Create a new EClient (or EWrapper) instance.

connect_ack

The session is open. Nothing has been asked for yet.

connection_closed

The session is over, because this client ended it. A session that went away instead is reported on error under 1100.

next_valid_id

The first order id this session may use. Each order needs one higher than the last.

managed_accounts

Every account this login may act for, separated by commas. One for most logins; an advisor has several.

error

What the venue said about a request, under the number it says it with. Codes from 2100 to 2200 are notices about a connection rather than failures. req_id is -1 for anything that answers no particular request. A request this client will not send is reported here too, under the same numbers the reference client uses: 321 for a request that fails validation, 200 for a contract description that matches nothing, 504 for a call made with no session. error_time is the reference client's second parameter, in milliseconds since the epoch. A gateway stamps every error it sends, and so does this client: what the venue said about an order on a report, a refusal or a message, with the second the report states it was sent, and every other error with the clock as it is delivered.

error_from

An error, with what it is about: a request and whether nothing more follows for it, an order and the operation it answers, a request that carries no number, the session, or a lookup this client made for itself. The number error carries can be any of these and does not say which; origin says. Every error reaches a subclass of this class here. By default it goes on to error, under the number origin.id states it under, so a subclass that overrides only error is told exactly what it was told before. A wrapper that is not a subclass and has no method of this name is called on error, as the reference client calls it.

current_time

The venue clock, in seconds since the epoch.

current_time_in_millis

The venue clock, in milliseconds since the epoch. The same clock current_time reports, at the precision the venue stated it in. The stamp can carry a fraction of a second and this reads it where it does, but the stamps measured against this venue carried none, so the answer lands on a whole second.

tick_price

One price of a quote, and which price it is. tick_type names it — 1 bid, 2 ask, 4 last, 9 close — and attrib says whether it can be traded against and whether it is past its limit. A size arrives on tick_size under the type that belongs to it.

tick_size

One size of a quote, and which size it is: 0 bid, 3 ask, 5 last, 8 the day's volume.

tick_string

A quote's value that is not a number — a timestamp, an exchange map, a set of ids.

tick_generic

A quote's value that is a number and is not a price or a size — an implied volatility, an index future's premium, a halt.

tick_snapshot_end

A snapshot has stated everything it is going to. Only for a subscription asked for as a snapshot; a streaming one never ends.

market_data_type

Which feed a subscription is being served from: 1 live, 2 frozen, 3 delayed, 4 delayed and frozen.

order_status

Where an order stands now: stated as the venue reports on the order, again on each fill, and after the order's open_order when open orders are asked for. Sending a cancel states nothing, as a gateway states nothing then: asked for, the order reads PendingCancel, and the venue's next report on it states it so. filled and remaining are shares, avg_fill_price the average of what has filled so far.

open_order

An order as the venue holds it, and the state it is in. Fires beside every order_status, when open orders are asked for, and once for a preview — where the state carries what the order would cost and no status follows, because a preview is not an order.

open_order_end

Every open order has been stated.

exec_details

One fill, against the order and contract it filled. What it cost arrives separately, on commission_and_fees_report.

exec_details_end

Every execution answering this request has been stated.

commission_and_fees_report

What a fill cost, matched to it by execution id.

update_account_value

One figure the venue states about an account, in the currency it states it in. An account is stated in several currencies at once, so the same key arrives more than once.

update_portfolio

One position, as the venue values it now.

update_account_time

When the account figures above were last stated.

account_download_end

The account has been fully stated. Fires once the venue has stopped adding to it, not on the first figure.

account_summary

One figure answering req_account_summary, in the currency the venue states it in.

account_summary_end

Every figure answering this request has been stated.

position

One position held, on any account this login may act for.

position_end

Every position has been stated.

pnl

An account's running profit: today's, what is unrealised, and what has been realised.

pnl_single

The same for one position, with the size held.

historical_data

One bar answering a historical request. bar.date is a day for a daily bar and a moment for anything shorter, in the zone the bar carries.

historical_data_end

Every bar answering this request has been stated, and the window they cover.

historical_data_update

A bar that continues a keep_up_to_date request, after its first batch completed. The bar still forming is restated as it changes.

head_timestamp

The earliest moment the venue holds data for a contract.

contract_details

One contract matching a description, with everything the venue states about it. A description can match more than one.

contract_details_end

Every contract matching this request has been stated.

symbol_samples

Contracts whose symbol or name matches a pattern, across venues.

tick_by_tick_all_last

One trade, as it happens. tick_attrib_last says whether it was past a limit and whether it goes unreported to the tape.

tick_by_tick_bid_ask

One change to the top of the book, as it happens.

tick_by_tick_mid_point

One change to the midpoint, as it happens.

scanner_data

One row of a scan, in rank order.

scanner_data_end

Every row of this scan has been stated.

scanner_parameters

Every scan the venue offers and what each can be filtered by, as the XML the venue publishes.

news_providers

Every news provider this account may read.

news_article

The body of one article. article_type is 0 for text and 1 for a binary document.

historical_news

One headline from the archive.

historical_news_end

Every headline answering this request has been stated, and whether the archive holds more.

tick_news

A headline about a contract being watched, as it is published.