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: