# Introduction: Cryptocurrency Market Data in R

    library(cryptoQuotes)

This `vignette` is a short introduction to the `cryptoQuotes`-package, for a more extensive introduction on its usecase and limitations please refer to the wiki.

> NOTE: This `vignette` is limited by geolocation due to various country specific cryptocurrency laws. The introduction, therefore, is limited to what is available in the US.

Throughout this `vignette` we will explore the Bitcoin market data using the `Kraken` exchange. All available `tickers` and its notation various across exchangs, so if you are unfamiliar with the exchange specific notation please use the `available_intervals()`-functions,

    # show a sample of
    # the available tickers
    sample(
      x = available_tickers(
        source  = "kraken",
        futures = FALSE
      ),
      size = 5
    )
    #> [1] "SBRUSD"  "WOOUSD"  "GRTUSD"  "KSMUSD"  "STRKUSD"

These available tickers can be passed into the `ticker`-argument of all the `get_*`-functions with the appropriate `source` and `futures`-argument which, in this case, is `kraken` and `FALSE`.

## Cryptocurrency market data in R

### Open, High, Low, Close an Volume

We will extract the Bitcoin market data in `hourly` intervals, and store it as `BTC`,

    ## extract Bitcoin
    ## market on the hourly
    ## chart
    BTC <- get_quote(
      ticker   = "XBTUSDT",
      source   = "kraken",
      futures  = FALSE,
      interval = "1h"
    )

    #>                        open    high     low   close    volume
    #> 2024-05-31 17:00:00 67483.0 67506.0 67261.6 67261.6  9.119218
    #> 2024-05-31 18:00:00 67255.7 67255.7 66692.3 67188.8 26.041747
    #> 2024-05-31 19:00:00 67176.7 67449.1 67165.7 67344.1  4.485146
    #> 2024-05-31 20:00:00 67360.1 67431.0 67200.0 67411.7  3.443449
    #> 2024-05-31 21:00:00 67406.1 67948.0 67361.9 67660.4  5.423839
    #> 2024-05-31 22:00:00 67672.2 67792.7 67597.9 67755.4  3.278028

The market data can be extracted in different intervals using the `interval`-argument. To see available intervals, the `available_intervals()`-function can be used,

    ## get available
    ## intervals for OHLC
    ## on Kraken
    available_intervals(
      source  = "kraken",
      type    = "ohlc",
      futures = FALSE
    )
    #> ℹ Available Intervals at "kraken" (spot):
    #> ✔ 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w, 2w

### Sentiment Data

To put the Bitcoin price action in perspective, an interesting sentiment indicator like the `long` to `short` ratio can be extracted,

    ## extract long-short
    ## ratio on Bitcoin
    ## using the hourly chart
    LS_BTC <- try(
       get_lsratio(
        ticker   = "XBTUSDT",
        source   = "kraken",
        interval = "1h"
      )
    )
    #> Error in (function (..., row.names = NULL, check.rows = FALSE, check.names = TRUE,  :
    #>   arguments imply differing number of rows: 0, 1

This gives an `error`. The source of the error is the ticker-naming convention; as the `long` to `short` ratio is specific to the perpetual futures market, and the current ticker is specific to the spot-market, the endpoint throws an error.

To circumvent this, we can either use perpetual futures throughout the `script`, or modify the `ticker`-argument as follows,

    ## extract long-short
    ## ratio on Bitcoin
    ## using the hourly chart
    LS_BTC <- get_lsratio(
      ticker   = "PF_XBTUSD",
      source   = "kraken",
      interval = "1h"
    )

    #>                       long  short ls_ratio
    #> 2024-05-31 17:00:00 0.7526 0.2474 3.042037
    #> 2024-05-31 18:00:00 0.7463 0.2537 2.941663
    #> 2024-05-31 19:00:00 0.7504 0.2496 3.006410
    #> 2024-05-31 20:00:00 0.7507 0.2493 3.011231
    #> 2024-05-31 21:00:00 0.7541 0.2459 3.066694
    #> 2024-05-31 22:00:00 0.7452 0.2548 2.924647

The `ticker` specific to the perpetual futures market can be extracted using the `available_tickers` with `futures = TRUE` as follows,

    # show a sample of
    # the available tickers
    sample(
      x = available_tickers(
        source  = "kraken",
        futures = TRUE
      ),
      size = 5
    )
    #> [1] "PF_PEPEUSD"       "PF_UMAUSD"        "PF_ICPUSD"        "PF_XBTUSD"
    #> [5] "FI_XBTUSD_240628"

## Charting cryptocurrency market data

The Bitcoin market data can be charted using the `chart()`-function, which uses `plotly` as backend,

    # candlestick chart with
    # volume and Long to Short Ratio
    chart(
      ticker = BTC,
      main   = kline(),
      sub    = list(
        volume(),
        lsr(ratio = LS_BTC)
      ),
      options = list(
        dark = FALSE
      )
    )

### Adding indicators

The `cryptoQuotes`-package also acts as an API-client to the `TTR`-package, and supports most of its functions. We can add Moving Average indicators, and bollinger bands to the chart using the `indicator`-argument,

    # candlestick chart with
    # volume and Long to Short Ratio
    chart(
      ticker = BTC,
      main   = kline(),
      sub    = list(
        volume(),
        lsr(ratio = LS_BTC)
      ),
      indicator = list(
        sma(n = 7),
        sma(n = 14),
        sma(n = 21),
        bollinger_bands(
          color = "steelblue"
        )
      ),
      options = list(
        dark = FALSE
      )
    )