NAV Navbar
Shell Node.Js C# Java Python

Getting started

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

This is the official BlockFacts developer documentation. In this document, you should find all the information required to properly implement applications and services using our APIs.

There are 2 main APIs that we currently support:

API Communication model Description
RESTful Request-Response API providing the richest amount of data. Mostly used for gathering historical asset, trades, and normalization data, as well as getting to know our standards a bit in-depth.
WebSocket Publish-Subscribe API providing realtime market streaming data. Mostly used for gathering real-time trades and normalization data from multiple exchanges.

Standards and conventions

Date and time formats

All BlockFacts servers are based on UTC time, meaning that our timestamps, dates, and times are always converted to UTC before we insert them in the database.
On the other hand, the timestamps we receive from other exchanges are inserted as-is, based on their timezones and date structuring.

REST API

General

BlockFacts provides a unique way of fetching the data from multiple crypto exchanges through only one API.

Our Rest API is built with performance, scalability, and readability in mind. Endpoints are structured by hierarchy and are divided into several main endpoint groups.

Endpoint group Description
Asset data Asset endpoints expose information about certain crypto as well as fiat currencies. Users can use this information to get familiar with currency namings in our system, as well as to see what assets and pairs we provide.
BlockFacts data Endpoints in this group provide rich data regarding our normalized data feeds. Using these endpoints users can get information such as current normalized price value for a specific asset-denominator pair from a specific exchange, historical normalized data, normalized end of day data, and much more.
Exchange data Exchange data endpoints provide details regarding the crypto exchanges that we collect the data from. Some of the most commonly used are current trade data endpoint for specific asset-denominator pair, historical trades data queried by asset-denominator, exchange as well as date and time interval.

We try to unify as much data as possible and provide a wide variety of data to our clients.

Authorization

In order to use our API, you must authorize yourself with each request.
You will need to provide X-API-KEY and X-API-SECRET values in the HTTP Request header.

Name In Type Required
X-API-KEY header string true
X-API-SECRET header string true

Assuming your API Key is 2562532287-YOUR-API-KEY and API Secret 2562532287-YOUR-API-SECRET, then the HTTP request headers should look like this:

X-API-KEY: 2562532287-YOUR-API-KEY
X-API-SECRET: 2562532287-YOUR-API-SECRET

Obtaining an API Key

You can obtain your API Key and Secret by signing up on this link

API Key Limitations

Each key is associated with its plan and has different daily and monthly call limits.

Pricing plan Daily API call limit Monthly API call limit
Hobbyist 100 1000
StartUp Unlimited Unlimited
Professional Unlimited Unlimited
Enterprise Unlimited Unlimited


Daily API call limit resets at 00:00, and monthly limit resets every 1st day of the month.
You can learn more about pricing plans on our pricing page.

Asset endpoints

List all assets

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/assets \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/assets';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/assets";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/assets";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/assets'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

Get all assets that we support

HTTP Request

GET /api/v1/assets

Example responses

200 Response

[
  {
    "asset": "Bitcoin",
    "blockfactsTicker": "BTC",
    "isCrypto": 1
  },
  {
    "asset": "Ethereum",
    "blockfactsTicker": "ETH",
    "isCrypto": 1
  }
]

Responses

Status Code 200

Name Type Description
asset string Asset name
blockfactsTicker string BlockFacts ticker ID
isCrypto integer(int32) Boolean indicator 1 = yes, 0 = no

Specific asset

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/assets/BTC \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/assets/BTC';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/assets/BTC";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/assets/BTC";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/assets/BTC'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

Get specific asset by ticker ID

HTTP Request

GET /api/v1/assets/{ticker}

Parameters

Name In Type Multiple allowed Description
ticker path string no BlockFacts asset ticker (e.g. BTC)

Example responses

200 Response

{
    "asset": "Bitcoin",
    "blockfactsTicker": "BTC",
    "isCrypto": 1
}

Responses

Status Code 200

Name Type Description
asset string Asset name
blockfactsTicker string BlockFacts ticker ID
isCrypto integer(int32) Boolean indicator 1 = yes, 0 = no

BlockFacts endpoints

Exchanges in normalization

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/blockfacts/normalization/whitelist/BTC-USD \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/blockfacts/normalization/whitelist/BTC-USD';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/blockfacts/normalization/whitelist/BTC-USD";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/blockfacts/normalization/whitelist/BTC-USD";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/blockfacts/normalization/whitelist/BTC-USD'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

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

HTTP Request

GET /api/v1/blockfacts/normalization/whitelist/{pair}

Parameters

Name In Type Multiple allowed Description
pair path string yes (5 max) Asset-denominator pair (e.g. BTC-USD)

Example responses

200 Response

{
    "BTC-USD": {
        "asset": "Bitcoin",
        "blockfactsPair": "BTC-USD",
        "blockfactsTicker": "BTC",
        "blockfactsDenominator": "USD",
        "exchanges": [
            "Exchange 1",
            "Exchange 2",
            "Exchange 3"
        ]
    }
}

Responses

Status Code 200

Name Type Description
asset string Asset name
blockfactsPair string Name of the pair on BlockFacts server
blockfactsTicker string BlockFacts ticker ID
blockfactsDenominator string BlockFacts denominator ID
exchanges string[] An array of exchanges in string format

Current data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/blockfacts/price?asset=BTC&denominator=USD \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/blockfacts/price?asset=BTC&denominator=USD';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/blockfacts/price?asset=BTC&denominator=USD";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/blockfacts/price?asset=BTC&denominator=USD";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/blockfacts/price?asset=BTC&denominator=USD'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

Get current normalization data for specific asset-denominator pair

HTTP Request

GET /api/v1/blockfacts/price?asset={assetTicker}&denominator={denominatorTicker}

Parameters

Name In Type Multiple allowed Description
asset query string yes (3 max) Asset ticker (e.g. BTC)
denominator query string yes (3 max) Denominator ticker (e.g. USD)

Example responses

200 Response

{
  "BTC-USD": {
        "exchange": "BLOCKFACTS",
        "pair": "BTC-USD",
        "price": 10567.19,
        "included": [
            {
                "exchange": "Exchange 1",
                "pair": "BTC-USD",
                "price": 10567.19,
                "tradeSize": 0.72255894,
                "makerTaker": "sell",
                "tradeId": 73545601,
                "exchangeTime": "09/05/2019 07:51:13",
                "blockfactsTime": 1567669873060,
                "epochExchangeTime": 1567669873002
            }
        ],
        "excluded": [
            {
                "exchange": "Exchange 2",
                "pair": "BTC-USD",
                "price": 10568,
                "tradeSize": 0.72255894,
                "makerTaker": "sell",
                "tradeId": 73545601,
                "exchangeTime": "09/05/2019 07:51:13",
                "blockfactsTime": 1567669873060,
                "epochExchangeTime": 1567669873002
            },
            {
                "exchange": "Exchange 3",
                "pair": "BTC-USD",
                "price": 10566.4,
                "tradeSize": 0.72255894,
                "makerTaker": "sell",
                "tradeId": 73545601,
                "exchangeTime": "09/05/2019 07:51:13",
                "blockfactsTime": 1567669873060,
                "epochExchangeTime": 1567669873002
            }
        ],
        "timestamp": 1567669882006,
        "normalizationTimestamp": 1567669881000,
        "algorithm": "MEDIAN"
}

Responses

Status Code 200

Name Type Description
exchange string Exchange name (In this case always BLOCKFACTS)
pair string Name of the pair on BlockFacts server
price number(double) Normalized price at the specific second
included array An array of included exchange trades which contain rich information regarding a specific trade
excluded array An array of excluded exchange trades which contain rich information regarding a specific trade
timestamp number(double) The timestamp of the finished normalization / Insertion in the database
normalizationTimestamp number(double) The timestamp which represents in which second was the normalization started
algorithm string The algorithm which was used for the normalization

Historical data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/blockfacts/price/historical?asset=ETH&denominator=USD&date=2.8.2019&time=14:01:00&interval=20 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/blockfacts/price/historical?asset=ETH&denominator=USD&date=2.8.2019&time=14:01:00&interval=20';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/blockfacts/price/historical?asset=ETH&denominator=USD&date=2.8.2019&time=14:01:00&interval=20";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/blockfacts/price/historical?asset=ETH&denominator=USD&date=2.8.2019&time=14:01:00&interval=20";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/blockfacts/price/historical?asset=ETH&denominator=USD&date=2.8.2019&time=14:01:00&interval=20'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

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

HTTP Request

GET /api/v1/blockfacts/price/historical?asset={assetTicker}&denominator={denominatorTicker}&date={date}&time={time}&interval={interval}&page={page}

Parameters

Name In Type Multiple allowed Description
asset query string no Asset ticker (e.g. BTC)
denominator query string no Denominator ticker (e.g. USD)
date query string no Specific date (e.g. 2.9.2019)
time query string no Specific time (e.g. 14:01:00)
interval query string no Historical interval to cover (e.g. 20 = 14:01:00 - 14:21:00) (Min 0, Max 240)
page query string no Optional, our API is always showing 100 results per page in order to improve the performance. You can provide the page parameter in order to query a specific page

Example responses

200 Response

{
  "page": 1,
  "totalPages": 15,
  "results": [
    {
        "exchange": "BLOCKFACTS",
            "pair": "ETH-USD",
            "price": 219.84,
            "included": [
                {
                    "exchange": "Exchange 1",
                    "pair": "ETH-USD",
                    "price": 219.84,
                    "tradeSize": 0.34287156,
                    "makerTaker": "buy",
                    "tradeId": 50572779,
                    "exchangeTime": "08/02/2019 14:00:48",
                    "blockfactsTime": 1564754448347,
                    "epochExchangeTime": 1564754448326
                }
            ],
            "excluded": [
              {
                    "exchange": "Exchange 2",
                    "pair": "ETH-USD",
                    "price": 218.2,
                    "tradeSize": 0.34287156,
                    "makerTaker": "buy",
                    "tradeId": 50572779,
                    "exchangeTime": "08/02/2019 14:00:48",
                    "blockfactsTime": 1564754448347,
                    "epochExchangeTime": 1564754448326
                }
            ],
            "timestamp": 1564754460009,
            "normalizationTimestamp": 1564754448000,
            "algorithm": "MEDIAN"
    }
  ]
}

Responses

Status Code 200

Name Type Description
page integer(int32) The number which represents on which page are you currently on
totalPages integer(int32) Number of total pages
results array An array of objects, each representing a certain normalization

Specific historical data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/blockfacts/price/specific?asset=BTC&denominator=USD&date=2.9.2019&time=14:00:00 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/blockfacts/price/specific?asset=BTC&denominator=USD&date=2.9.2019&time=14:00:00';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/blockfacts/price/specific?asset=BTC&denominator=USD&date=2.9.2019&time=14:00:00";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/blockfacts/price/specific?asset=BTC&denominator=USD&date=2.9.2019&time=14:00:00";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/blockfacts/price/specific?asset=BTC&denominator=USD&date=2.9.2019&time=14:00:00'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

Get historical normalized price by specific point in time.

HTTP Request

GET /api/v1/blockfacts/price/specific?asset={assetTicker}&denominator={denominatorTicker}&date={date}&time={time}

Parameters

Name In Type Multiple allowed Description
asset query string no Asset ticker (e.g. BTC)
denominator query string no Denominator ticker (e.g. USD)
date query string no Specific date (e.g. 2.9.2019)
time query string no Specific time (e.g. 14:00:00)

Example responses

200 Response

{
    "exchange": "BLOCKFACTS",
    "pair": "BTC-USD",
    "price": 9920.92,
    "included": [
        {
            "exchange": "Exchange 1",
            "pair": "BTC-USD",
            "price": 9911.1,
            "tradeSize": 0.73745005,
            "makerTaker": "s",
            "tradeId": 0,
            "exchangeTime": "1567432800.818191",
            "blockfactsTime": 1567432800905,
            "epochExchangeTime": 1567432800818
        }
    ],
    "excluded": [
      {
            "exchange": "Exchange 2",
            "pair": "BTC-USD",
            "price": 9930.74,
            "tradeSize": 0.10048231,
            "makerTaker": "sell",
            "tradeId": 73367846,
            "exchangeTime": "09/02/2019 14:00:00",
            "blockfactsTime": 1567432800984,
            "epochExchangeTime": 1567432800153
        }
    ],
    "timestamp": 1567432801004,
    "normalizationTimestamp": 1567432800000,
    "algorithm": "MEDIAN"
}

Responses

Status Code 200

Name Type Description
exchange string Exchange name (In this case always BLOCKFACTS)
pair string Name of the pair on BlockFacts server
price number(double) Normalized price at the specific second
included array An array of included exchange trades which contain rich information regarding a specific trade
excluded array An array of excluded exchange trades which contain rich information regarding a specific trade
timestamp number(double) The timestamp of the finished normalization / Insertion in the database
normalizationTimestamp number(double) The timestamp which represents in which second was the normalization started
algorithm string The algorithm which was used for the normalization

Normalization pairs

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/blockfacts/normalization/trades \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/blockfacts/normalization/trades';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/blockfacts/normalization/trades";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/blockfacts/normalization/trades";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/blockfacts/normalization/trades'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

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

HTTP Request

GET /api/v1/blockfacts/normalization/trades

Example responses

200 Response

[
  {
    "pair": "BTC-USD"
  },
  {
    "pair": "ETH-USD"
  }
]

Responses

Status Code 200

Name Type Description
pair string Asset-denominator pair which is entering the normalization

End of day data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/blockfacts/price/endOfDay?asset=BTC&denominator=USD&length=10 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/blockfacts/price/endOfDay?asset=BTC&denominator=USD&length=10';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/blockfacts/price/endOfDay?asset=BTC&denominator=USD&length=10";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/blockfacts/price/endOfDay?asset=BTC&denominator=USD&length=10";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/blockfacts/price/endOfDay?asset=BTC&denominator=USD&length=10'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

Get normalized end of day data for specific asset-denominator

HTTP Request

GET /api/v1/blockfacts/price/endOfDay?asset={assetTicker}&denominator={denominatorTicker}&length={length}

Parameters

Name In Type Multiple allowed Description
asset query string no Asset ticker (e.g. BTC)
denominator query string no Denominator ticker (e.g. USD)
length query string no Length (representing how many days back from the current day, Min = 0, Max = 20)

Example responses

200 Response

[
  {
        "exchange": "BLOCKFACTS",
        "pair": "BTC-USD",
        "volume": 123993449.84829322,
        "low": 10019.1,
        "high": 10333.44,
        "open": 10355.11,
        "close": 10171.85,
        "timestamp": 1566864001000,
        "date": "2019-08-27T00:03:17.478Z"
    },
    {
        "exchange": "BLOCKFACTS",
        "pair": "BTC-USD",
        "volume": 237848414.10746586,
        "low": 9555.47,
        "high": 10232.32,
        "open": 10171.85,
        "close": 9714.31,
        "timestamp": 1566950401000,
        "date": "2019-08-28T00:02:32.898Z"
    }
]

Responses

Status Code 200

Name Type Description
exchange string Exchange name (In this case always BLOCKFACTS)
pair string Name of the pair on BlockFacts server
volume number(double) The volume calculated for a specific day
low number(double) Specific day's low
high number(double) Specific day's high
open number(double) Specific day's open
close number(double) Specific day's close
timestamp integer(int64) Date timestamp
date string(date-time) Date indicator

Exchange endpoints

All exchanges

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/exchanges \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'

const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/exchanges';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/exchanges";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/exchanges";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/exchanges'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

List all exchanges

HTTP Request

GET /api/v1/exchanges

Example responses

200 Response

[
  {
    "exchange": "Exchange 1",
    "pairs": [
      {
        "collection": "ADA",
        "query": "ADA/ETH",
        "tickerId": "ADA",
        "blockfactsPair": "ADA-ETH",
        "assetName": "Cardano",
        "isCrypto": 1,
        "denominatorName": "Ether",
        "blockfactsDenominator": "ETH"
      },
      {
        "collection": "QTUM",
        "query": "QTUM/ETH",
        "tickerId": "QTUM",
        "blockfactsPair": "QTUM-ETH",
        "assetName": "QTUM",
        "isCrypto": 1,
        "denominatorName": "Ether",
        "blockfactsDenominator": "ETH"
      }
    ]
  },
  {
    "exchange": "Exchange 2",
    "pairs": [
      {
        "collection": "ETH",
        "query": "ETH/XBT",
        "tickerId": "ETH",
        "blockfactsPair": "ETH-BTC",
        "assetName": "Ethereum",
        "isCrypto": 1,
        "denominatorName": "Bitcoin",
        "blockfactsDenominator": "BTC"
      }
    ]
  }
]

Responses

Status Code 200

Name Type Description
exchange string Exchange name
pairs array Pairs array containing rich information of assets which we collect from a specific exchange

Specific exchange data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/exchanges/KRAKEN \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'
const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/exchanges/KRAKEN';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/exchanges/KRAKEN";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/exchanges/KRAKEN";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/exchanges/KRAKEN'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

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

HTTP Request

GET /api/v1/exchanges/{name}

Parameters

Name In Type Multiple allowed Description
name path string no Name of the exchange (e.g. KRAKEN)

Example responses

200 Response

{
  "exchange": "Exchange 1",
  "pairs": [
    {
      "collection": "ADA",
      "query": "ADA/ETH",
      "tickerId": "ADA",
      "blockfactsPair": "ADA-ETH",
      "assetName": "Cardano",
      "isCrypto": 1,
      "denominatorName": "Ether",
      "blockfactsDenominator": "ETH"
    },
    {
      "collection": "QTUM",
      "query": "QTUM/ETH",
      "tickerId": "QTUM",
      "blockfactsPair": "QTUM-ETH",
      "assetName": "QTUM",
      "isCrypto": 1,
      "denominatorName": "Ether",
      "blockfactsDenominator": "ETH"
    }
  ]
}

Responses

Status Code 200

Name Type Description
exchange string Exchange name
pairs array Pairs array containing rich information of assets which we collect from a specific exchange

Current trade data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/exchanges/trades?asset=BTC&denominator=USD&exchange=KRAKEN \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'
const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/exchanges/trades?asset=BTC&denominator=USD&exchange=KRAKEN';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/exchanges/trades?asset=BTC&denominator=USD&exchange=KRAKEN";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/exchanges/trades?asset=BTC&denominator=USD&exchange=KRAKEN";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/exchanges/trades?asset=BTC&denominator=USD&exchange=KRAKEN'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

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

HTTP Request

GET /api/v1/exchanges/trades?asset={assetTicker}&denominator={denominatorTicker}&exchange={exchangeName}

Parameters

Name In Type Multiple allowed Description
asset query string yes (max 3) Asset ticker (e.g. BTC)
denominator query string yes (max 3) Denominator ticker (e.g. USD)
exchange query string yes (max 3) Exchange name (e.g. KRAKEN)

Example responses

200 Response

{
  "BTC-USD": [
    {
      "exchange": "KRAKEN",
      "pair": "BTC-USD",
      "price": 10600.6,
      "tradeSize": 0.15,
      "makerTaker": "b",
      "tradeId": 0,
      "exchangeTime": "1567683508.485677",
      "blockfactsTime": 1567683508698,
      "epochExchangeTime": 1567683508485
    }
  ]
}

Responses

Status Code 200

Name Type Description
exchange string Exchange name
pair string Name of the pair on BlockFacts server
price number(double) Current price
tradeSize number(double) Trade size
makerTaker string Maker taker
tradeId integer(int64) Trade ID
exchangeTime string Timestamp representing the time in which the exchange sent out the trade
blockfactsTime integer(int64) Timestamp representing the time in which the BlockFacts servers received the trade
epochExchangeTime integer(int64) Exchange time converted to epoch timestamp

Historical trade data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/exchanges/trades/historical?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00&interval=20 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'
const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/exchanges/trades/historical?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00&interval=20';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/exchanges/trades/historical?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00&interval=20";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/exchanges/trades/historical?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00&interval=20";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/exchanges/trades/historical?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00&interval=20'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

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

HTTP Request

GET /api/v1/exchanges/trades/historical?asset={assetTicker}&denominator={denominatorTicker}&exchange={exchangeName}&date={date}&time={time}&interval={interval}&page={page}

Parameters

Name In Type Multiple allowed Description
asset query string no Asset ticker (e.g. BTC)
denominator query string no Denominator ticker (e.g. USD)
exchange query string yes (3 max) Exchange name (e.g. KRAKEN)
date query string no Specific date (e.g. 2.9.2019)
time query string no Specific time (e.g. 14:00:00)
interval query string no Historical interval to cover (e.g. 20 = 14:00:00 - 14:20:00) (Min 0, Max 240)
page query string no Optional, our API is always showing 100 results per page in order to improve the performance. You can provide the page parameter in order to query a specific page

Example responses

200 Response

{
  "page": 0,
  "totalPages": 0,
  "results": [
    {
      "exchange": "string",
      "pair": "string",
      "price": 0,
      "tradeSize": 0,
      "makerTaker": "string",
      "tradeId": 0,
      "exchangeTime": "string",
      "blockfactsTime": 0,
      "epochExchangeTime": 0
    }
  ]
}

Responses

Status Code 200

Name Type Description
page integer(int32) The number which represents on which page are you currently on
totalPages integer(int32) Number of total pages
results array An array of objects, each representing a certain trade

Specific trade data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/exchanges/trades/specific?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'
const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/exchanges/trades/specific?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/exchanges/trades/specific?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/exchanges/trades/specific?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/exchanges/trades/specific?asset=BTC&denominator=USD&exchange=KRAKEN&date=2.9.2019&time=14:00:00'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

Get historical exchange trades in specific second

HTTP Request

GET /api/v1/exchanges/trades/specific?asset={assetTicker}&denominator={denominatorTicker}&exchange={exchangeName}&date={date}&time={time}

Parameters

Name In Type Multiple allowed Description
asset query string no Asset ticker (e.g. BTC)
denominator query string no Denominator ticker (e.g. USD)
exchange query string yes (3 max) Exchange name (e.g. KRAKEN)
date query string no Specific date (e.g. 2.9.2019)
time query string no Specific time (e.g. 14:00:00)

Example responses

200 Response

[
  {
    "exchange": "KRAKEN",
    "pair": "BTC-USD",
    "price": 9916.9,
    "tradeSize": 0.2,
    "makerTaker": "s",
    "tradeId": 0,
    "exchangeTime": "1567432800.990809",
    "blockfactsTime": 1567432801186,
    "epochExchangeTime": 1567432800990
  }
]

Responses

Status Code 200

Name Type Description
exchange string Exchange name
pair string Name of the pair on BlockFacts server
price number(double) Current price
tradeSize number(double) Trade size
makerTaker string Maker taker
tradeId integer(int64) Trade ID
exchangeTime string Timestamp representing the time in which the exchange sent out the trade
blockfactsTime integer(int64) Timestamp representing the time in which the BlockFacts servers received the trade
epochExchangeTime integer(int64) Exchange time converted to epoch timestamp

End of day data

Code samples

# You can also use wget
curl -X GET https://api.blockfacts.io/api/v1/exchanges/trades/endOfDay?asset=BTC&denominator=USD&exchange=KRAKEN&length=10 \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: your-api-key' \
  -H 'X-API-SECRET: your-api-secret'
const fetch = require('node-fetch');

var url = 'https://api.blockfacts.io/api/v1/exchanges/trades/endOfDay?asset=BTC&denominator=USD&exchange=KRAKEN&length=10';
var headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

fetch(url, { headers: headers })
.then(response => response.json())
.then(json => console.log(json))
string url = "https://api.blockfacts.io/api/v1/exchanges/trades/endOfDay?asset=BTC&denominator=USD&exchange=KRAKEN&length=10";
var client = new RestClient(url);
var request = new RestRequest(Method.GET);

request.AddHeader("X-API-KEY", "your-api-key");
request.AddHeader("X-API-SECRET", "your-api-secret");

IRestResponse response = client.Execute(request);
var data = response.Content;
OkHttpClient client = new OkHttpClient();
String url = "https://api.blockfacts.io/api/v1/exchanges/trades/endOfDay?asset=BTC&denominator=USD&exchange=KRAKEN&length=10";

Request request = new Request.Builder()
  .url(url)
  .post(body)
  .addHeader("X-API-KEY", "your-api-key")
  .addHeader("X-API-SECRET", "your-api-secret")
  .build();

Response response = client.newCall(request).execute();
import requests

url = 'https://api.blockfacts.io/api/v1/exchanges/trades/endOfDay?asset=BTC&denominator=USD&exchange=KRAKEN&length=10'
headers = {
  'Content-Type': 'application/json',
  'X-API-KEY': 'your-api-key',
  'X-API-SECRET': 'your-api-secret'
}

response = requests.get(url, headers = headers)

print response.json()

Get exchange end of day data for specific asset-denominator and exchange

HTTP Request

GET /api/v1/exchanges/trades/endOfDay?asset={assetTicker}&denominator={denominatorTicker}&exchange={exchangeName}&length={length}

Parameters

Name In Type Multiple allowed Description
asset query string no Asset ticker (e.g. BTC)
denominator query string no Denominator ticker (e.g. USD)
exchange query string no Exchange name (e.g. KRAKEN)
length query string no Length (representing how many days back from the current day, Min = 0, Max = 20)

Example responses

200 Response

[
  {
    "exchange": "KRAKEN",
    "pair": "BTC-USD",
    "volume": 12474395.752756037,
    "low": 10033.0,
    "high": 10387.9,
    "open": 10364.4,
    "close": 10176.3,
    "timestamp": 1566864001000,
    "date": "2019-08-27T00:01:00.3Z"
  },
  {
    "exchange": "KRAKEN",
    "pair": "BTC-USD",
    "volume": 25925093.697197579,
    "low": 9533.0,
    "high": 10297.7,
    "open": 10145.4,
    "close": 9716.1,
    "timestamp": 1566950401000,
    "date": "2019-08-28T00:01:04.486Z"
  }
]

Responses

Status Code 200

Name Type Description
exchange string Exchange name
pair string Name of the pair on BlockFacts server
volume number(double) The volume calculated for a specific day
low number(double) Specific day's low
high number(double) Specific day's high
open number(double) Specific day's open
close number(double) Specific day's close
timestamp integer(int64) Date timestamp
date string(date-time) Date indicator

WebSocket API

Introduction

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.

URL

BlockFacts WebSocket API is located on wss://ws.blockfacts.io/v1/. Connecting to it requires API key authentication.

Channels and pairs

Using our REST API, clients are able to list all available channels and pairs they can subscribe to. Please refer to REST API > Exchange endpoints > All exchanges for listing all supported exchanges and pairs, and check out REST API > BlockFacts endpoints > Normalization pairs for listing all BlockFacts pairs clients can subscribe to.

Limitations

When subscribing to a channel, the maximum number of pairs you can subscribe to is 5.

Communication

All messages will have a type attribute:

{
  "type":"..."
}

All messages sent from and to the server, have a type attribute that can be used to handle the message appropriately. Clients are required to format their messages in the same way, as this is an indicator of the message type they are sending.

Available client message types are:

Type Description
subscribe A message request to subscribe to certain channels and pairs.
unsubscribe A message request to unsubscribe from certain channels or pairs.
ping Client side ping message. Sent to the server to determine if it's still online. The server will respond with a pong type message.
pong A response to a ping type message received from the server.

Error messages

Clients can receive error messages from our WebSocket server. Error messages can be emitted if the client has sent something wrong or there is an issue on our side. Most error messages result in the connection closing immediately.

Ping-Pong

Our WebSocket server uses Ping/Pong messages to determine if client connections are online or offline. The server sends out ping type messages every minute and clients are required to respond with pong type messages to it. If we don't receive a pong type message after a minute, the clients are considered offline.

Clients can also send ping type messages to our WebSocket server, and the server will always respond with a pong type message, if online. For determining if your connection is still alive, you can also subscribe to the heartbeat channel.

Client messages

Clients can communicate with the WebSocket server by sending out messages containing the type attribute. Messages without the type attribute will be disregarded.

Subscribe

Example of a subscribe type message, requesting to subscribe to KRAKEN, COINBASE and BLOCKFACTS channels:

{
  "type":"subscribe",
  "X-API-KEY":"your-api-key",
  "X-API-SECRET":"your-api-secret",
  "channels": [
    {
      "name":"KRAKEN",
      "pairs": [
        "BTC-USD",
        "BTC-EUR"
      ]
    },
    {
      "name":"COINBASE",
      "pairs": [
        "BTC-USD"
      ]
    },
    {
      "name":"BLOCKFACTS",
      "pairs": [
        "BTC-USD",
        "BTC-EUR",
        "BTC-GBP"
      ]
    }
  ]
}

Another example of a subscribe type message, now requesting to subscribe to the BITSTAMP and the HEARTBEAT channel:

{
  "type":"subscribe",
  "X-API-KEY":"your-api-key",
  "X-API-SECRET":"your-api-secret",
  "channels": [
    {
      "name":"BITSTAMP",
      "pairs": [
        "BTC-USD",
        "BTC-EUR",
        "BTC-GBP",
        "ETH-USD",
        "ETH-EUR"
      ]
    },
    {
      "name":"HEARTBEAT"
    }
  ]
}

When your WebSocket client has established the connection, you must send out a subscribe type message which contains:

Field Type Description
type string Type of the message the client is sending. In this case subscribe.
X-API-KEY string Client's API key.
X-API-SECRET string Client's API secret.
channels object array Array of channels the client is subscribing to.

The channels array is used to tell our WebSocket API which exchange data streams you are subscribing to and what pairs you are requesting. An array element is an object and contains two fields:

Field Type Description
name string Name of the channel you are subscribing to.
pairs string array Array of pairs you are subscribing to from that channel.

Unsubscribe

Example of an unsubscribe type message, requesting to unsubscribe from the whole KRAKEN channel, from some pairs from the COINBASE channel and the HEARTBEAT channel:

{
  "type":"unsubscribe",
  "channels": [
    {
      "name":"KRAKEN"
    },
    {
      "name":"COINBASE",
      "pairs": [
        "BTC-USD",
        "BTC-GBP"
      ]
    },
    {
      "name":"HEARTBEAT"
    }
  ]
}

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

Field Type Description
type string Type of the message the client is sending. In this case unsubscribe.
channels object array Array of channels the client is unsubscribing from.

The channels array is used to tell our WebSocket API which channels you are unsubscribing from. You can unsubscribe from certain pairs in a channel, or from the whole channel and all of its pairs.

The channels array element contains two fields:

Field Type Description
name string Name of the channel you are unsubscribing from.
pairs string array Array of pairs you are unsubscribing from in that channel. This field is not mandatory, and is only needed if you are unsubscribing from certain pairs in a channel. If you are trying to unsubscribe from the whole channel, don't provide this field.

Ping

Example of a ping type message:

{
  "type":"ping"
}

Clients can send ping type messages to determine if the server is online. The ping type message contains:

Field Type Description
type string Type of the message the client is sending. In this case ping.

Pong

Example of a pong type message:

{
  "type":"pong"
}

Clients must respond to ping type messages from the server with a pong type message. The pong type message contains:

Field Type Description
type string Type of the message the client is sending. In this case pong.

Server messages

The WebSocket server gives feedback and communicates with the clients. It also makes sure that the clients receive real-time exchange data streams for channels they subscribed to. Each message will have a type attribute that can be used to handle the message appropriately.

Subscribed

Example of a subscribed type message, the client was successfully subscribed to KRAKEN, COINBASE, BLOCKFACTS and the HEARTBEAT channel:

{
  "type":"subscribed",
  "channels": [
    {
      "name":"KRAKEN",
      "pairs": [
        "BTC-USD",
        "BTC-EUR"
      ]
    },
    {
      "name":"COINBASE",
      "pairs": [
        "BTC-USD",
        "BTC-GBP"
      ]
    },
    {
      "name":"BLOCKFACTS",
      "pairs": [
        "BTC-USD",
        "BTC-EUR",
        "BTC-GBP"
      ]
    },
    {
      "name":"HEARTBEAT"
    }
  ]
}

The subscribed type message is returned from the server after a successful subscription. The subscribed type message contains:

Field Type Description
type string Type of the message the server is sending. In this case subscribed.
channels object array Array of channels the client has subscribed to.

Unsubscribed

Example of a unsubscribed type message, the client was successfully unsubscribed from the whole KRAKEN channel and from 2 pairs from the COINBASE channel:

{
  "type":"unsubscribed",
  "channels": [
    {
      "name":"KRAKEN",
      "pairs": []
    },
    {
      "name":"COINBASE",
      "pairs": [
        "BTC-USD",
        "BTC-GBP"
      ]
    }
  ]
}

The unsubscribed type message is returned from the server after a successful unsubscription. The unsubscribed type message contains:

Field Type Description
type string Type of the message the server is sending. In this case unsubscribed.
channels object array Array of channels the client has unsubscribed from.

ExchangeTrade

Example of a exchangeTrade type message:

{
  "type":"exchangeTrade",
  "data": {
    "blockfactsTime":1567763615260,
    "epochExchangeTime":1567763615195,
    "exchange":"COINBASE",
    "exchangeTime":"2019-09-06T09:53:35.195Z",
    "makerTaker":"sell",
    "pair":"BTC-EUR",
    "price":9729.55000000,
    "tradeId":21792466,
    "tradeSize":0.00126608
  }
}

exchangeTrade messages are returned from the server on every executed transaction on the exchanges (channels) the client is subscribed to. The exchangeTrade type message contains:

Field Type Description
type string Type of the message the server is sending. In this case exchangeTrade.
data object The BlockFacts trade model, containing the information regarding the transaction.

The data object contains the following fields:

Field Type Description
exchange string Exchange/channel name.
pair string Pair name.
price number Current price of that asset.
tradeSize number Trade size.
makerTaker string Maker taker.
tradeId number Trade ID.
exchangeTime string Timestamp representing the time in which the exchange sent out the trade.
blockfactsTime number Timestamp representing the time in which the BlockFacts servers received the trade.
epochExchangeTime number Exchange time converted to an epoch timestamp.

BlockfactsPrice

Example of a blockfactsPrice type message:

{
  "type":"blockfactsPrice",
  "data": {
    "algorithm":"MEDIAN",
    "exchange":"BLOCKFACTS",
    "excluded": [],
    "included": [{
      "blockfactsTime":1567765573380,
      "epochExchangeTime":1567765573361,
      "exchange":"COINBASE",
      "exchangeTime":"09/06/2019 10:26:13",
      "makerTaker":"sell",
      "pair":"BTC-USD",
      "price":10769.51,
      "tradeId":73596693,
      "tradeSize":0.00129343
    }],
    "normalizationTimestamp":1567765573000,
    "pair":"BTC-USD",
    "price":10769.51,
    "timestamp":1567765574010
  }
}

blockfactsPrice messages are returned from the server every second for each BlockFacts pair the client is subscribed to. The blockfactsPrice type message contains:

Field Type Description
type string Type of the message the server is sending. In this case blockfactsPrice.
data object The BlockFacts normalized price model, containing the information regarding the normalized price for the pair the client is subscribed to.

The data object contains the following fields:

Field Type Description
exchange string Exchange name. In this case BLOCKFACTS.
pair string Pair name.
price number Normalized price at a specific second.
included object array Array of included exchange trade models which contain rich information regarding a specific trade.
excluded object array Array of excluded exchange trade models which contain rich information regarding a specific trade.
timestamp number Timestamp representing the time in which the normalization process finished working for a particular second.
normalizationTimestamp number Timestamp representing the second for which the normalization process worked for.
algorithm string The algorithm used to calculate the normalized price.

Ping

Example of a ping type message:

{
  "type":"ping"
}

The WebSocket server will send ping type messages to determine if the clients are online. The ping type message contains:

Field Type Description
type string Type of the message the server is sending. In this case ping.

Pong

Example of a pong type message:

{
  "type":"pong"
}

The WebSocket server will respond to ping type messages from the client with a pong type message. The pong type message contains:

Field Type Description
type string Type of the message the server is sending. In this case pong.

Status

Example of a status type message, received after connecting and authenticating on the WebSocket server:

{
  "type":"status",
  "connectionID":"b97c7ed0-d091-11e9-be0f-d511aa698665",
  "status":"online",
  "wssVersion":"1.0.0"
}

Another example of a status type message, received before the WebSocket server maintenance starts:

{
  "type":"status",
  "connectionID":"b97c7ed0-d091-11e9-be0f-d511aa698665",
  "status":"maintenance",
  "wssVersion":"1.0.0"
}

status type messages are sent out on system status changes and after initializing the connection for the first time. There are three types of system statuses:

The online status is sent when the connection is established between the client and the server. The maintenance status message is sent when the maintenance of the WebSocket is about to take place, warning clients that the server is going offline. The error status message is sent out if an internal error occurred.

The status type message contains:

Field Type Description
type string Type of the message the server is sending. In this case status.
connectionID string Client's connection ID.
status string Server system status.
wssVersion string The version of the WebSocket server the client is connected to.

Heartbeat

Example of a heartbeat type message:

{
  "type":"heartbeat"
}

If you subscribe to the heartbeat channel, you will receive heartbeat type messages every 5 seconds, if there aren't other messages coming through. The heartbeat type message contains:

Field Type Description
type string Type of the message the server is sending. In this case heartbeat.

Error

Example of an error type message:

{
  "type":"error",
  "message":"..."
}

error messages are sent out if a client sent a wrong message, or there was something preventing them from connecting to our WebSocket server. The error type message contains:

Field Type Description
type string Type of the message the server is sending. In this case error.
message string The error message.