Skip to main content

Python bindings for the Cryptowatch API. Cryptocurrency markets, assets, instruments and exchanges data.

Project description

Cryptowatch Python SDK

The Cryptowatch Python library provides a convenient access to the Cryptowatch API from applications written in the Python language.

It includes the following features:

  • Auto-serialization of API responses into Python objects
  • Websocket client with transparent handling of protobuf messages
  • API credentials automatically read from your ~/.cw/credentials.yml config file
  • Custom exceptions for API-specific issues (e.g.: Requests Allowance)
  • Smart back-off retries in case of API connectivity loss

Installation

pip install cryptowatch-sdk

Note:

The cryptowatch library is not related with Cryptowatch. If you installed it by mistake run pip uninstall cryptowatch to remove it.

The correct library name is cryptowatch-sdk.

Example

Showing all Kraken markets that already gained at least 5% over the current weekly candle.

import cryptowatch as cw
from datetime import datetime, timedelta

# Get all Kraken markets
kraken = cw.markets.list("kraken")

# For each Kraken market...
for market in kraken.markets:

    # Forge current market ticker, like KRAKEN:BTCUSD
    ticker = "{}:{}".format(market.exchange, market.pair).upper()
    # Request weekly candles for that market
    candles = cw.markets.get(ticker, ohlc=True, periods=["1w"])

    # Each candle is a list of [close_timestamp, open, high, low, close, volume, volume_quote]
    # Get close_timestamp, open and close from the most recent weekly candle
    close_ts, wkly_open, wkly_close = (
        candles.of_1w[-1][0],
        candles.of_1w[-1][1],
        candles.of_1w[-1][4],
    )

    # Compute market performance, skip if open was 0
    if wkly_open == 0:
        continue
    perf = (wkly_open - wkly_close) * 100 / wkly_open

    # If the market performance was 5% or more, print it
    if perf >= 5:
        open_ts = datetime.utcfromtimestamp(close_ts) - timedelta(days=7)
        print("{} gained {:.2f}% since {}".format(ticker, perf, open_ts))

Requirements

  • python v3.7+
  • requests v0.8.8+
  • marshmallow v3.2.2+
  • pyyaml v5.1.2+
  • websocket-client v0.56+
  • protobuf v3.11.3+

API Crendential

Using a credential file will allow you to authenticate your requests and grant you the API access of your Cryptowatch account.

Your account Credits will be consumed for the REST and WebSocket API. Specific Credit cost details can be found on the Pricing page.

Setup your credential file

  1. Generate an Cryptowatch API key from your account

  2. Create your credential file on your machine by running in order:

    2.1 mkdir $HOME/.cw

    2.2 echo "apikey: 123" > $HOME/.cw/credentials.yml (where 123 is your 20 digits public key)

  3. Verify with cat $HOME/.cw/credentials.yml that you see something like below (123 being your public key):

apikey: 123

The SDK will read your public key as soon as import cryptowatch is ran in your script.

Usage

REST API

import cryptowatch as cw

# Set your API Key, it is by default read from  your ~/.cw/credentials.yml file
cw.api_key = "123"

# Assets
cw.assets.list()
cw.assets.get("BTC")

# Exchanges
cw.exchanges.list()
cw.exchanges.get("KRAKEN")

# Instruments
cw.instruments.list()
cw.instruments.get("BTCUSD")

# Markets
cw.markets.list() # Returns list of all markets on all exchanges
cw.markets.list("BINANCE") # Returns all markets on Binance

# Returns market summary (last, high, low, change, volume)
cw.markets.get("KRAKEN:BTCUSD")
# Return market candlestick info (open, high, low, close, volume) on some timeframes
cw.markets.get("KRAKEN:BTCUSD", ohlc=True, periods=["4h", "1h", "1d"])

# Returns market last trades
cw.markets.get("KRAKEN:BTCUSD", trades=True)

# Return market current orderbook
cw.markets.get("KRAKEN:BTCUSD", orderbook=True)
# Return market current orderbook liquidity
cw.markets.get("KRAKEN:BTCUSD", liquidity=True)

You can access the raw HTTP response received via the _http_response attribute which is a requests.Response object:

import cryptowatch as cw

bitcoin = cw.assets.get('btc')
print(bitcoin._http_response)

Websocket

import cryptowatch as cw

# Set your API Key
cw.api_key = "123"

# Subscribe to resources (https://docs.cryptowat.ch/websocket-api/data-subscriptions#resources)
cw.stream.subscriptions = ["markets:*:trades"]

# What to do on each trade update
def handle_trades_update(trade_update):
    """
        trade_update follows Cryptowatch protocol buffer format:
        https://github.com/cryptowatch/proto/blob/master/public/markets/market.proto
    """
    market_msg = ">>> Market#{} Exchange#{} Pair#{}: {} New Trades".format(
        trade_update.marketUpdate.market.marketId,
        trade_update.marketUpdate.market.exchangeId,
        trade_update.marketUpdate.market.currencyPairId,
        len(trade_update.marketUpdate.tradesUpdate.trades),
    )
    print(market_msg)
    for trade in trade_update.marketUpdate.tradesUpdate.trades:
        trade_msg = "\tID:{} TIMESTAMP:{} TIMESTAMPNANO:{} PRICE:{} AMOUNT:{}".format(
            trade.externalId,
            trade.timestamp,
            trade.timestampNano,
            trade.priceStr,
            trade.amountStr,
        )
        print(trade_msg)


cw.stream.on_trades_update = handle_trades_update


# Start receiving
cw.stream.connect()

# Call disconnect to close the stream connection
# cw.stream.disconnect()

See this script for more streaming example.

Converting protobuf messages to JSON

If you need to convert the protobuf message to JSON, you can do so with MessageToJson. See the example below:

from google.protobuf.json_format import MessageToJson
import cryptowatch as cw

# Set your API Key
cw.api_key = "123"

# Subscribe to resources (https://docs.cryptowat.ch/websocket-api/data-subscriptions#resources)
cw.stream.subscriptions = ["markets:*:trades"]

# What to do on each trade update
def handle_trades_update(trade_update):
    """
        trade_update follows Cryptowatch protocol buffer format:
        https://github.com/cryptowatch/proto/blob/master/public/markets/market.proto
    """
    MessageToJson(trade_update)

cw.stream.on_trades_update = handle_trades_update


# Start receiving
cw.stream.connect()

Logging

Logging can be enabled through Python's logging module:

import logging

logging.basicConfig()
logging.getLogger("cryptowatch").setLevel(logging.DEBUG)

CLI

The library exposes a simple utility, named cryptowatch, to return last market prices.

By default it returns Kraken's BTCUSD market

> cryptowatch
7425.0

Add another Kraken market to return this market last price

> cryptowatch btceur
6758.1

You can also specify your own exchange

> cryptowatch binance:ethbtc
0.020359

When the market doesn't exist a return code of 1 will be set (0 otherwise):

> cryptowatch binance:nosuchmarketusd
> echo $?
1

Testing

Unit tests are under the tests folder and use pytest, run them all with:

make test

Integration tests sending real HTTP requests to the Cryptowatch API can be run with:

make test-http-real

Development

Testing and developement dependencies are in the requirements.txt file, install them with:

pip install -r requirements.txt

The code base use the Black linter, run it with:

make lint

License

BSD-2-Clause

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cryptowatch-sdk-0.0.15.tar.gz (41.8 kB view details)

Uploaded Source

Built Distribution

cryptowatch_sdk-0.0.15-py3-none-any.whl (47.3 kB view details)

Uploaded Python 3

File details

Details for the file cryptowatch-sdk-0.0.15.tar.gz.

File metadata

  • Download URL: cryptowatch-sdk-0.0.15.tar.gz
  • Upload date:
  • Size: 41.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.1

File hashes

Hashes for cryptowatch-sdk-0.0.15.tar.gz
Algorithm Hash digest
SHA256 3db2ce3e1dd18609fe1a1317b873a3540d648238098455eebf3608cb41f33144
MD5 406fa9f7c5b7fab0771cfad6b3b075ad
BLAKE2b-256 381fcd4ef6cfb66b37a6cb900cf1c700308f69d6727aff978be215b8ffc4453d

See more details on using hashes here.

File details

Details for the file cryptowatch_sdk-0.0.15-py3-none-any.whl.

File metadata

  • Download URL: cryptowatch_sdk-0.0.15-py3-none-any.whl
  • Upload date:
  • Size: 47.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.8.1

File hashes

Hashes for cryptowatch_sdk-0.0.15-py3-none-any.whl
Algorithm Hash digest
SHA256 5531a7f038e8e2d527f6e0b9b02f884e290fcbd61732c98c753237526e5c15ed
MD5 0d4d45eefd7af84634b4c3f91d4e49ff
BLAKE2b-256 f3098087e3efa148d95a02763fdd984b9dfde21a00d3cd5d2246b3835f0a2060

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page