8.12
Interactive Brokers API🔗ℹ
Racket implementation for the Interactive Brokers’ Trader Workstation Client API.
This implementation is based on the Java TWS API version 976.01. The protocol used to communicate between the client and server establishes
the client version and should allow the server to continue consuming and producing messages compatible with our version even when the server
is updated. However, when there are desirable new features added, this library may be updated and its version number updated to reflect
the version of the TWS API the new code uses.
The overall design of this library is to use objects to represent the connection and request messages and to use structs to represent
response messages. Using objects for the connection and request messages seemed to make the process of creation easier as there are many
fields that are often not cared about and can be omitted. We also use an interface and a base class for request messages. For response
message, we stick to structs as we don’t care about inheritance, nor do we need an ease-of-use creation method as the library creates
the fully-filled-in instances. This is maybe a weird design.
1 Establishing a connection🔗ℹ
The general code flow to establish a (default) connection and send a message is as follows:
| (define ibkr (new ibkr-session%)) |
| (send ibkr connect) |
| ; The connection should be established after call to connect |
| ; Doing the below may be useful for testing |
| (require interactive-brokers-api/request-messages) |
| (send ibkr send-msg (new executions-req%)) |
This object is responsible for establishing a connection, sending messages, and registering callbacks to receive messages. One
quirk of this implementation is that calls to send-msg will block until we receive a response. During testing, it was
seen that attempting to send multiple requests without waiting for a response forced a disconnect.
| (new ibkr-session% | | | | [ | [client-id client-id] | | | | | [handle-account-value-rsp handle-account-value-rsp] | | | | | [handle-accounts-rsp handle-accounts-rsp] | | | | | [handle-commission-report-rsp handle-commission-report-rsp] | | | | | [handle-contract-details-rsp handle-contract-details-rsp] | | | | | [handle-err-rsp handle-err-rsp] | | | | | [handle-execution-rsp handle-execution-rsp] | | | | | [handle-historical-data-rsp handle-historical-data-rsp] | | | | | [handle-market-data-rsp handle-market-data-rsp] | | | | | [handle-next-valid-id-rsp handle-next-valid-id-rsp] | | | | | [handle-open-order-rsp handle-open-order-rsp] | | | | | [handle-order-status-rsp handle-order-status-rsp] | | | | | [handle-portfolio-value-rsp handle-portfolio-value-rsp] | | | | | [handle-server-time-rsp handle-server-time-rsp] | | | | | [hostname hostname] | | | | | [port-no port-no] | | | | | [write-messages write-messages]]) | |
|
| → (is-a?/c ibkr-session%) |
| client-id : integer? = 0 |
|
| handle-accounts-rsp : (-> (listof string?) any) = (λ (a) void) |
|
|
| handle-err-rsp : (-> err-rsp? any) = (λ (e) void) |
| handle-execution-rsp : (-> execution-rsp? any) = (λ (e) void) |
|
|
|
|
|
|
| handle-server-time-rsp : (-> moment? any) = (λ (st) void) |
| hostname : string? = "127.0.0.1" |
| port-no : port-number? = 7497 |
| write-messages : boolean? = #f |
On construction, we attempt to connect to the TWS server from the specified hostname and port-no. Encryption is
not used currently; this library is not recommended to be used over an unsecure network.
All response handlers will execute in the same, separate thread from the thread that constructs ibkr-session%.
The write-messages field, when set to #t, will write both request and response messages to the
current-output-port.
When called, a
thread is created to read from the socket and call the appropriate response handler with the received message.
Currently, this thread will die when the connection is interruped. When this happens, I just create a new
ibkr-session% to
connect again rather than attempt to call
connect on the existing session.
Sends a message over the established session. See the request-messages section for information on available request messages.
2 Request messages🔗ℹ
2.1 Base interface and class🔗ℹ
This interface makes sure all request messages provide a ->string method that can be used to serialize the object into a
string that can be processed by the server.
This is the base class for all request messages. There is no need for a client of this library to instantiate this class. This
class is just a declaration that each request message will contain a
msg-id and
version.
2.2 Account Data🔗ℹ
Request message to receive
account-value-rsps and
portfolio-value-rsps. Each component of an account (e.g Net
Liquidation, Account Code, Cash Balance, etc.) will be received in an individual response; there is no large structure or map
that will be returned that has all of the account components. Likewise for the components of a portfolio. If you wish to aggregate
the account and portfolio components, you will need to do that in your own application code. To receive account data, do:
By default subscribe is #f. To actually subscribe to data, you will need to set this value to #t. When
you are finished consuming account data, you can do the following to unsubscribe:
2.3 Contract Details🔗ℹ
Request message to receive a
contract-details-rsp. Here, if there is any ambiguity in your request, you will receive all of
the contract details that match your request. As an example,
will retrieve all actively trading AAPL options with a strike price of 200.0. By filling in more fields in your request, you are more
likely to retrieve a single result if that is your objective.
| (new contract-details-req% | | | | [ | [request-id request-id] | | | | | [contract-id contract-id] | | | | | [symbol symbol] | | | | | [security-type security-type] | | | | | [expiry expiry] | | | | | [strike strike] | | | | | [right right] | | | | | [multiplier multiplier] | | | | | [exchange exchange] | | | | | [primary-exchange primary-exchange] | | | | | [currency currency] | | | | | [local-symbol local-symbol] | | | | | [trading-class trading-class] | | | | | [security-id-type security-id-type] | | | | | [security-id security-id]]) | |
|
| → (is-a?/c contract-details-req%) |
| request-id : integer? = 0 |
| contract-id : integer? = 0 |
| symbol : string? = "" |
| | security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag 'ind | | 'bill 'fund 'fixed 'slb 'news 'cmdty | | 'bsk 'icu 'ics #f) |
| | | | | = | | #f |
|
| expiry : (or/c date? #f) = #f |
| strike : rational? = 0 |
| right : (or/c 'call 'put #f) = #f |
| multiplier : (or/c rational? #f) = #f |
| exchange : string? = "" |
| primary-exchange : string? = "" |
| currency : string? = "" |
| local-symbol : string? = "" |
| trading-class : string? = "" |
| security-id-type : (or/c 'cusip 'sedol 'isin 'ric #f) = #f |
| security-id : string? = "" |
2.4 Executions (otherwise known as trades)🔗ℹ
will retrieve all executions within a week.
| (new executions-req% | | | | [ | [request-id request-id] | | | | | [client-id client-id] | | | | | [account account] | | | | | [timestamp timestamp] | | | | | [symbol symbol] | | | | | [security-type security-type] | | | | | [exchange exchange] | | | | | [side side]]) | |
|
| → (is-a?/c executions-req%) |
| request-id : integer? = 0 |
| client-id : integer? = 0 |
| account : string? = "" |
| timestamp : (or/c moment? #f) = #f |
| symbol : string? = "" |
| | security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag 'ind | | 'bill 'fund 'fixed 'slb 'news 'cmdty | | 'bsk 'icu 'ics #f) |
| | | | | = | | #f |
|
| exchange : string? = "" |
| side : (or/c 'buy 'sell 'sshort #f) = #f |
2.5 Historical Data🔗ℹ
Request message to receive
historical-data-rsps. The interesting part of this response are the
bars
that are sent back and can be used for display in a chart. As an example,
will retrieve 1-hour (bar-size default) open-high-low-close bars from yesterday to today
(end-moment and duration defaults) representing trades (what-to-show default).
As of 2020-09-03, the smallest set of data at the finest resolution is to request 1-second bars over a duration of 30
seconds.
You will need to track the relationship between your request-id and your parameters as the returned
historical-data-rsps
will not have the symbol, security-type, etc. information.
| (new historical-data-req% | | | | [ | [request-id request-id] | | | | | [contract-id contract-id] | | | | | [symbol symbol] | | | | | [security-type security-type] | | | | | [expiry expiry] | | | | | [strike strike] | | | | | [right right] | | | | | [multiplier multiplier] | | | | | [exchange exchange] | | | | | [primary-exchange primary-exchange] | | | | | [currency currency] | | | | | [local-symbol local-symbol] | | | | | [trading-class trading-class] | | | | | [include-expired include-expired] | | | | | [end-moment end-moment] | | | | | [bar-size bar-size] | | | | | [duration duration] | | | | | [use-rth use-rth] | | | | | [what-to-show what-to-show] | | | | | [combo-legs combo-legs] | | | | | [keep-up-to-date keep-up-to-date] | | | | | [chart-options chart-options]]) | |
|
| → (is-a?/c historical-data-req%) |
| request-id : integer? = 0 |
| contract-id : integer? = 0 |
| symbol : string? = "" |
| | security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag 'ind | | 'bill 'fund 'fixed 'slb 'news 'cmdty | | 'bsk 'icu 'ics #f) |
| | | | | = | | #f |
|
| expiry : (or/c date? #f) = #f |
| strike : rational? = 0 |
| right : (or/c 'call 'put #f) = #f |
| multiplier : (or/c rational? #f) = #f |
| exchange : string? = "" |
| primary-exchange : string? = "" |
| currency : string? = "" |
| local-symbol : string? = "" |
| trading-class : string? = "" |
| include-expired : boolean? = #f |
| end-moment : moment? = (now/moment) |
| | bar-size | | : | | | (or/c '1-secs '5-secs '15-secs '30-secs '1-min | | '2-mins '3-mins '5-mins '15-mins | | '30-mins '1-hour '2-hours '3-hours | | '4-hours '8-hours '1-day '1W '1M) |
| | | | | = | | '1-hour |
|
| duration : period? = (days 1) |
| use-rth : boolean? = #f |
| | what-to-show | | : | | | (or/c 'trades 'midpoint 'bid 'ask 'bid-ask | | 'historical-volatility 'option-implied-volatility | | 'fee-rate 'rebate-rate) |
| | | | | = | | 'trades |
|
| combo-legs : (listof combo-leg?) = (list) |
| keep-up-to-date : boolean? = #f |
| chart-options : string? = "" |
2.6 Market Data🔗ℹ
will subscribe to (at least) bid/ask price and size updates.
You will need to track the relationship between your request-id and your parameters as the returned
market-data-rsps
will not have the symbol, security-type, etc. information.
| (new market-data-req% | | | | [ | [request-id request-id] | | | | | [contract-id contract-id] | | | | | [symbol symbol] | | | | | [security-type security-type] | | | | | [expiry expiry] | | | | | [strike strike] | | | | | [right right] | | | | | [multiplier multiplier] | | | | | [exchange exchange] | | | | | [primary-exchange primary-exchange] | | | | | [currency currency] | | | | | [local-symbol local-symbol] | | | | | [trading-class trading-class] | | | | | [combo-legs combo-legs] | | | | | [delta-neutral-contract-id delta-neutral-contract-id] | | | | | [delta-neutral-delta delta-neutral-delta] | | | | | [delta-neutral-price delta-neutral-price] | | | | | [generic-tick-list generic-tick-list] | | | | | [snapshot snapshot] | | | | | [regulatory-snapshot regulatory-snapshot] | | | | | [market-data-options market-data-options]]) | |
|
| → (is-a?/c market-data-req%) |
| request-id : integer? = 0 |
| contract-id : integer? = 0 |
| symbol : string? = "" |
| | security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag 'ind | | 'bill 'fund 'fixed 'slb 'news 'cmdty | | 'bsk 'icu 'ics #f) |
| | | | | = | | #f |
|
| expiry : (or/c date? #f) = #f |
| strike : rational? = 0 |
| right : (or/c 'call 'put #f) = #f |
| multiplier : (or/c rational? #f) = #f |
| exchange : string? = "" |
| primary-exchange : string? = "" |
| currency : string? = "" |
| local-symbol : string? = "" |
| trading-class : string? = "" |
| combo-legs : (listof combo-leg?) = (list) |
| delta-neutral-contract-id : (or/c integer? #f) = #f |
| delta-neutral-delta : (or/c rational? #f) = #f |
| delta-neutral-price : (or/c rational? #f) = #f |
| generic-tick-list : string? = "" |
| snapshot : boolean? = #f |
| regulatory-snapshot : boolean? = #f |
| market-data-options : string? = "" |
Request message to change the type of market data received using calls to
market-data-req%.
As an example,
will allow subsequent
market-data-req% calls to first retrieve real-time market data if available;
if not, delayed market data will be retrieved; if delayed data is unavailable, delayed frozen
(last available market data) data will be retrieved.
Using
market-data-type-req% is useful when subscribing to market data using a demo account where
real-time data may not be supported.
Request message to receive all
open-order-rsps. There are no fields to provide here to filter for particular
open orders.
Request message to place an order. As you can see below, there are tons of different fields to produce an order that is
as complex as you desire. Certain fields might interfere with others or be required by others. Despite this class’
many fields, it is likely that you will just be doing something simple like the following:
| (send ibkr send-msg |
| (new place-order-req% [symbol "AAPL"] |
| [security-type 'stk] |
| [exchange "SMART"] |
| [currency "USD"] |
| [action 'buy] |
| [total-quantity 100] |
| [limit-price 200.0])) |
Any questions related to which fields do what should first consult the IBKR docs or IBKR themselves. The fields of this
class are intended to exactly match those in the Java client library.
Be sure to add a handler for
next-valid-id-rsp in
ibkr-session% so that you don’t run into any errors
as a result of reusing an order ID. Order IDs are unique integers over the life of an account.
| (new place-order-req% | | | | [ | [order-id order-id] | | | | | [contract-id contract-id] | | | | | [symbol symbol] | | | | | [security-type security-type] | | | | | [expiry expiry] | | | | | [strike strike] | | | | | [right right] | | | | | [multiplier multiplier] | | | | | [exchange exchange] | | | | | [primary-exchange primary-exchange] | | | | | [currency currency] | | | | | [local-symbol local-symbol] | | | | | [trading-class trading-class] | | | | | [security-id-type security-id-type] | | | | | [security-id security-id] | | | | | [action action] | | | | | [total-quantity total-quantity] | | | | | [order-type order-type] | | | | | [limit-price limit-price] | | | | | [aux-price aux-price] | | | | | [time-in-force time-in-force] | | | | | [oca-group oca-group] | | | | | [account account] | | | | | [open-close open-close] | | | | | [origin origin] | | | | | [order-ref order-ref] | | | | | [transmit transmit] | | | | | [parent-id parent-id] | | | | | [block-order block-order] | | | | | [sweep-to-fill sweep-to-fill] | | | | | [display-size display-size] | | | | | [trigger-method trigger-method] | | | | | [outside-rth outside-rth] | | | | | [hidden hidden] | | | | | [combo-legs combo-legs] | | | | | [order-combo-legs order-combo-legs] | | | | | [smart-combo-routing-params smart-combo-routing-params] | | | | | [discretionary-amount discretionary-amount] | | | | | [good-after-time good-after-time] | | | | | [good-till-date good-till-date] | | | | | [advisor-group advisor-group] | | | | | [advisor-method advisor-method] | | | | | [advisor-percentage advisor-percentage] | | | | | [advisor-profile advisor-profile] | | | | | [model-code model-code] | | | | | [short-sale-slot short-sale-slot] | | | | | [designated-location designated-location] | | | | | [exempt-code exempt-code] | | | | | [oca-type oca-type] | | | | | [rule-80-a rule-80-a] | | | | | [settling-firm settling-firm] | | | | | [all-or-none all-or-none] | | | | | [minimum-quantity minimum-quantity] | | | | | [percent-offset percent-offset] | | | | | [electronic-trade-only electronic-trade-only] | | | | | [firm-quote-only firm-quote-only] | | | | | [nbbo-price-cap nbbo-price-cap] | | | | | [auction-strategy auction-strategy] | | | | | [starting-price starting-price] | | | | | [stock-ref-price stock-ref-price] | | | | | [delta delta] | | | | | [stock-range-lower stock-range-lower] | | | | | [stock-range-upper stock-range-upper] | | | | | [override-percentage-constraints override-percentage-constraints] | | | | | [volatility volatility] | | | | | [volatility-type volatility-type] | | | | | [delta-neutral-order-type delta-neutral-order-type] | | | | | [delta-neutral-aux-price delta-neutral-aux-price] | | | | | [continuous-update continuous-update] | | | | | [reference-price-type reference-price-type] | | | | | [trailing-stop-price trailing-stop-price] | | | | | [trailing-percent trailing-percent] | | | | | [scale-init-level-size scale-init-level-size] | | | | | [scale-subs-level-size scale-subs-level-size] | | | | | [scale-price-increment scale-price-increment] | | | | | [scale-price-adjust-value scale-price-adjust-value] | | | | | [scale-price-adjust-interval scale-price-adjust-interval] | | | | | [scale-profit-offset scale-profit-offset] | | | | | [scale-auto-reset scale-auto-reset] | | | | | [scale-init-position scale-init-position] | | | | | [scale-init-fill-quantity scale-init-fill-quantity] | | | | | [scale-random-percent scale-random-percent] | | | | | [scale-table scale-table] | | | | | [active-start-time active-start-time] | | | | | [active-stop-time active-stop-time] | | | | | [hedge-type hedge-type] | | | | | [hedge-param hedge-param] | | | | | [opt-out-smart-routing opt-out-smart-routing] | | | | | [clearing-account clearing-account] | | | | | [clearing-intent clearing-intent] | | | | | [not-held not-held] | | | | | [delta-neutral-contract-id delta-neutral-contract-id] | | | | | [delta-neutral-delta delta-neutral-delta] | | | | | [delta-neutral-price delta-neutral-price] | | | | | [algo-strategy algo-strategy] | | | | | [algo-strategy-params algo-strategy-params] | | | | | [algo-id algo-id] | | | | | [what-if what-if] | | | | | [order-misc-options order-misc-options] | | | | | [solicited solicited] | | | | | [randomize-size randomize-size] | | | | | [randomize-price randomize-price] | | | | | [reference-contract-id reference-contract-id] | | | | | [is-pegged-change-amount-decrease is-pegged-change-amount-decrease] | | | | | [pegged-change-amount pegged-change-amount] | | | | | [reference-change-amount reference-change-amount] | | | | | [reference-exchange-id reference-exchange-id] | | | | | [conditions conditions] | | | | | [conditions-ignore-rth conditions-ignore-rth] | | | | | [conditions-cancel-order conditions-cancel-order] | | | | | [adjusted-order-type adjusted-order-type] | | | | | [trigger-price trigger-price] | | | | | [limit-price-offset limit-price-offset] | | | | | [adjusted-stop-price adjusted-stop-price] | | | | | [adjusted-stop-limit-price adjusted-stop-limit-price] | | | | | [adjusted-trailing-amount adjusted-trailing-amount] | | | | | [adjusted-trailing-unit adjusted-trailing-unit] | | | | | [ext-operator ext-operator] | | | | | [soft-dollar-tier-name soft-dollar-tier-name] | | | | | [soft-dollar-tier-value soft-dollar-tier-value] | | | | | [cash-quantity cash-quantity] | | | | | [mifid2-decision-maker mifid2-decision-maker] | | | | | [mifid2-decision-algo mifid2-decision-algo] | | | | | [mifid2-execution-trader mifid2-execution-trader] | | | | | [mifid2-execution-algo mifid2-execution-algo] | | | | | [dont-use-auto-price-for-hedge dont-use-auto-price-for-hedge] | | | | | [is-oms-container is-oms-container] | | | | | [discretionary-up-to-limit-price discretionary-up-to-limit-price] | | | | | [use-price-management-algo use-price-management-algo]]) | |
|
| → (is-a?/c place-order-req%) |
| order-id : integer? = 0 |
| contract-id : integer? = 0 |
| symbol : string? = "" |
| | security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag 'ind | | 'bill 'fund 'fixed 'slb 'news 'cmdty | | 'bsk 'icu 'ics #f) |
| | | | | = | | #f |
|
| expiry : (or/c date? #f) = #f |
| strike : rational? = 0 |
| right : (or/c 'call 'put #f) = #f |
| multiplier : (or/c rational? #f) = #f |
| exchange : string? = "" |
| primary-exchange : string? = "" |
| currency : string? = "" |
| local-symbol : string? = "" |
| trading-class : string? = "" |
| security-id-type : (or/c 'cusip 'sedol 'isin 'ric #f) = #f |
| security-id : string? = "" |
| action : (or/c 'buy 'sell 'sshort) = 'buy |
| total-quantity : rational? = 0 |
| order-type : string? = "LMT" |
| limit-price : (or/c rational? #f) = #f |
| aux-price : (or/c rational? #f) = #f |
| | time-in-force | | : | | | (or/c 'day 'gtc 'opg 'ioc 'gtd 'gtt | | 'auc 'fok 'gtx 'dtc) |
| | = | | 'day |
|
| oca-group : string? = "" |
| account : string? = "" |
| open-close : (or/c 'open 'close) = 'open |
| origin : (or/c 'customer 'firm) = 'customer |
| order-ref : string? = "" |
| transmit : boolean? = #t |
| parent-id : integer? = 0 |
| block-order : boolean? = #f |
| sweep-to-fill : boolean? = #f |
| display-size : integer? = 0 |
| trigger-method : integer? = 0 |
| outside-rth : boolean? = #f |
| hidden : boolean? = #f |
| combo-legs : (listof combo-leg?) = (list) |
| order-combo-legs : (listof rational?) = (list) |
| smart-combo-routing-params : hash? = (hash) |
| discretionary-amount : (or/c rational? #f) = #f |
| good-after-time : (or/c moment? #f) = #f |
| good-till-date : (or/c date? #f) = #f |
| advisor-group : string? = "" |
| advisor-method : string? = "" |
| advisor-percentage : string? = "" |
| advisor-profile : string? = "" |
| model-code : string? = "" |
| short-sale-slot : (or/c 0 1 2) = 0 |
| designated-location : string? = "" |
| exempt-code : integer? = -1 |
| oca-type : integer? = 0 |
| rule-80-a : string? = "" |
| settling-firm : string? = "" |
| all-or-none : boolean? = #f |
| minimum-quantity : (or/c integer? #f) = #f |
| percent-offset : (or/c rational? #f) = #f |
| electronic-trade-only : boolean? = #f |
| firm-quote-only : boolean? = #f |
| nbbo-price-cap : (or/c rational? #f) = #f |
| | auction-strategy | | : | | (or/c 'match 'improvement 'transparent #f) | | | | | = | | #f |
|
| starting-price : rational? = 0 |
| stock-ref-price : rational? = 0 |
| delta : (or/c rational? #f) = #f |
| stock-range-lower : rational? = 0 |
| stock-range-upper : rational? = 0 |
| override-percentage-constraints : boolean? = #f |
| volatility : (or/c rational? #f) = #f |
| volatility-type : (or/c integer? #f) = #f |
| delta-neutral-order-type : string? = "" |
| delta-neutral-aux-price : (or/c rational? #f) = #f |
| continuous-update : integer? = 0 |
| reference-price-type : (or/c integer? #f) = #f |
| trailing-stop-price : (or/c rational? #f) = #f |
| trailing-percent : (or/c rational? #f) = #f |
| scale-init-level-size : (or/c integer? #f) = #f |
| scale-subs-level-size : (or/c integer? #f) = #f |
| scale-price-increment : (or/c rational? #f) = #f |
| scale-price-adjust-value : (or/c rational? #f) = #f |
| scale-price-adjust-interval : (or/c integer? #f) = #f |
| scale-profit-offset : (or/c rational? #f) = #f |
| scale-auto-reset : boolean? = #f |
| scale-init-position : (or/c integer? #f) = #f |
| scale-init-fill-quantity : (or/c integer? #f) = #f |
| scale-random-percent : boolean? = #f |
| scale-table : string? = "" |
| active-start-time : string? = "" |
| active-stop-time : string? = "" |
| hedge-type : string? = "" |
| hedge-param : string? = "" |
| opt-out-smart-routing : boolean? = #f |
| clearing-account : string? = "" |
| clearing-intent : (or/c 'ib 'away 'pta #f) = #f |
| not-held : boolean? = #f |
| delta-neutral-contract-id : (or/c integer? #f) = #f |
| delta-neutral-delta : (or/c rational? #f) = #f |
| delta-neutral-price : (or/c rational? #f) = #f |
| algo-strategy : string? = "" |
| algo-strategy-params : hash? = (hash) |
| algo-id : string? = "" |
| what-if : boolean? = #f |
| order-misc-options : string? = "" |
| solicited : boolean? = #f |
| randomize-size : boolean? = #f |
| randomize-price : boolean? = #f |
| reference-contract-id : integer? = 0 |
| is-pegged-change-amount-decrease : boolean? = #f |
| pegged-change-amount : rational? = 0 |
| reference-change-amount : rational? = 0 |
| reference-exchange-id : string? = "" |
| conditions : (listof condition?) = (list) |
| conditions-ignore-rth : boolean? = #f |
| conditions-cancel-order : boolean? = #f |
| | adjusted-order-type | | : | | | (or/c 'mkt 'lmt 'stp 'stp-limit | | 'rel 'trail 'box-top 'fix-pegged | | 'lit 'lmt-+-mkt 'loc 'mit | | 'mkt-prt 'moc 'mtl 'passv-rel | | 'peg-bench 'peg-mid 'peg-mkt 'peg-prim | | 'peg-stk 'rel-+-lmt 'rel-+-mkt 'snap-mid | | 'snap-mkt 'snap-prim 'stp-prt 'trail-limit | | 'trail-lit 'trail-lmt-+-mkt 'trail-mit | | 'trail-rel-+-mkt 'vol 'vwap 'quote 'ppv | | 'pdv 'pmv 'psv #f) |
| | | | | = | | #f |
|
| trigger-price : rational? = 0 |
| limit-price-offset : rational? = 0 |
| adjusted-stop-price : rational? = 0 |
| adjusted-stop-limit-price : rational? = 0 |
| adjusted-trailing-amount : rational? = 0 |
| adjusted-trailing-unit : integer? = 0 |
| ext-operator : string? = "" |
| soft-dollar-tier-name : string? = "" |
| soft-dollar-tier-value : string? = "" |
| cash-quantity : rational? = 0 |
| mifid2-decision-maker : string? = "" |
| mifid2-decision-algo : string? = "" |
| mifid2-execution-trader : string? = "" |
| mifid2-execution-algo : string? = "" |
| dont-use-auto-price-for-hedge : boolean? = #f |
| is-oms-container : boolean? = #f |
| discretionary-up-to-limit-price : boolean? = #f |
| use-price-management-algo : boolean? = #f |
Please note that the fields action, order-type, time-in-force, open-close, and origin
use defaults that are not the #f, 0, or "" typical defaults. Also note that you need to manage
order-id on your own. If you do not supply an order-id, it will use 0 and you will likely get an error stating
the order ID has already been used.
3 Response messages🔗ℹ
As with the Java API, value here is often numeric, but we leave it as a string because this field is not guaranteed
to be numeric.
Commission reports are sent along with executions when calls are made to
executions-req%.
| (struct | | contract-details-rsp | ( | request-id | | | | | | symbol | | | | | | security-type | | | | | | expiry | | | | | | strike | | | | | | right | | | | | | exchange | | | | | | currency | | | | | | local-symbol | | | | | | market-name | | | | | | trading-class | | | | | | contract-id | | | | | | minimum-tick-increment | | | | | | md-size-multiplier | | | | | | multiplier | | | | | | order-types | | | | | | valid-exchanges | | | | | | price-magnifier | | | | | | underlying-contract-id | | | | | | long-name | | | | | | primary-exchange | | | | | | contract-month | | | | | | industry | | | | | | category | | | | | | subcategory | | | | | | time-zone-id | | | | | | trading-hours | | | | | | liquid-hours | | | | | | ev-rule | | | | | | ev-multiplier | | | | | | security-ids | | | | | | agg-group | | | | | | underlying-symbol | | | | | | underlying-security-type | | | | | | market-rule-ids | | | | | | real-expiry) |
|
| #:extra-constructor-name make-contract-details-rsp) |
| request-id : integer? |
| symbol : string? |
| | security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag 'ind | | 'bill 'fund 'fixed 'slb 'news 'cmdty | | 'bsk 'icu 'ics #f) |
|
|
| expiry : (or/c date? #f) |
| strike : (or/c rational? #f) |
| right : (or/c 'call 'put #f) |
| exchange : string? |
| currency : string? |
| local-symbol : string? |
| market-name : string? |
| trading-class : string? |
| contract-id : integer? |
| minimum-tick-increment : rational? |
| md-size-multiplier : integer? |
| multiplier : string? |
| order-types : (listof string?) |
| valid-exchanges : (listof string?) |
| price-magnifier : integer? |
| underlying-contract-id : integer? |
| long-name : string? |
| primary-exchange : string? |
| contract-month : string? |
| industry : string? |
| category : string? |
| subcategory : string? |
| time-zone-id : string? |
| trading-hours : (listof string?) |
| liquid-hours : (listof string?) |
| ev-rule : string? |
| ev-multiplier : string? |
| security-ids : hash? |
| agg-group : integer? |
| underlying-symbol : string? |
| | underlying-security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag | | 'ind 'bill 'fund 'fixed 'slb 'news | | 'cmdty 'bsk 'icu 'ics #f) |
|
|
| market-rule-ids : (listof string?) |
| real-expiry : (or/c date? #f) |
When receiving contract details, it is often nice to use the contract-id for subsequent new order or market data
requests as these identifiers are unique.
Generic error message for incorrectly formed requests. Consult the Java API docs for more information.
It is recommended to periodically call
executions-req% to make sure you receive all of the executions that have occurred.
|
| #:extra-constructor-name make-historical-data-rsp) |
| request-id : integer? |
| start-moment : moment? |
| end-moment : moment? |
| bars : (listof bar?) |
Be sure to check for
err-rsps if you are not receiving historical data when you expect to.
More information about tick types can be found in the
IBKR Docs.
|
| #:extra-constructor-name make-next-valid-id-rsp) |
| order-id : integer? |
This response should be saved locally so that calls to
place-order-req% can include this saved value. It is not recommended
to just track order IDs independently of what the API is giving you. As a reminder, it is necessary to provide an order ID to
place-order-req%.
| (struct | | open-order-rsp | ( | order-id | | | | | | contract-id | | | | | | symbol | | | | | | security-type | | | | | | expiry | | | | | | strike | | | | | | right | | | | | | multiplier | | | | | | exchange | | | | | | currency | | | | | | local-symbol | | | | | | trading-class | | | | | | action | | | | | | total-quantity | | | | | | order-type | | | | | | limit-price | | | | | | aux-price | | | | | | time-in-force | | | | | | oca-group | | | | | | account | | | | | | open-close | | | | | | origin | | | | | | order-ref | | | | | | client-id | | | | | | perm-id | | | | | | outside-rth | | | | | | hidden | | | | | | discretionary-amount | | | | | | good-after-time | | | | | | advisor-group | | | | | | advisor-method | | | | | | advisor-percentage | | | | | | advisor-profile | | | | | | model-code | | | | | | good-till-date | | | | | | rule-80-a | | | | | | percent-offset | | | | | | settling-firm | | | | | | short-sale-slot | | | | | | designated-location | | | | | | exempt-code | | | | | | auction-strategy | | | | | | starting-price | | | | | | stock-ref-price | | | | | | delta | | | | | | stock-range-lower | | | | | | stock-range-upper | | | | | | display-size | | | | | | block-order | | | | | | sweep-to-fill | | | | | | all-or-none | | | | | | minimum-quantity | | | | | | oca-type | | | | | | electronic-trade-only | | | | | | firm-quote-only | | | | | | nbbo-price-cap | | | | | | parent-id | | | | | | trigger-method | | | | | | volatility | | | | | | volatility-type | | | | | | delta-neutral-order-type | | | | | | delta-neutral-aux-price | | | | | | delta-neutral-contract-id | | | | | | delta-neutral-settling-firm | | | | | | delta-neutral-clearing-account | | | | | | delta-neutral-clearing-intent | | | | | | delta-neutral-open-close | | | | | | delta-neutral-short-sale | | | | | | delta-neutral-short-sale-slot | | | | | | delta-neutral-designated-location | | | | | | continuous-update | | | | | | reference-price-type | | | | | | trailing-stop-price | | | | | | trailing-percent | | | | | | basis-points | | | | | | basis-points-type | | | | | | combo-legs-description | | | | | | combo-legs | | | | | | order-combo-legs | | | | | | smart-combo-routing-params | | | | | | scale-init-level-size | | | | | | scale-subs-level-size | | | | | | scale-price-increment | | | | | | scale-price-adjust-value | | | | | | scale-price-adjust-interval | | | | | | scale-profit-offset | | | | | | scale-auto-reset | | | | | | scale-init-position | | | | | | scale-init-fill-quantity | | | | | | scale-random-percent | | | | | | hedge-type | | | | | | hedge-param | | | | | | opt-out-smart-routing | | | | | | clearing-account | | | | | | clearing-intent | | | | | | not-held | | | | | | delta-neutral-underlying-contract-id | | | | | | delta-neutral-underlying-delta | | | | | | delta-neutral-underlying-price | | | | | | algo-strategy | | | | | | algo-strategy-params | | | | | | solicited | | | | | | what-if | | | | | | status | | | | | | initial-margin-before | | | | | | maintenance-margin-before | | | | | | equity-with-loan-before | | | | | | initial-margin-change | | | | | | maintenance-margin-change | | | | | | equity-with-loan-change | | | | | | initial-margin-after | | | | | | maintenance-margin-after | | | | | | equity-with-loan-after | | | | | | commission | | | | | | minimum-commission | | | | | | maximum-commission | | | | | | commission-currency | | | | | | warning-text | | | | | | randomize-size | | | | | | randomize-price | | | | | | reference-contract-id | | | | | | is-pegged-change-amount-decrease | | | | | | pegged-change-amount | | | | | | reference-change-amount | | | | | | reference-exchange-id | | | | | | conditions | | | | | | adjusted-order-type | | | | | | trigger-price | | | | | | trail-stop-price | | | | | | limit-price-offset | | | | | | adjusted-stop-price | | | | | | adjusted-stop-limit-price | | | | | | adjusted-trailing-amount | | | | | | adjusted-trailing-unit | | | | | | soft-dollar-tier-name | | | | | | soft-dollar-tier-value | | | | | | soft-dollar-tier-display-name | | | | | | cash-quantity | | | | | | dont-use-auto-price-for-hedge | | | | | | is-oms-container | | | | | | discretionary-up-to-limit-price | | | | | | use-price-management-algo) |
|
| #:extra-constructor-name make-open-order-rsp) |
| order-id : integer? |
| contract-id : integer? |
| symbol : string? |
| | security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag 'ind | | 'bill 'fund 'fixed 'slb 'news 'cmdty | | 'bsk 'icu 'ics #f) |
|
|
| expiry : (or/c date? #f) |
| strike : (or/c rational? #f) |
| right : (or/c 'call 'put #f) |
| multiplier : (or/c rational? #f) |
| exchange : string? |
| currency : string? |
| local-symbol : string? |
| trading-class : string? |
| action : (or/c 'buy 'sell 'sshort) |
| total-quantity : rational? |
| order-type : string? |
| limit-price : (or/c rational? #f) |
| aux-price : (or/c rational? #f) |
| | time-in-force | | : | | | (or/c 'day 'gtc 'opg 'ioc 'gtd 'gtt | | 'auc 'fok 'gtx 'dtc) |
|
|
| oca-group : string? |
| account : string? |
| open-close : (or/c 'open 'close #f) |
| origin : (or/c 'customer 'firm) |
| order-ref : string? |
| client-id : integer? |
| perm-id : integer? |
| outside-rth : boolean? |
| hidden : boolean? |
| discretionary-amount : (or/c rational? #f) |
| good-after-time : (or/c moment? #f) |
| advisor-group : string? |
| advisor-method : string? |
| advisor-percentage : string? |
| advisor-profile : string? |
| model-code : string? |
| good-till-date : (or/c date? #f) |
| rule-80-a : string? |
| percent-offset : (or/c rational? #f) |
| settling-firm : string? |
| short-sale-slot : (or/c 0 1 2) |
| designated-location : string? |
| exempt-code : integer? |
| auction-strategy : (or/c 'match 'improvement 'transparent #f) |
| starting-price : (or/c rational? #f) |
| stock-ref-price : (or/c rational? #f) |
| delta : (or/c rational? #f) |
| stock-range-lower : (or/c rational? #f) |
| stock-range-upper : (or/c rational? #f) |
| display-size : (or/c integer? #f) |
| block-order : boolean? |
| sweep-to-fill : boolean? |
| all-or-none : boolean? |
| minimum-quantity : (or/c integer? #f) |
| oca-type : integer? |
| electronic-trade-only : boolean? |
| firm-quote-only : boolean? |
| nbbo-price-cap : (or/c rational? #f) |
| parent-id : integer? |
| trigger-method : integer? |
| volatility : (or/c rational? #f) |
| volatility-type : (or/c integer? #f) |
| delta-neutral-order-type : string? |
| delta-neutral-aux-price : (or/c rational? #f) |
| delta-neutral-contract-id : (or/c integer? #f) |
| delta-neutral-settling-firm : string? |
| delta-neutral-clearing-account : string? |
| delta-neutral-clearing-intent : string? |
| delta-neutral-open-close : (or/c 'open 'close #f) |
| delta-neutral-short-sale : boolean? |
| delta-neutral-short-sale-slot : (or/c integer? #f) |
| delta-neutral-designated-location : string? |
| continuous-update : integer? |
| reference-price-type : (or/c integer? #f) |
| trailing-stop-price : (or/c rational? #f) |
| trailing-percent : (or/c rational? #f) |
| basis-points : (or/c rational? #f) |
| basis-points-type : (or/c integer? #f) |
| combo-legs-description : string? |
| combo-legs : (listof combo-leg?) |
| order-combo-legs : (listof rational?) |
| smart-combo-routing-params : hash? |
| scale-init-level-size : (or/c integer? #f) |
| scale-subs-level-size : (or/c integer? #f) |
| scale-price-increment : (or/c rational? #f) |
| scale-price-adjust-value : (or/c rational? #f) |
| scale-price-adjust-interval : (or/c integer? #f) |
| scale-profit-offset : (or/c rational? #f) |
| scale-auto-reset : boolean? |
| scale-init-position : (or/c integer? #f) |
| scale-init-fill-quantity : (or/c integer? #f) |
| scale-random-percent : boolean? |
| hedge-type : string? |
| hedge-param : string? |
| opt-out-smart-routing : boolean? |
| clearing-account : string? |
| clearing-intent : (or/c 'ib 'away 'pta #f) |
| not-held : boolean? |
| delta-neutral-underlying-contract-id : (or/c integer? #f) |
| delta-neutral-underlying-delta : (or/c rational? #f) |
| delta-neutral-underlying-price : (or/c rational? #f) |
| algo-strategy : string? |
| algo-strategy-params : hash? |
| solicited : boolean? |
| what-if : boolean? |
| status : string? |
| initial-margin-before : (or/c rational? #f) |
| maintenance-margin-before : (or/c rational? #f) |
| equity-with-loan-before : (or/c rational? #f) |
| initial-margin-change : (or/c rational? #f) |
| maintenance-margin-change : (or/c rational? #f) |
| equity-with-loan-change : (or/c rational? #f) |
| initial-margin-after : (or/c rational? #f) |
| maintenance-margin-after : (or/c rational? #f) |
| equity-with-loan-after : (or/c rational? #f) |
| commission : (or/c rational? #f) |
| minimum-commission : (or/c rational? #f) |
| maximum-commission : (or/c rational? #f) |
| commission-currency : string? |
| warning-text : string? |
| randomize-size : boolean? |
| randomize-price : boolean? |
| reference-contract-id : (or/c integer? #f) |
| is-pegged-change-amount-decrease : boolean? |
| pegged-change-amount : (or/c rational? #f) |
| reference-change-amount : (or/c rational? #f) |
| reference-exchange-id : string? |
| conditions : (listof condition?) |
| | adjusted-order-type | | : | | | (or/c 'mkt 'lmt 'stp 'stp-limit | | 'rel 'trail 'box-top 'fix-pegged | | 'lit 'lmt-+-mkt 'loc 'mit | | 'mkt-prt 'moc 'mtl 'passv-rel | | 'peg-bench 'peg-mid 'peg-mkt 'peg-prim | | 'peg-stk 'rel-+-lmt 'rel-+-mkt 'snap-mid | | 'snap-mkt 'snap-prim 'stp-prt 'trail-limit | | 'trail-lit 'trail-lmt-+-mkt 'trail-mit | | 'trail-rel-+-mkt 'vol 'vwap 'quote 'ppv | | 'pdv 'pmv 'psv #f) |
|
|
| trigger-price : (or/c rational? #f) |
| trail-stop-price : (or/c rational? #f) |
| limit-price-offset : (or/c rational? #f) |
| adjusted-stop-price : (or/c rational? #f) |
| adjusted-stop-limit-price : (or/c rational? #f) |
| adjusted-trailing-amount : (or/c rational? #f) |
| adjusted-trailing-unit : integer? |
| soft-dollar-tier-name : string? |
| soft-dollar-tier-value : string? |
| soft-dollar-tier-display-name : string? |
| cash-quantity : rational? |
| dont-use-auto-price-for-hedge : boolean? |
| is-oms-container : boolean? |
| discretionary-up-to-limit-price : boolean? |
| use-price-management-algo : boolean? |
This response is largely just telling you what you already provided to
place-order-req%. The fields of interest here
are the generated
client-id and
perm-id.
This response gives a useful summary of the status of an order as well as the amount filled and amount remaining.
| (struct | | combo-leg | ( | contract-id | | | | | | ratio | | | | | | action | | | | | | exchange | | | | | | open-close | | | | | | short-sale-slot | | | | | | designated-location | | | | | | exempt-code) |
|
| #:extra-constructor-name make-combo-leg) |
| contract-id : integer? |
| ratio : integer? |
| action : (or/c 'buy 'sell 'sshort) |
| exchange : string? |
| open-close : (or/c 'same 'open 'close #f) |
| short-sale-slot : (or/c 0 1 2) |
| designated-location : string? |
| exempt-code : integer? |
Use
combo-leg within
place-order-req% when you want to place a spread. This is commonly done for options
and will work for many strategies. Note that you can only provide
contract-id, which you can retrieve from
contract-details-req%.
| (struct | | condition | ( | type | | | | | | boolean-operator | | | | | | comparator | | | | | | value | | | | | | contract-id | | | | | | exchange | | | | | | trigger-method | | | | | | security-type | | | | | | symbol) |
|
| #:extra-constructor-name make-condition) |
| | type | | : | | | (or/c 'price 'time 'margin | | 'execution 'volume 'percent-change) |
|
|
| boolean-operator : (or/c 'and 'or) |
| comparator : (or/c 'less-than 'greater-than #f) |
| value : (or/c rational? moment? #f) |
| contract-id : (or/c integer? #f) |
| exchange : (or/c string? #f) |
| | trigger-method | | : | | | (or/c 'default 'double-bid/ask 'last 'double-last | | 'bid/ask 'last-of-bid/ask 'mid-point #f) |
|
|
| | security-type | | : | | | (or/c 'stk 'opt 'fut 'cash 'bond 'cfd | | 'fop 'war 'iopt 'fwd 'bag 'ind | | 'bill 'fund 'fixed 'slb 'news 'cmdty | | 'bsk 'icu 'ics #f) |
|
|
| symbol : (or/c string? #f) |
Use
condition within
place-order-req% when you want your order to either take effect or be canceled only
when certain conditions are met.
'price conditions require: boolean-operator, comparator, value, contract-id,
exchange, and trigger-method.
'time conditions require: boolean-operator, comparator, and value.
'margin conditions require: boolean-operator, comparator, and value.
'execution conditions require: boolean-operator, exchange, security-type, and symbol.
'volume conditions require: boolean-operator, comparator, value, contract-id,
and exchange.
'percent-change conditions require: boolean-operator, comparator, value, contract-id,
and exchange.
Where fields are not required for a given condition type, they are not sent to the server and are effectively ignored.