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
)
```

# 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

The `cryptoQuotes`-package 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,

<div align="center">
```{r, echo=FALSE}
## available exchanges
invisible(
  all_exchanges <- cryptoQuotes::available_exchanges()
)

# Convert the character vector to a single-row data frame
exchanges_df <- data.frame(t(all_exchanges))

# Set column names to be the exchange names
colnames(exchanges_df) <- all_exchanges

# Create a horizontal table
kableExtra::kable_styling(
  knitr::kable(
    x = exchanges_df, 
    digits = 2,
    col.names = NULL,
    caption = '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

The `cryptoQuotes`-package 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 on [pkgdown](https://serkor1.github.io/cryptoQuotes/).

> **Note:** 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(
  exchange,
  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(
    exchange,
    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
kableExtra::kable_styling(
  knitr::kable(
    digits = 2,
    caption = 'Supported exchanges, markets and intervals.',
    align = 'lccccc',
    table.attr = "style='width:100%;'",
    col.names = c('Exchange', 'Spot', 'Futures', 'Available Intervals' ,'Smallest Interval', 'Biggest Interval'),
    x = data.frame(
      row.names = NULL,
      Exchange  = exchange,
      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))
    ),
    format = 'html'
  ),
  full_width = TRUE,
  position = 'center'
)
```
</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}
## 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() - 1 
)
```

<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 the `cryptoQuotes`-package 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 on [pkgdown](https://serkor1.github.io/cryptoQuotes/). All supported *market indicators* by exchange are listed in the table below,

<div align="center">
```{r, echo = FALSE}
## 1) list all available
## exchanges and the links
available_endpoint <- data.frame(
  Endpoint = c(
    "Long-Short Ratio",
    "Open Interest",
    "Funding Rate"
    ),
  Binance  = c(
    ":white_check_mark:",
    ":white_check_mark:",
    ":white_check_mark:"
    ),
  Bitmart  = c(
    ":x:",
    ":x:",
    ":x:"
    ),
  Bybit    = c(
    ":white_check_mark:",
    ":white_check_mark:",
    ":white_check_mark:"
    ),
  Kraken    = c(
    ":white_check_mark:",
    ":white_check_mark:",
    ":x:"
    ),
  Kucoin    = c(
    ":x:",
    ":x:",
    ":white_check_mark:"
    )
)

## 4) present table
## for as is
kableExtra::kable_styling(
  knitr::kable(
    digits = 0,
    caption = 'Available sentiment indicators by exchange',
    align = 'lccccc',
    table.attr = "style='width:100%;'",
    x = available_endpoint,
    format = 'markdown'
  ),
  full_width = TRUE,
  position = 'center'
)
```
</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}
## 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() - 1 
)
```

<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 the `cryptoQuotes`-package 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()
  )
)
```


<details>
<summary>Colorblind friendly version</summary>
#### Charting with indicators (colorblind friendly)

```{r chartquote(deficiency), fig.align='center', fig.dpi=180, fig.alt="cryptocurrency charts in R"}
## Chart BTC
## using klines, SMA
## Bollinger Bands and 
## ling-short ratio with color-deficiency
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(
    deficiency = TRUE
  )
)
```

__________
</details>

## :information_source: Installation

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

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

## :information_source: Code of Conduct

Please note that the `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.