README.Rmd

---
output: github_document
always_allow_html: true
---
<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r setup, include = FALSE}
# set options
Sys.setenv(OPENSSL_CONF="/dev/null")

knitr::opts_chunk$set(
  collapse = FALSE,
  comment  = "#>",
  fig.path = "man/figures/README-",
  message  = FALSE,
  warning  = FALSE,
  echo     = FALSE 
)
```

# {cryptoQuotes}: Open access to cryptocurrency market data <a href="https://serkor1.github.io/cryptoQuotes/"><img src="man/figures/logo.png" align="right" height="154" alt="cryptocurrency in R"/></a>

<!-- badges: start -->
[![CRAN status](https://www.r-pkg.org/badges/version/cryptoQuotes)](https://CRAN.R-project.org/package=cryptoQuotes)
[![CRAN RStudio mirror downloads](https://cranlogs.r-pkg.org/badges/last-month/cryptoQuotes?color=blue)](https://r-pkg.org/pkg/cryptoQuotes)
[![R-CMD-check](https://github.com/serkor1/cryptoQuotes/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/serkor1/cryptoQuotes/actions/workflows/R-CMD-check.yaml)
[![codecov](https://codecov.io/gh/serkor1/cryptoQuotes/graph/badge.svg?token=D7NF1BPVL5)](https://app.codecov.io/gh/serkor1/cryptoQuotes)
[![Lifecycle: stable](https://img.shields.io/badge/lifecycle-stable-brightgreen.svg)](https://lifecycle.r-lib.org/articles/stages.html#stable)
![GitHub last commit (branch)](https://img.shields.io/github/last-commit/serkor1/cryptoQuotes/development)
<!-- badges: end -->

## :information_source: About

[{cryptoQuotes}](https://serkor1.github.io/cryptoQuotes/) is a high-level API client for accessing public market data endpoints on major cryptocurrency exchanges. It supports open, high, low, close and volume (OHLC-V) data and a variety of sentiment indicators; the market data is high quality and can be retrieved in intervals ranging from *seconds* to *months*. All the market data is accessed and processed without relying on crawlers, or API keys, ensuring an open, and reliable, access for researchers, traders and students alike. There are currently `r length(invisible(cryptoQuotes::available_exchanges(type = "ohlc")))` supported cryptocurrency exchanges,

```{r Exchanges (Raw),include=FALSE, echo=FALSE}
# 1) create a data.table of available
# exchanges and store as dat.table
DT <- data.table::data.table(
  value = suppressMessages(
    cryptoQuotes::available_exchanges()
  )
)

# 2) add labels
# to the data data
DT[
  ,
  label := data.table::fcase(
    value == "binance", "Binance",
    value == "kraken", "Kraken",
    value == "crypto.com", "Crypto.com",
    value == "kucoin", "KuCoin",
    value == "bitmart", "BitMart",
    value == "huobi", "Huobi (HTX)",
    value == "mexc", "MEXC",
    value == "bybit", "Bybit"
  )
  ,
]

```


<div align="center">
```{r Exchanges (Table), echo=FALSE}
# 1) define all available
# exchanges
all_exchanges <- DT$label

if (length(DT$label) %% 2 != 0) {
  # If odd, append an empty string to make it even
  all_exchanges <- c(DT$label, "")
}

# Convert the character vector to a single-row data frame
all_exchanges <- data.table::data.table(
  matrix(
    data = all_exchanges, 
    ncol = 4,
    byrow = TRUE)
)

# Create a horizontal table
kableExtra::kable_styling(
  knitr::kable(
    x = all_exchanges, 
    digits = 2,
    col.names = NULL,
    caption = 'All supported exchanges.',
    align = 'c',
    table.attr = "style='width:100%;'",
    format = 'html'
  ),
  full_width = TRUE,
  position = 'center'
)
```
</div>

All data is returned as [{xts}](https://github.com/joshuaulrich/xts)-objects which enables seamless interaction with with [{quantmod}](https://github.com/joshuaulrich/quantmod) and [{TTR}](https://github.com/joshuaulrich/TTR), for developing and evaluating trading strategies or general purpose cryptocurrency market analysis with a historical or temporal perspective. 

## :information_source: Overview

[{cryptoQuotes}](https://serkor1.github.io/cryptoQuotes/) has *two* main features; retrieving cryptocurrency market data, and charting. The market data consists of *OHLC-V* data and sentiment indicators; including, but not limited to, cryptocurrency *fear and greed index*, *long-short ratio* and *open interest*. All market data is retrieved using the family of `get_*`-functions. To get a full overview of the package and functionality please see the documentation via [{pkgdown}](https://serkor1.github.io/cryptoQuotes/).

> [!WARNING]
>
> Given the nature of crypotcurrency data and general legislative restrictions, some `exchanges` may not work in your geolocation.

Below is a quick overview of the package and basic usage examples on retrieving and charting Bitcoin (BTC) *OHLC-V* and *long-short ratio* in 30 minute intervals.

### :information_source: Cryptocurrency market data

#### OHLC-V

All supported exchanges and markets are listed in the table below, alongside the available range of intervals available from the respective exchanges,

<div align="center">
```{r supported calls, echo=FALSE,fig.alt="Cryptocurrency market data in R"}
# function to make 
# first letter uppercase without
# declaring dependency on stringr
# Thank you Stackoverflow
# https://stackoverflow.com/a/18509816
firstup <- function(x) {
  substr(x, 1, 1) <- toupper(substr(x, 1, 1))
  x
}

sort_granularities <- function(granularity_vector) {
  # Define a custom ordering based on granularity
  custom_order <- c("s","m", "h", "d", "w", "M")
  
  # Extract numeric and non-numeric parts
  numeric_part <- as.numeric(gsub("[^0-9]", "", granularity_vector))
  non_numeric_part <- gsub("[0-9]", "", granularity_vector)
  
  # Map non-numeric part to custom order
  non_numeric_part_order <- match(non_numeric_part, custom_order)
  
  # Create a sorting index
  sorting_index <- order(non_numeric_part_order, numeric_part)
  
  # Sort the vector
  sorted_granularity_vector <- granularity_vector[sorting_index]
  
  return(sorted_granularity_vector)
}

# 1) Supported Exchanges
# sorted alphabetically
exchange <- firstup(
  sort(
    suppressMessages(
      cryptoQuotes::available_exchanges()
    )
  )
)


# 2) calculate available
# intervals
intervals <- sapply(
  DT$value,
  function(x){
    suppressMessages(
      {
        futures = cryptoQuotes::available_intervals(
          type   = 'ohlc',
          source = tolower(x),
          futures = TRUE
        )
        
        spot = cryptoQuotes::available_intervals(
          type   = 'ohlc',
          source = tolower(x),
          futures = FALSE
        )
        
      }
    )
    
    
    
    length(union(futures, spot))
    
  }
)


# 2) calculate available
# intervals
granularity <- function(
    lowest = TRUE
)
{
  sapply(
    DT$value,
    function(x){
      suppressMessages(
        {
          futures = cryptoQuotes::available_intervals(
            source = tolower(x),
            futures = TRUE
          )
          
          spot = cryptoQuotes::available_intervals(
            source = tolower(x),
            futures = FALSE
          )
          
        }
      )
      
      available_granularity <- sort_granularities(union(
        futures,
        spot
      ))
      
      
      if (lowest) {
        
        output <- available_granularity[1]
        
        
        
      } else {
        
        output <- available_granularity[length(available_granularity)]
        
      }
      
      
      output <- gsub("(.)(.)", "\\1 \\2", output)
      
      output <- strsplit(
        output,
        split = " "
      )[[1]]
      
      
      number <- output[1]
      
      granularity <- switch(
        EXPR = output[2],
        s = "second(s)",
        m = "minute(s)",
        h = "hour(s)",
        w = "week(s)",
        d = "day(s)",
        M = "month(s)"
      )
      
      paste(number, granularity)
      
    }
  )
}

# 2) create
# table
gt::as_raw_html(
  gt::fmt_markdown(
    gt::cols_label(
     gt::cols_align(
      data = gt::gt(
        data.frame(
          row.names = NULL,
          Exchange  = DT$label,
          Spot = rep(x = ":white_check_mark:",length(exchange)),
          Futures = rep(x = ":white_check_mark:",length(exchange)),
          `Available Intervals` = c(intervals),
          `Smallest Interval` = c(granularity(TRUE)),
          `Biggest Interval` = c(granularity(FALSE))
        ),
        auto_align = FALSE,
        caption = 'Supported exchanges by spot and futures markets with available intervals.'),
      align = "left",
      columns = "Exchange"
      
    ),
    Available.Intervals = "Available Intervals",
    Smallest.Interval   = "Smallest Interval",
    Biggest.Interval    = "Biggest Interval"
    )
    
    
  )
)
```
</div>

<details>
<summary>Example: Bitcoin OHLC-V</summary>

Get USDT denominated Bitcoin (BTC) on the spot market from Binance in `30m`-intervals using the `get_quote()`-function,

```{r cryptocurrency market data in R, eval=TRUE, echo=TRUE}
## BTC OHLC prices
## from Binance spot market
## in 30 minute intervals
BTC <- cryptoQuotes::get_quote(
  ticker   = 'BTCUSDT',
  source   = 'binance',
  futures  = FALSE,
  interval = '30m',
  from     = Sys.Date() - 2
)
```

<div align="center">
```{r print table, echo=FALSE, fig.alt="cryptocurrency prices in R"}
kableExtra::kable_styling(
  knitr::kable(
    caption = 'Bitcoin (BTC) OHLC-V data',
    align = 'lcccc',
    table.attr = "style='width:100%;'",
    x = data.frame(
      cbind(
        index = paste(tail(zoo::index(BTC))),
        tail(zoo::coredata(BTC))
      ),row.names = NULL
    ),
    format = 'html'
  ),
  full_width = TRUE,
  position = 'center'
)
```
</div>
__________
</details>

#### Sentiment indicators

The sentiment indicators available in [{cryptoQuotes}](https://serkor1.github.io/cryptoQuotes/) can be divided in two; *derived indicators* and *market indicators*. The former is calculated based on, for example, the price actions such as the *Moving Average Convergence Divergence* (MACD) indicator. The latter are public indicators such as the *long-short ratio* or *fear and greed index*; these are retrieved using the family of `get_*`-functions, while the derived indicators can be created using, for example, [{TTR}](https://github.com/joshuaulrich/TTR).

In this overview we are focusing on *market indicators* made public by the cryptocurrency exchanges. For a full overview of sentiment indicators please refer to the documentation via [{pkgdown}](https://serkor1.github.io/cryptoQuotes/). All supported *market indicators* by exchange are listed in the table below,

<div align="center">
```{r Available Endpoints by Exchange, echo = FALSE}
## 0) Get all available
## endpoints
endpoint_label <- c("Long-Short Ratio", "Open Interest", "Fundingrate")
endpoint_value <- c(         "lsratio",      "interest", "fundingrate")
all_exchanges  <- DT$value

DT_ <- data.table::rbindlist(
  lapply(
    seq_along(all_exchanges),
    FUN = function(i) {
      
      # 0) extract exchange
      exchange <- all_exchanges[i]
      
      data.table::rbindlist(
        lapply(
          seq_along(endpoint_value),
          FUN = function(j) {
            
            
            # 0) generate table
            DT <- data.table::data.table(
              order    = j,
              Exchange = DT$label[i],
              Endpoint = endpoint_label[j]
            )
            
            DT[
              ,
              available := data.table::fifelse(
                test = exchange %in% suppressMessages(cryptoQuotes::available_exchanges(endpoint_value[j])),
                yes  = ":white_check_mark:",
                no   =  ":x:"
              )
              ,
            ]
            
            DT
            
            
          }
        )
      )
      
      
      
      
    }
  )
)

DT_ <- data.table::dcast(
  data = DT_,
  formula = order +  Endpoint ~ Exchange,
  value.var = "available"
)
DT_$order <- NULL

## 4) present table
## for as is
gt::as_raw_html(
  gt::fmt_markdown(
    gt::cols_align(
      data = gt::gt(
        DT_,
        auto_align = FALSE,
        caption = 'Available sentiment indicators by exchange'),
      align = "left",
      columns = "Endpoint"
      
    )
    
  )
)
```
</div>

<details>
<summary>Example: Bitcoin Long-Short Ratio</summary>

Get the *long-short ratio* on Bitcoin (BTC) using the `get_lsratio()`-function,

```{r cryptocurrency sentiment indicators in R, eval=TRUE, echo=TRUE}
## BTC OHLC prices
## from Binance spot market
## in 30 minute intervals
BTC_LS <- cryptoQuotes::get_lsratio(
  ticker   = 'BTCUSDT',
  source   = 'binance',
  interval = '30m',
  from     = Sys.Date() - 2
)
```

<div align="center">
```{r print LS table, echo=FALSE, fig.alt="cryptocurrency prices in R"}
kableExtra::kable_styling(
  knitr::kable(
    caption = 'Long-Short Ratio on Bitcoin (BTC)',
    align = 'lccc',
    table.attr = "style='width:100%;'",
    x = data.frame(
      cbind(
        index = paste(tail(zoo::index(BTC_LS))),
        tail(zoo::coredata(round(BTC_LS,3)))
      ),row.names = NULL
    ),
    format = 'html'
  ),
  full_width = TRUE,
  position = 'center'
)
```
</div>
__________
</details>

### :information_source: Charting

```{r, echo=FALSE, include=FALSE}
## Chart BTC
## using klines, SMA, 
## MACD and Bollinger Bands
cryptoQuotes::chart(
  ticker = BTC,
  main   = cryptoQuotes::kline(),
  sub    = list(
    cryptoQuotes::lsr(ratio = BTC_LS),
    cryptoQuotes::volume()
  ),
  indicator = list(
    cryptoQuotes::sma(n = 7),
    cryptoQuotes::sma(n = 14),
    cryptoQuotes::sma(n = 21),
    cryptoQuotes::bollinger_bands()
  )
)
```

Charting in [{cryptoQuotes}](https://serkor1.github.io/cryptoQuotes/) is built on [{plotly}](https://github.com/plotly/plotly.R) for interactivity. It supports *light* and *dark* themes, and accounts for *color-deficiency* via the `options`-argument in the `chart()`-function.

#### Charting with indicators

The OHLC-V data and the sentiment indicator can be charted using the `chart()`-function,

```{r chartquote, fig.align='center',fig.dpi=180, fig.alt="cryptocurrency charts in R"}
## Chart BTC
## using klines, SMA
## Bollinger Bands and
## long-short ratio
cryptoQuotes::chart(
  ticker = BTC,
  main   = cryptoQuotes::kline(),
  sub    = list(
    cryptoQuotes::lsr(ratio = BTC_LS),
    cryptoQuotes::volume()
  ),
  indicator = list(
    cryptoQuotes::sma(n = 7),
    cryptoQuotes::sma(n = 14),
    cryptoQuotes::sma(n = 21),
    cryptoQuotes::bollinger_bands()
  ),
  options = list(
    static     = TRUE
  )
)
```

<details>
<summary>Source</summary>

```{r chartquote (Source),echo=TRUE, fig.align='center',fig.dpi=180, fig.alt="cryptocurrency charts in R", eval=FALSE}
## Chart BTC
## using klines, SMA
## Bollinger Bands and
## long-short ratio
cryptoQuotes::chart(
  ticker = BTC,
  main   = cryptoQuotes::kline(),
  sub    = list(
    cryptoQuotes::lsr(ratio = BTC_LS),
    cryptoQuotes::volume()
  ),
  indicator = list(
    cryptoQuotes::sma(n = 7),
    cryptoQuotes::sma(n = 14),
    cryptoQuotes::sma(n = 21),
    cryptoQuotes::bollinger_bands()
  ),
  options = list(
    static     = TRUE
  )
)
```

</details>

## :information_source: Installation

### :shield: Stable version
```{r stable version guide, eval = FALSE, echo=TRUE}
## install from CRAN
install.packages(
  pkgs = 'cryptoQuotes',
  dependencies = TRUE
)
```

### :hammer_and_wrench: Development version
```{r development version guide, eval = FALSE,echo=TRUE}
## install from github
devtools::install_github(
  repo = 'https://github.com/serkor1/cryptoQuotes/',
  ref  = 'development'
)
```

## :information_source: Code of Conduct

Please note that the [{cryptoQuotes}](https://serkor1.github.io/cryptoQuotes/) project is released with a [Contributor Code of Conduct](https://serkor1.github.io/cryptoQuotes/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms.