tlab-trading-toolkit

--- title: Introduction to the Live orderbook keywords: GTT, feed data, exchange, GDAX, orderbook last_updated: August 15, 2017 tags: [getting_started, tutorials] summary: "Producing a live orderbook" sidebar: gtt_sidebar permalink: gtt_tutorials_liveorderbook.html folder: gtt --- ## Introduction The Live Orderbook will lie at the heart of almost any real-world trading bot or algorithm. In this tutorial, we illustrate the steps to hook a LiveOrderbook instance up to a message feed and to start extracting information from it. ## Configuration The [LiveOrderbook class](apiref/modules/_src_core_liveorderbook_.html) configuration object has only one required field: `product`. Since an orderbook represents a single trading pair, any message with a product ID other than `product` will be filtered out. The other config options are `logger`, to pass a global [Logger](apiref/modules/_src_utils_logger_.html) object to the orderbook; and `strictMode`, a boolean, that determines the behavior when a skipped message is detected. `LiveOrderbook` is a writable stream, so once you have a feed message stream, and applied whatever filters and transformers to it that you like, you can pipe it straight in and the orderbook will update itself automatically. A standard template for creating and configuring a LiveOrderbook looks like this: import * as GTT from 'gdax-trading-toolkit'; const products = ['LTC-USD']; const logger = GTT.utils.ConsoleLoggerFactory({ level: 'debug' }); GTT.Factories.GDAX.FeedFactory(logger, products).then((feed: GDAXFeed) => { // Configure the live book object const config: LiveBookConfig = { product: product, logger: logger }; const book = new LiveOrderbook(config); feed.pipe(book); ... }); ## Orderbook messages `LiveOrderbook` emits an array of messages in response to certain events. | Event tag | Emitted when | Data provided | |-----------|--------------|---------------| | LiveOrderbook.update | The orderbook changes due to a new order, a cancelled order, or a trade | A descendant of [OrderbookMessage](apiref/interfaces/_src_core_messages_.orderbookmessage.html) causing the change | | LiveOrderbook.trade | a trade occurs | A [TradeMessage](apiref/interfaces/_src_core_messages_.trademessage.html) describing the trade | | LiveOrderbook.ticker | Whenever the ticker is updated | A [TickerMessage](apiref/interfaces/_src_core_messages_.tickermessage.html) instance | | LiveOrderbook.snapshot | When an orderbook snapshot is received, usually immediately after subscribing to the message feed. | The [SnapshotMessage](apiref/interfaces/_src_core_messages_.snapshotmessage.html) | | LiveOrderbook.skippedMessage | if a sequencing error in the message feed is detected. | A [SkippedMessageEvent](apiref/interfaces/_src_core_liveorderbook_.skippedmessageevent.html)| | error | An unrecoverable error occurs | The `Error` object | ## Orderbook methods and properties All the orderbook methods and properties are near-realtime. You can query the last update time with `book.timeSinceTickerUpdate` or `book.timeSinceOrderbookUpdate` which returns the time (is seconds) since the last update to the orderbook. Some of the handy properties available on `LiveOrderbook` are: | Property | Type | Description | |----------|------|-------------| | sourceSequence | number | The last known sequence number from the underlying feed, if it exists. Some websocket feeds don't supply sequences, for example. | | sequence | number | The sequence number as generated by the connected feed source. It may or may not correspond to `sourceSequence` | | numAsks | number | The number of orders on the sell side of the book | | numBids | number | The number of orders on the buy side of the book | | asksTotal | BigJS | The total value of the sell side of the book (in base currency) | | bidsTotal | BigJS | The total value of the buy side of the book (in base currency) | | book | BookBuilder | Provides access to the underlying book builder. Note: Modifying the book will cause the `LiveOrderbook` to go out of sync. | | ticker | Ticker | Returns the latest ticker information about the book | | baseCurrency | string | The base currency for the trading pair (e.g. BTC in BTC-USD) | | quoteCurrency | string | The quote currency for the trading pair (e.g. USD in BTC-USD) | ### ordersForValue `ordersForValue` is probably the most useful method in `liveOrderbook`. It allows you to query the orderbook to determine which orders would be filled for a given trade. This comes in useful for calculating things like average price, slippage and various other metrics for liquidity that are important for algorithmic trading. The function takes a side ('buy' or 'sell') and a value and returns the orders that would be filled by that trade. However, it also returns the cumulative size and cost/value of the trade at each level, from which all the liquidity metrics can be derived. The 3rd and 4th arguments to `ordersForValue` modify the interpretation of the trade. `useQuote` instructs the method to interpret `value` in quote currency rather than base currency. And `startingPoint` allows you to specify an offset value (by default it is zero). This allows you to calculate order tranches (the first 100 BTC, the second 100 BTC etc). ## Try it out Given a running LiveOrderbook instance, the following snippet console.log(`Number of bids: ${book.numBids} asks: ${book.numAsks}`); console.log(`Total ${book.baseCurrency} liquidity: ${book.bidsTotal.toFixed(3)} asks: ${book.asksTotal.toFixed(3)}`); let orders: CumulativePriceLevel[] = book.ordersForValue('buy', 100, false); console.log(`Cost of buying 100 ${book.baseCurrency}: ${orders[orders.length - 1].cumValue.toFixed(2)} ${book.quoteCurrency}`); orders = book.ordersForValue('sell', 1000, true); console.log(`Need to sell ${orders[orders.length - 1].cumSize.toFixed(3)} ${book.baseCurrency} to get 1000 ${book.quoteCurrency}`); would produce output similar to Number of bids: 1849 asks: 2297 Total LTC liquidity: 4004381.314 asks: 172100.402 Cost of buying 100 LTC: 4299.23 USD Need to sell 23.278 LTC to get 1000 USD To respond to orderbook messages, simple add an event listener to the book. To respond to ticker events you can do something like book.on('LiveOrderbook.ticker', (ticker: Ticker) => { console.log(ticker); }); And to track total trading volume since connecting, you would have let tradeVolume: number = 0; book.on('LiveOrderbook.trade', (trade: TradeMessage) => { tradeVolume += +(trade.size); }); A full working example can be found in the repository, in `tutorials/t002_liveOrderbook.ts`. It can be executed by running $ ts-node src/tutorials/t002_liveOrderbook.ts to obtain output similar to 2017-08-15T20:35:56.317Z - info: Creating new GDAX Websocket connection to wss://ws-feed.gdax.com 2017-08-15T20:35:57.661Z - debug: Connection to wss://ws-feed.gdax.com has been established. 2017-08-15T20:35:57.662Z - debug: Sending subscribe message to WS server 2017-08-15T20:35:58.697Z - info: Snapshot received by LiveOrderbook Demo Price: 42.89 | Bid: 42.89 | Ask: 42.90 | sequence: 4282257 Orderbook 266 1.3168 1.3168 $ 42.89 $ 42.90 3.8946 3.8946 67.3168 66.0000 $ 42.88 $ 42.91 1.0826 4.9772 67.3268 0.0100 $ 42.87 $ 42.92 1.0000 5.9772 97.3919 30.0652 $ 42.86 $ 42.94 0.1392 6.1164 117.4271 20.0352 $ 42.85 $ 42.95 0.9465 7.0629 160.4720 43.0449 $ 42.84 $ 42.96 52.4897 59.5527 182.9364 22.4644 $ 42.83 $ 42.97 5.8179 65.3706 182.9713 0.0349 $ 42.82 $ 42.98 11.7460 77.1166 223.0063 40.0349 $ 42.81 $ 42.99 7.4361 84.5527 1225.8337 1002.8275 $ 42.80 $ 43.00 213.4548 298.0075 Number of bids: 1846 asks: 2300 Total LTC liquidity: 4025988.612 asks: 171302.649 Cost of buying 100 LTC: 4296.80 USD Need to sell 1000.000 LTC to get 1000 USD 2017-08-15T20:36:03.704Z - info: Cumulative trade volume: 27.9451 Orderbook 409 1.3168 1.3168 $ 42.89 $ 42.90 3.8946 3.8946 26.3168 25.0000 $ 42.88 $ 42.91 1.0826 4.9772 56.3268 30.0100 $ 42.87 $ 42.92 1.0000 5.9772 ...