R/get_orderbook.R

In lorenzbr/cryptowatchR: An API Wrapper for 'Cryptowatch'

#' Get order book of cryptocurrencies
#'
#' Get the order book of cryptocurrencies using the REST API of cryptowat.ch.
#' The route is \emph{orderbook} and returns two arrays, bids and asks.
#' See \url{https://docs.cryptowat.ch/rest-api/markets/order-book} for further
#' information.
#'
#' @usage get_orderbook(pair, depth = NULL, span = NULL, limit = NULL,
#'               exchange = "kraken", api_key = NULL, allowance = FALSE)
#' @param pair A string containing a pair symbol, e.g. \emph{btcusd} (required
#' argument). Run \code{get_pairs()} to find other available pairs.
#' @param depth A number: Only return orders cumulating up to this size (optional).
#' @param span A number: Only return orders within this percentage of the
#' midpoint (optional). Example: 0.5 (meaning 0.5 percent).
#' @param limit An integer limiting the number of orders on each side of the
#' book (optional).
#' @param exchange A character string containing the exchange. Default is
#' \emph{kraken}. Run \code{get_exchanges()} to find other available exchanges.
#' @param api_key A character string containing the API key. See
#' \url{https://docs.cryptowat.ch/rest-api/rate-limit} to learn how to create
#' an account and how to generate an API key.
#' @param allowance A logical (default is \code{FALSE}). If \code{TRUE} the
#' function returns a list which includes allowance information, i.e. cost of
#' the request, remaining credits and your account name.
#'
#' @return A list containing an order book of a given pair of currencies. It
#' contain two data frames for bid and ask prices with columns \emph{Price} and
#' \emph{Amount}. The function also returns the sequence number \emph{seqNum}.
#' If allowance is \code{TRUE}, \code{get_orderbook()} returns a list which
#' additionally includes allowance information.
#'
#' @references See \url{https://docs.cryptowat.ch/rest-api} for further information.
#' @seealso \code{\link{get_markets}}, \code{\link{get_orderbook_liquidity}},
#' \code{\link{get_exchanges}}, \code{\link{get_pairs}}
#' @examples
#' \dontrun{
#' # Entire order book of Bitcoin in USD
#' orderbook <- get_orderbook("btcusd")
#' # Order book of Bitcoin in USD: only the best bid and best ask, i.e. the spread
#' orderbook_limit <- get_orderbook("btcusd", limit = 1)
#' # Order book of Bitcoin in USD for orders within 0.5% of the top of the book
#' orderbook_span <- get_orderbook("btcusd", span = 0.5)
#' # Order book of Bitcoin in Euro for orders adding up to 100 BTC on each side
#' orderbook_depth <- get_orderbook("btceur", depth = 100)
#' }
#'
#' @export
get_orderbook <- function(pair, depth = NULL, span = NULL, limit = NULL,
                          exchange = "kraken", api_key = NULL,
                          allowance = FALSE) {

  params <- list(depth = depth, span = span, limit = limit)

  orderbook <- get_markets(route = "orderbook", pair, exchange,
                           params, api_key, allowance)

  if (allowance) {

    allowance_list <- orderbook[[2]]
    orderbook <- orderbook[[1]]

  }

  asks <- data.frame(orderbook$asks)
  df_asks <- data.frame(Price = asks$X1, Amount = asks$X2)

  bids <- data.frame(orderbook$bids)
  df_bids <- data.frame(Price = bids$X1, Amount = bids$X2)

  seqNum <- orderbook$seqNum

  result <- list(asks = df_asks, bids = df_bids, seqNum = seqNum)

  if (allowance) {

    output <- list(result = result, allowance = allowance_list)

  } else if (allowance == FALSE) {

    output <- result

  }

  return(output)

}