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.

update_mkt_depth

One level of a book that names no venue. operation is 0 to insert, 1 to update, 2 to delete; side is 0 ask, 1 bid.

update_mkt_depth_l2

One level of a book that names the venue it stands on. Every level from this client names one.

mkt_depth_exchanges

Every exchange the venue names, in the two sections it names them in: shares and derivatives.

real_time_bar

One five-second bar of a live stream.

historical_ticks

Historical midpoints, in batches, until done.

historical_ticks_bid_ask

Historical quotes, in batches, until done.

historical_ticks_last

Historical trades, in batches, until done.

tick_option_computation

The venue's model for an option: the volatility its price implies, the greeks, and the modelled value of the option and its underlying. Every figure is None where the venue stated none. The reference client hands a caller None for those, so this surface does too, and a wrapper that has not overridden this is handed the same. Declared as a number, the default refused the call and the exception left the caller's reading loop: a caller who watched an option and did not write this method lost the session on the first model the venue did not fill in.

security_definition_option_parameter

One venue's option chain for an underlying and trading class: the expiries and strikes it lists for that class.

security_definition_option_parameter_end

Every venue's chain has been stated.

fundamental_data

A fundamental report, as the XML the venue publishes.

update_news_bulletin

A notice the venue broadcasts to everyone — an exchange unavailable, a system message.

receive_fa

A partition of an advisor's configuration, as the XML the venue holds it in.

replace_fa_end

An advisor configuration has been replaced.

position_multi

One position, for a request naming an account or a model.

position_multi_end

Every position answering this request has been stated.

account_update_multi

One account figure, for a request naming an account or a model.

account_update_multi_end

Every figure answering this request has been stated.

display_group_list

Which display groups exist, as the venue numbers them.

display_group_updated

What a display group is now showing.

market_rule

The price ladder a contract trades on: each step, and what the price moves in above it.

smart_components

Which venue each bit of a quote's exchange mask refers to, and the letter that venue is named by.

soft_dollar_tiers

The soft dollar tiers this account may direct commission to.

family_codes

The account families this login belongs to.

histogram_data

How much traded at each price over a window.

user_info

What the login is entitled to, as the venue states it.

wsh_meta_data

What the corporate-events calendar carries: its event types and the fields each one has, as the JSON the venue publishes.

wsh_event_data

Events from the corporate-events calendar, as the JSON the venue publishes. Events themselves need a Wall Street Horizon subscription; a login without one is answered with an empty set.

completed_order

An order that is done — filled, cancelled or expired — as the venue holds it.

completed_orders_end

Every completed order has been stated.

order_bound

An order placed elsewhere has been bound to this session, so its changes arrive here.

tick_req_params

What a subscription was given: the increment its prices move in, which venues it is served from, and which feed answered. Sent once per request, with the first record it is served, as a gateway sends it; a request served none is sent none.

bond_contract_details

One bond matching a description, with its terms: what it pays, how and when, whether it can be called or put, whether it converts, what it is rated.

reroute_mkt_data_req

The contract a market-data request should be asked for under instead. A gateway sends it, and asks the venue nothing, for a contract for difference whose own definition asks for its underlying's data, where the account's logon permissions allow that: the underlying's contract and the venue to ask on. This client does not read a definition's flags for asking on the underlying before subscribing: the request goes to the venue as asked, and this never fires.

reroute_mkt_depth_req

The same, for a request for the book rather than the quote.

delta_neutral_validation

The contract the venue paired with a delta-neutral order. Declared by the TWS API and never fired on a gateway: a gateway never sends it. It fires here as it does there: never.

tick_efp

An exchange-for-physical quote. Declared by the TWS API and never fired on a gateway, so it fires here as it does there: never.

verify_message_api

A step in the TWS API's verification handshake. Declared by the TWS API and never fired on a gateway, so these four fire here as they do there: never.

verify_completed

Whether that handshake was accepted.

verify_and_auth_message_api

The same handshake, where the terminal also authenticates the program.

verify_and_auth_completed

Whether that one was accepted.

win_error

Declared by the TWS API as winError. No message on the wire carries it, and the TWS API's Python client declares it and never raises it, so it fires here as it does there: never. Here, trouble on a connection reaches a caller on the error callback.

historical_schedule

When a contract's venue was open over a window, session by session, in the zone the venue keeps.