blockfacts-sdk 1.0.3

Official BlockFacts Python SDK including Rest and WebSocket API support

BlockFacts Python SDK

Official BlockFacts Python SDK including Rest and WebSocket API support.

Features

• REST API client with a function wrapper for easy API access
• WebSocket API client for real-time data gathering

Note: In order to read more and get richer details regarding our REST and WebSocket APIs, please refer to our official docs: https://docs.blockfacts.io.

• Installation
• Quick start
• Using Rest API Client
• Asset endpoints
• BlockFacts endpoints
• Exchange endpoints
• Using WebSocket API Client

Installation

$ pip install blockfacts-sdk

Quick start

To start using our SDK just import the package and pass the API-KEY and API-SECRET in the constructor.

from blockfacts import RestClient 
from blockfacts import WebsocketClient 

key = 'your-api-key'
secret = 'your-api-secret'

restClient = RestClient(key, secret)
websocketClient = WebsocketClient(key, secret)

Using Rest API Client

In the examples below, you can see which method is mapped to call it's predefined endpoint. You can also read more about authorization and how to obtain an API Key here: https://docs.blockfacts.io/?python#authorization

Asset endpoints

List all assets

Get all assets that we support.

• listAllAssets()

jsonResponse = restClient.assets.listAllAssets()

Get specific asset

Get specific asset by ticker ID.

• getSpecificAsset(tickerId)

jsonResponse = restClient.assets.getSpecificAsset("BTC")

BlockFacts endpoints

Exchanges in normalization

List exchanges that go into the normalization for specific asset-denominator pair.

• getExchangesInNormalization(pairs)

jsonResponse = restClient.blockfacts.getExchangesInNormalization(["BTC-USD", "ETH-USD"])

# OR

jsonResponse = restClient.blockfacts.getExchangesInNormalization("BTC-USD, ETH-USD")

Current data

Get current normalization data for specific asset-denominator pair.

• getCurrentData(assets, denominators)

jsonResponse = restClient.blockfacts.getCurrentData(["BTC", "ETH"], ["USD", "EUR"])

# OR

jsonResponse = restClient.blockfacts.getCurrentData("BTC, ETH", "USD, EUR")

Snapshot data

Get last 600 BlockFacts normalized prices for provided asset-denominator pairs.

• getSnapshotData(assets, denominators)

jsonResponse = restClient.blockfacts.getSnapshotData(["BTC", "ETH"], ["USD", "EUR"])

# OR

jsonResponse = restClient.blockfacts.getSnapshotData("BTC, ETH", "USD, EUR")

OHLCV Snapshot data

Gets the snapshot of Blockfacts OHLCV data for provided asset-denominator pairs and intervals.

• getOHLCVSnapshotData(assets, denominators, intervals)

jsonResponse = restClient.blockfacts.getOHLCVSnapshotData(["BTC", "ETH"], ["USD", "EUR"], ["30s", "1m", "1h"])

# OR

jsonResponse = restClient.blockfacts.getOHLCVSnapshotData("BTC, ETH", "USD, EUR", "30s, 1m, 1h")

Note: You can find all supported intervals on our official documentation here: https://docs.blockfacts.io/?python#data-snapshot-ohlcv-blockfacts

Historical data

Get historical normalization data by asset-denominator, date, time and interval.

• getHistoricalData(asset, denominator, date, time, interval, page)

jsonResponse = restClient.blockfacts.getHistoricalData("BTC", "USD", "2.9.2019", "14:00:00", 20)

# OR with page parameter (optional)

jsonResponse = restClient.blockfacts.getHistoricalData("BTC", "USD", "2.9.2019", "14:00:00", 20, 3)

OHLCV Historical data

Get historical OHLCV data by asset-denominator, date, time and interval.

• getHistoricalOHLCVData(asset, denominator, interval, dateStart, timeStart, dateEnd, timeEnd, page)

jsonResponse = restClient.blockfacts.getHistoricalOHLCVData("BTC", "USD", "1d", "5.8.2020", "14:00:00", "10.8.2020", "14:00:00")

# OR with page parameter (optional)

jsonResponse = restClient.blockfacts.getHistoricalOHLCVData("BTC", "USD", "1d", "5.8.2020", "14:00:00", "10.8.2020", "14:00:00", 2)

Specific historical data

Get historical normalized price by specific point in time.

• getSpecificHistoricalData(asset, denominator, date, time)

jsonResponse = restClient.blockfacts.getSpecificHistoricalData("BTC", "USD", "2.9.2019", "14:00:00")

Normalization pairs

Get all running normalization pairs. Resulting in which asset-denominator pairs are currently being normalized inside our internal system.

• getNormalizationPairs()

jsonResponse = restClient.blockfacts.getNormalizationPairs()

Period movers

Get the moving percentage, and difference in price over a certain time period.

• getPeriodMovers(denominator, date, interval, sort)

jsonResponse = restClient.blockfacts.getPeriodMovers("USD", "11.8.2020", "sevenDay", -1)

Exchange endpoints

List all exchanges

List all exchanges that we support.

• listAllExchanges()

jsonResponse = restClient.exchanges.listAllExchanges()

Specific exchange data

Get information about a specific exchange by its name. Returns information such as which assets are supported, asset ticker info, etc.

• getSpecificExchangeData(exchange)

jsonResponse = restClient.exchanges.getSpecificExchangeData("KRAKEN")

Current trade data

Get current trade data for specific asset-denominator pair, from specific exchange(s).

• getCurrentTradeData(assets, denominators, exchanges)

jsonResponse = restClient.exchanges.getCurrentTradeData(["BTC", "ETH"], ["USD", "GBP"], ["KRAKEN", "COINBASE"])

# OR

jsonResponse = restClient.exchanges.getCurrentTradeData("BTC, ETH", "USD, GBP", "KRAKEN, COINBASE")

Pair info

Get the Blockfacts pair representation of the provided exchange pair.

• getPairInfo(exchange, pair)

jsonResponse = restClient.exchanges.getPairInfo("BITSTAMP", "BTCUSD")

Snapshot trade data

Get 600 latest trades that happened on the requested exchange(s) and pairs.

• getSnapshotTradeData(assets, denominators, exchanges)

jsonResponse = restClient.exchanges.getSnapshotTradeData(["BTC", "ETH"], ["USD", "GBP"], ["KRAKEN", "COINBASE"])

# OR

jsonResponse = restClient.exchanges.getSnapshotTradeData("BTC, ETH", "USD, GBP", "KRAKEN, COINBASE")

Snapshot OHLCV data

Gets the snapshot of provided exchange(s) OHLCV data for provided asset-denominator pairs and intervals.

• getOHLCVSnapshotData(assets, denominators, exchanges, intervals)

jsonResponse = restClient.exchanges.getOHLCVSnapshotData(["BTC", "ETH"], ["USD", "GBP"], ["KRAKEN", "COINBASE"], ["30s", "1m", "1h"])

# OR

jsonResponse = restClient.exchanges.getOHLCVSnapshotData("BTC, ETH", "USD, GBP", "KRAKEN, COINBASE", "30s, 1m, 1h")

Note: You can find all supported intervals on our official documentation here: https://docs.blockfacts.io/?python#data-snapshot-ohlcv-exchange

Historical trade data

Get exchange historical price by asset-denominator, exchange, date, time and interval.

• getHistoricalTradeData(asset, denominator, exchanges, date, time, interval, page)

jsonResponse = restClient.exchanges.getHistoricalTradeData("BTC", "USD", ["KRAKEN", "COINBASE"], "2.9.2019", "14:00:00", 20)

# OR with page parameter (optional)

jsonResponse = restClient.exchanges.getHistoricalTradeData("BTC", "USD", "KRAKEN, COINBASE", "2.9.2019", "14:00:00", 20, 3)

OHLCV Historical data

Get historical OHLCV data by asset-denominator, exchange, date, time and interval.

• getHistoricalOHLCVData(asset, denominator, exchanges, interval, dateStart, timeStart, dateEnd, timeEnd, page)

jsonResponse = restClient.exchanges.getHistoricalOHLCVData("BTC", "USD", ["KRAKEN", "COINBASE"], "1d", "5.8.2020", "14:00:00", "10.8.2020", "14:00:00")

# OR with page parameter (optional)

jsonResponse = restClient.exchanges.getHistoricalOHLCVData("BTC", "USD", "KRAKEN, COINBASE", "1d", "5.8.2020", "14:00:00", "10.8.2020", "14:00:00", 1)

Specific trade data

Get historical exchange trades in specific second.

• getSpecificTradeData(asset, denominator, exchanges, date, time)

jsonResponse = restClient.exchanges.getSpecificTradeData("BTC", "USD", ["KRAKEN", "COINBASE"], "2.9.2019", "14:00:00")

# OR

jsonResponse = restClient.exchanges.getSpecificTradeData("BTC", "USD", "KRAKEN, COINBASE", "2.9.2019", "14:00:00")

Total trade volume

Get the total traded volume on all exchanges by asset-denominator and interval.

• getTotalTradeVolume(asset, denominator, interval)

jsonResponse = restClient.exchanges.getTotalTradeVolume("BTC", "USD", "1d")

Period movers

Get the moving percentage, and difference in price over a certain time period.

• getPeriodMovers(exchange, denominator, date, interval, sort)

jsonResponse = restClient.exchanges.getPeriodMovers("KRAKEN", "USD", "11.8.2020", "sevenDay", -1)

Using WebSocket API Client

Our WebSocket feed provides real-time market data streams from multiple exchanges at once and the BlockFacts normalized price stream for each second. The WebSocket feed uses a bidirectional protocol, and all messages sent and received via websockets are encoded in a JSON format.

Getting started and connecting

To get started simply create a new instance of the WebsocketClient class, and create handler functions for websocket events. You can then call the connect() function and open a connection with the BlockFacts websocket server.

from blockfacts import WebsocketClient
import json

key = 'your-api-key'
secret = 'your-api-secret'

def on_open():
    print("BlockFacts websocket server connection open")

def on_message(message):
    data = json.loads(message)
    print(data)    
    # Handle websocket server messages

def on_close():
    print("BlockFacts websocket server connection closed")

def on_error(err):
    print(err)

websocketClient = WebsocketClient(key, secret)
websocketClient.onOpen = on_open
websocketClient.onMessage = on_message
websocketClient.onClose = on_close
websocketClient.onError = on_error
websocketClient.connect()

Subscribing

In order to subscribe to specific channels or asset-pairs you must send out a subscribe type message. The subscribe message must be sent out after the connection with the websocket has been established. You can call the subscribe() function right after the connect() function, or in the on_open() event handler and pass it a list of channels:

websocketClient.connect()
websocketClient.subscribe([
    {
        "name":"BLOCKFACTS",
        "pairs": [
            "BTC-USD"
        ]
    },
    {
        "name":"HEARTBEAT"
    }
])

# OR

def on_open():
    print("BlockFacts websocket server connection open")
    websocketClient.subscribe([
      {
        "name":"BLOCKFACTS",
        "pairs": [
            "BTC-USD"
        ]
      },
      {
        "name":"HEARTBEAT"
      }
    ])

The subscribe type message supports two more optional parameters which are id and snapshot. You can pass those parameters after the listed channels dictionary in the subscribe() function.

websocketClient.subscribe([
    {
        "name":"BLOCKFACTS",
        "pairs": [
            "BTC-USD"
        ]
    },
    {
        "name":"HEARTBEAT"
    }
], "some-id", True)

To read more about the snapshot type message, please refer to our official documentation: https://docs.blockfacts.io/?python#snapshot

Unsubscribing

If you wish to unsubscribe from certain channels or pairs, you can do so by sending the unsubscribe type message.

websocketClient.unsubscribe([
    {
      "name":"BLOCKFACTS",
      "pairs": [
          "BTC-USD",
          "ETH-USD"
      ]
    },
    {
      "name":"HEARTBEAT"
    },
    {
      "name":"KRAKEN"
    }
], 12345)

The unsubscribe type message supports one more optional parameter which is id. You can pass this parameter after the listed channels dictionary in the unsubscribe() function.

Ping

Clients can send ping type messages to determine if the server is online.

websocketClient.ping()

The ping type message supports one optional parameter which is id. You can pass this parameter in the ping() function.

Pong

Clients must respond to ping type messages sent from the server with a pong type message.

def on_message(message):
    data = json.loads(message)

    if (data["type"] == "ping"):
      websocketClient.pong()

The on_message() event handler can also be used to handle all message types from the websocket, for example:

def on_msg(message):
    data = json.loads(message)

    if data["type"] == 'subscribed':
      # Subscribed type message  

    if data["type"] == 'snapshot':
      # Snapshot type message  

    if data["type"] == 'unsubscribed':
      # Unsubscribed type message    

    if data["type"] == 'exchangeTrade':
      # ExchangeTrade type message    

    if data["type"] == 'blockfactsPrice':
      # BlockfactsPrice type message    

    if data["type"] == 'ping':
      # Ping type message     
      websocketClient.pong()   

    if data["type"] == 'pong':
      # Pong type message       

    if data["type"] == 'status':
      # Status type message       

    if data["type"] == 'heartbeat':
      # Heartbeat type message        

    if data["type"] == 'error':
      # Error type message   

Disconnect

Clients can disconnect from the BlockFacts websocket by calling the disconnect() function. The disconnect function will work only if the connection has already been established.

websocketClient.disconnect()

In order to have a better understanding of our server responses, please refer to: https://docs.blockfacts.io/?python#server-messages