diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ibkr.org | 294 |
1 files changed, 294 insertions, 0 deletions
diff --git a/doc/ibkr.org b/doc/ibkr.org new file mode 100644 index 0000000..f879129 --- /dev/null +++ b/doc/ibkr.org @@ -0,0 +1,294 @@ +#+TITLE: Interactive Brokers +#+AUTHOR: Daniel Rostovtsev + +#+TEXINFO_DIR_CATEGORY: Trading +#+TEXINFO_DIR_NAME: Interactive Brokers +#+TEXINFO_DIR_DESC: Routing requests to the interactive brokers trading API + +* History + +Interactive Brokers is a publicly-traded broker dealer with an +investment grade rating by Standard and Poor's. It started as a market +maker with Thomas Peterffy, who bought a chair on AMEX in 1977 and +founded "T.P. & Co." in 1978. + +In 1979, the company hired its first four employees, and wrote one of +the first equity options trading algorithms, which they started using +in 1982. By 1983, they created the first handheld computers to give +traders recommendations on the floor, and in 1984 they began trading +with a fully fledged electronic operation. + +After a period of rapid expansion in the late 1980s, the company +rebrands as "Timber Hill" and grows to 150 employees, trading a +variety of securities internationally as electronic trading is gaining +wider adoption. + +In the late 1990s, the company expands from market making into +brokerage services. In 1998, they begin to clear S&P futures for +retail clients, and in 1999 they begin to offer "smart routing" +services for multiple equity options. + +The company has continued to grow and add new retail and institutional +clients since the early 2000s. + +More is available about interactive brokers at their site at: +https://www.interactivebrokers.com/en/general/about/. + +* The Trading API + +Interactive Brokers offers a REST API for retail clients to send +orders, query their accounts, and poll market data. + +Here we used the "Web API v1.0", which is documented at: +https://www.interactivebrokers.com/campus/ibkr-api-page/cpapi-v1/#cpgw + +** Connecting to the API + +#+CINDEX: Client Gateway + +Interactive Brokers expects clients to route orders through a "client +gateway" which is a service run on the client's machine program which +manages authenticating and forwarding requests to the actual +Interactive Brokers API. + +#+CINDEX: Procyon + +The client gateway is written in Java, and the code can be decompiled +with tools like "procyon". By default, the gateway is configured to +forward requests send to port 5000 on the service machine. + +#+CINDEX: SSL + +By default, the client listens with SSL on port 5000. However, if you +are comfortable that this connection is secure you can turn off SSL +and connect to it directly. + +We currently provide a tool to start-up a connection and keep it +alive. + +#+BEGIN_SRC bash + ./scripts/run-gateway.bash & +#+END_SRC + +After starting up a connection, the user can navigate to +http://localhost:5000 and login. The connection logs are in ~gw.out~ +and the connection errors are in ~gw.err~. If you want to use a paper +trading session, be sure to select paper trading and login with your +paper trading account details. + +For more details, read the scripts themselves. + +** Idiosyncracies + +The IBKR API has a few idiosyncracies and patters specific to their +implementation. One, their responses are untyped blobs, and the names +for fixed values tend to change across different endpoints. As such, +it is the responsibility of the user to normalize their interactions +with the API and organize the data they use. + +In general, the API does not send reponses with return code not equal +to 200 even when messages trigger errors or warnings that the user has +to handle. It is up to the user to read the contents of messages to +understand whether the response the result of normal behaviour or +needs additional handling. + +Lastly, endpoints can return blobs of several "schemas". For instance, +order messages can have standard reply messages, warning messages, or +error messages, all of different "types". It is up to the user to +handle this logic as well. + +** Paper Trading + +#+CINDEX: Paper Trading + +"Paper trading" is the practice of sending mock trades and being +filled at mock prices to exercise a trading system. Paper trading is +good for getting a feel for how your system behaves before sending +real orders. + +* Scheme Interface + +The IBKR interface really only accept GET and POST requests. GETs +always have an empty body, and POSTs have a JSON body. The headers +expected by the API the same across endpoints. To make requests +easier, we expose the following helpers in scheme. + +#+FINDEX: ibkr-get +~ibkr-get~ (~uri~) + +Returns a GET request for an IBKR endpoint located at ~uri~. + +#+FINDEX: ibkr-post +~ibkr-post~ (~uri~) (~body~) + +Returns a POST request for an IBKR endpoint located at ~uri~ with body +~body~. + +The scheme interface helps build HTTP requests for common actions. All +the helper methods take a ~base~ URI for the location of +gateway. Extra information necessary for specific requests is passed +in as additional arguments. For more details, see the ~(ibkr api)~ +module. + +Useful data structures for interacting with IBKR like orders or +accounts are defined in ~(ibkr types)~. + +Sometimes, it is helpful to make requests manually. For this we offer +two helper functions in addition to ~ibkr-get~ and ~ibkr-post~. + +#+FINDEX: send-ibkr-request +~(send-ibkr-request request)~: sends a request (as constructed by +either ~ibkr-get~ or ~ibkr-post~) to IBKR and returns a pair of the +header and the contents of the response. + +#+FINDEX: v1-api +~(v1-api base)~: returns the "v1" API endpoint relative to the base +URI. + +** Authentication Status + +#+FINDEX: auth-status +~(auth-status base)~: This method simply checks if the current session +is authenticated. + +** Accounts + +#+FINDEX: accounts +~(accounts base)~: Returns as a list the accounts available to the +session. + +** Cash Balance + +#+FINDEX: ledger +~(ledger base account-id currency)~: Returns a "ledger" representing +the cash balance of a current account available in a given +session. Currency types include ~"BASE"~ and ~"USD"~. + +** Positions + +#+FINDEX: positions +~(positions base account-id)~: Returns the open positions of an +account as a list. + +** Security Definitions + +#+FINDEX: stocks-by-symbol +~(stocks-by-symbol base symbol)~: Returns all contracts matching a +given symbol. + +#+FINDEX: first-contract-on-exchange +~(first-contract-on-exchange stocks exchange)~: Returns the first +stock contract on a given exchange. + +These two methods are useful in equity markets for determining the +correct security associated with a given ticker (~symbol~). + +** Market Data Snapshots + +The following methods are exposed to get snapshots of market data in +real time. + +#+FINDEX: contract-snapshot +~(contract-snapshot base contract-id stat)~: Returns the latest +snapshot value of a ~stat~ (as a symbol) for a given ~contract-id~. + +An example to get the latest trade in security "HBB:NYSE" is given +below. + +#+BEGIN_SRC lisp + (use-modules (ibkr api) (ibkr types)) + (define base "http://localhost:5000") + (define hbb (first-contract-on-exchange + (stocks-by-symbol base "HBB") "NYSE")) + (contract-snapshot base (contract-id hbb) 'last-trade) +#+END_SRC + +#+FINDEX: snapshot-field +~(snapshot-field symbol)~: Returns the integer ID that IBKR associates +with a given market data statistic. + +The supported market data snapshot values include: + +- Last Trade ~last-trade~ (31) + +** Submitting Orders + +The "order" data structure helps with sending orders to IBKR. +It requries the following fields: + +- ~account-id~: The ~account-id~ associated with the trade. + +- ~contract-id~: The ~contract-id~ of the symbol being traded. + +- ~type~: ("MARKET", "LIMIT", etc...) + +- ~side~: "BUY" or "SELL" + +- ~tif~: "time-in-force". "IOC" for immediate or cancel. + +- ~quantity~: The quantity associated with the order. + +The order can be constructed with the ~make-order~ method. + +#+FINDEX: make-order +#+BEGIN_SRC lisp +(define ord (make-order "ACCT1234" "5678" "MARKET" "BUY" "IOC" 20)) +#+END_SRC + +This order represents a marketable immediate-or-cancel to purchase 20 +shares of 5678 for account "ACCT1234". + +IBKR allows users to preview orders before sending them. + +#+FINDEX: order-preview +~(order-preview base account-id order)~: Previews the placement of +~order~ for ~account-id~. + +The signature to send an order is identical. + +#+FINDEX: order-submit +~(order-submit base account-id order)~: submit ~order~ for +~account-id~. + +Sometimes the server will respond with a warning when sending an +order. The response message will come with an associated ~reply-id~. +To acknowledge the warning and proceed, use the ~order-confirm~ +method. + +#+FINDEX: order-confirm +~(order-confirm base reply-id)~: confirm the warnings associated with +an order and submit. + +** Reviewing Trades + +We expose the following methods to view the filled and open trades for +a market session. + +#+FINDEX: refresh-live-orders +~(refresh-live-orders base)~: Tells the IBKR API to refresh its cached +listing of live orders. + +#+FINDEX: list-live-orders +~(list-live-orders base)~: Lists the live orders (of all status types) +for the current market session. + +#+FINDEX: set-default-account +~(set-default-account base account-id)~: Sets the account for which +live orders are queried. + +* Indices + +** Concepts +:PROPERTIES: +:INDEX: cp +:END: + +** Data Types +:PROPERTIES: +:INDEX: tp +:END: + +** Functions +:PROPERTIES: +:INDEX: fn +:END: |