BitcoinAverage API

INTRODUCTION

DISCLAIMER

ANY ACCESS AND USE OF THE API AND OUR DATA IS SOLELY YOUR RESPONSIBILITY. FOR FULL TERMS AND CONDITIONS PLEASE CLICK HERE

Rate Limiting

The majority of our API is free to use. However, certain endpoints require authentication that requires registration and the generation of an API Key. Please Sign Up to create a key pair.

Access to our API is rate limited depending on the users plan. Full details of each plan’s access rights can be found here

Authentication

API Key authentication should be used for endpoints that are restricted to a certain plan. These levels are listed throughout our documentation where required.

Authenticating your API requests is recommended for all users, as the rate limiting levels for registered users are more generous.

Signing

Any request that is made using an API Key must be signed, you can create an API Key pair in your account.

Requests

All authenticated requests must contain this header:

  • X-signature
    • Containing timestamp, public_key and digest_value

Note: These values are dot (.) separated URL safe strings

Firstly create a payload consisting of “timestamp.public_key”:

  • timestamp

    • This is an integer value representing the unix epoch. This needs to be no more than 15 seconds different than our server time for the request to pass. This prevents replay attacks. If you wish to check our server time please use the “/constants/time” endpoint.
  • public_key

    • Public API Key as a string

Note: On some systems the timestamp is generated as 123541.123, a decimal value, make sure to convert this to integer i.e. strip the decimal part.

Example payload:

  • 1234.YzQxNGYyMGI1YzJjNDg3YThkOGU1MTgwZWNhYjY4ODI=

Secondly this payload needs to be HMAC encrypted with the sha256 algorithm using your API secret key that corresponds to the given public key in the payload. This result is called a ‘digest_value’ and needs to be in hex representation.

Example:

payload = 1234.YzQxNGYyMGI1YzJjNDg3YThkOGU1MTgwZWNhYjY4ODI=

Secret key = abcdef123456

digest_value = a963aa66dbe4871ca17bbd64d5c1043d2f9204f19538b6e0f69c78f04adab9c8

Example of an invalid digest_value:

  • \xc4\xfe\x8e\xe0\xa7b-F{&\xbaj\x99\x0f"\xdc\xe6\xdbxT\n\xd9\xa7\x96\x95:G!\x96\xdav|
    • This value is the raw bytes value.

Finally we can compose the value that needs to be used in the X-signature header. It’s contents need to be in the format:

  • timestamp.public_key.digest_value

Example X-signature header:

  • 1234.YzQxNGYyMGI1YzJjNDg3YThkOGU1MTgwZWNhYjY4ODI=.a963aa66dbe4871ca17bbd64d5c1043d2f9204f19538b6e0f69c78f04adab9c8

To “unlock” an endpoint for testing, simply include this header with your request: “X-testing: testing”. You will still be rate limited by IP when using this method. Here is an example:

  • curl -H "X-testing: testing" https://apiv2.bitcoinaverage.com/exchanges/all

Note that the endpoint used in the example requires authentication, but with this header you can test it right away.

Integration

Integration examples in multiple programming languages can be found on our GitHub repository.

We are looking to expand the languages we support, if you are interested in helping out please get in touch! support@bitcoinaverage.com

Python PIP library

This is as simple as running the following command in console:

pip install bitcoinaverage

For more details please visit: https://pypi.org/project/bitcoinaverage/

You can find usage examples for all functions provided by our PIP library on our GitHub repository.

Constants

Endpoints to return our supported currency pair symbols

Supported Symbols

All Symbols

Returns a list of all symbols for both global and local markets

Symbols Per Market

Returns a list of symbols for a specific market

Exchange Rates

Rates

Returns global fiat exchange rates used in the current indices calculations

Server Time

Time

Returns our server time that can be used as a check when using API Key authentication

Indices

We provide a single global index, and multiple local or currency indices

All endpoints in this collection require the market parameter to be provided

Ticker Data

All

If no query parameters are sent, then returns ticker data for every supported symbol. If crypto(s) and/or fiat(s) are sent as parameters, then only the ticker for those values is sent

Plan: Developer

Per Symbol

Returns ticker data for specified symbol

Short

Returns basic ticker denoting last and daily average price for the specified crypto/fiat values.

Ticker Changes Per Symbol

Returns ticker values and price changes for specified market and symbol.

Plan: Developer

Custom

This endpoint can be used to generate a custom index in a certain currency. The “inex” path parameter represents “include” or “exclude”, you can choose to generate an index removing specified exchanges, or only including the few that you require.

Note that the exchange must have an order book in the specified currency.

Plan: Business

Historical Data

Historical Data

Return historical ticker data for ‘symbol’. Optional ‘format’ parameter with value csv/json

Periods

  • daily - per minute daily sliding window.

  • monthly - per hour monthly sliding window.

  • alltime - per day all time history (default value)

Data Since Timestamp

Return historical ticker data since ‘timestamp’ only

Plan: Developer

Price at Timestamp

Return price at specified timestamp (unix format)

  • If timestamp is in per_minute data range, returns price closest to minute

  • If timestamp is in per_hour data range, returns price closest to hour

  • If timestamp is in per_day data range, returns price closest to timestamp at 00:00 that day

Plan: Developer

Exchanges

Endpoints for exchange related actions

Exchange Data

Exchange Data by Symbol

Returns data for exchanges that provide an order book with the specified symbol

Plan: Developer

All Exchange Data

Returns a list of all exchanges with their integrated symbols and data. Data can be filtered by crypto or fiat currency

Plan: Developer

Per Exchange Data

Returns specified exchange’s symbols and data

Ignored Exchanges

Returns exchanges that are either ignored or inactive according to specified state parameter. With ignored exchanges a “ignore_reason” is provided

Exchange Count

Get integration counts

Return a total of integrated exchanges along with ignored, included and inactive status counts

Exchange Outliers

Get Outliers

Returns a list of exchanges that failed our sanity checks. Provides what value failed and on what order book

Weighting

These endpoints return the weighting data that are used to calculate our various indices

Indices Weighting

Exchange Weights

Returns a list of exchanges, their symbols, and their associated weights

Plan: Developer

Currency Weights

Returns a list of currencies and their weights that are used to produce our Global Bitcoin Price Index

Plan: Developer

Conversion

Price Converter

Perform Conversion

Returns conversion from start currency to resulting currency. Only conversion from fiat to crypto, or vice verca are supported. Conversion from crypto to crypto is not supported.

Plan: Registered

Blockchain

Get price at the moment the trasaction happened.

Price Based on Transaction Hash

Price at Transaction Time

Takes a transaction hash and returns a price for the day the transaction was conducted. The price is for the provided symbol.

Plan: Developer

Websocket API

We provide real time data through our websocket API.

Websocket Authentication

For regular API users the procedure is following. Let’s consider a user with apikey pair consisting of:

public_key = 12341234AB
secret_key = 2134fdas3sdf

These are the steps for websocket authentication:

  1. Send a GET request, signed with public_key and secret_key to /websocket/get_ticket and receive response {“ticket”: “ASDFXZCVASDF2341234”}.

  2. Connect to one of the desired endpoints:

    a) /websocket/ticker
     
     b) /websocket/exchanges

    With additional parameters to the end of the url:

    ?public_key=12341234AB&ticket=ASDFXZCVASDF2341234

    The whole request url for the available websockets would be:

    a) /websocket/ticker:
     wss://apiv2.bitcoinaverage.com/websocket/ticker?public_key=12341234AB&ticket=ASDFXZCVASDF2341234
    
     b) /websocket/exchanges:
     wss://apiv2.bitcoinaverage.com/websocket/exchanges?public_key=12341234AB&ticket=ASDFXZCVASDF2341234

    If some of the parameters, public_key or ticket, are wrong, then the connection will be closed immediately by our server. The ticket can only be used once. The ticket will expire after its generation so it can be used within a limited time period, around 60 seconds or less.

Subscribing to a channel

Once the authentication is successfully done and the connection is open, the client can send messages to the server. Here are the subscribe message examples for the offered endpoints:

a) /websocket/ticker

    Parameters:
        "market" - "local" and "global"
        "currency" - crypto-fiat pairs, e.g. BTCUSD, LTCEUR, ETHGBP, etc.

    {"event": "message",
         "data": {
             "operation": "subscribe",
             "options": {
                 "market": "local",
                 "currency": "BTCUSD"
             }
         }
    }
    
b) /websocket/exchanges
    
    Parameters:
        "exchange" - valid exchange name
    
    {"event": "message",
         "data": {
             "operation": "subscribe",
             "options": {
                 "exchange": "bitfinex"
             }
         }
     }

Full websocket example

Full working example (for Ticker Websocket) can be found on GitHub.

No action selected

You can try selecting'All Symbols'from the left column.

All Symbols

GET https://apiv2.bitcoinaverage.com/constants/symbols
Response

200

HideShow
Headers
Content-Type: application/json
Body
{
    "local": {
        "symbols": [
            "BTCAUD",
            "BTCBRL",
            "BTCCAD",
        ]
    },
    "global": {
        "symbols": [
            "BTCAED",
            "BTCAFN",
            "BTCALL",
    },
    "success": true,
}

Symbols Per Market

GET https://apiv2.bitcoinaverage.com/constants/symbols/global
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
    "symbols": [
        "BTCAUD",
        "BTCBRL",
        "BTCCAD",
    ],
    "success": true
}

Rates

GET https://apiv2.bitcoinaverage.com/constants/exchangerates/global
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
    "time": "23-03-2016 16:59:19",
    "rates": {
        "MXN": {
            "name": "Mexican Peso",
            "rate": "17.48512"
        },
        "USD": {
            "name": "United States Dollar",
            "rate": "1"
        },
        "JPY": {
            "name": "Japanese Yen",
            "rate": "112.5204"
        },
        "KRW": {
            "name": "South Korean Won",
            "rate": "1161.976675"
        },
    },
}

Time

GET https://apiv2.bitcoinaverage.com/constants/time
Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "epoch": 1458754280,
  "iso": "2016-03-23T17:31:20"
}

All

GET https://apiv2.bitcoinaverage.com/indices/global/ticker/all?crypto=BTC&fiat=USD,EUR
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

crypto
stringBTC

Crypto

fiat
stringUSD,EUR

Fiat

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "BTCEUR": {
    "ask": 591.04,
    "bid": 590.43,
    "last": 590.82,
    "high": 591.72,
    "low": 585.7,
    "open": {
      "day": 590.32,
      "week": "",
      "month": ""
    },
    "averages": {
      "day": 587.93,
      "week": 587.92,
      "month": 588.57
    },
    "volume": 98908.81,
    "changes": {
      "percent": {
        "day": 0.85,
        "week": -0.89,
        "month": 3.38
      },
      "price": {
        "day": 5.01,
        "week": -5.3,
        "month": 19.3
      }
    },
    "volume_percent": 6.6,
    "timestamp": 1469802310,
    "display_timestamp": "2016-07-29 14:25:10"
  },
  "BTCUSD": {
    "ask": 659.82,
    "bid": 659.14,
    "last": 659.58,
    "high": 660.59,
    "low": 653.86,
    "open": {
      "day": 653.99,
      "week": 665.5,
      "month": 638.03
    },
    "averages": {
      "day": 656.36,
      "week": 656.34,
      "month": 657.07
    },
    "volume": 98908.81,
    "changes": {
      "percent": {
        "day": 0.85,
        "week": -0.89,
        "month": 3.38
      },
      "price": {
        "day": 5.59,
        "week": -5.92,
        "month": 21.55
      }
    },
    "volume_percent": 29.57,
    "timestamp": 1469802310,
    "display_timestamp": "2016-07-29 14:25:10"
  }
}

Per Symbol

GET https://apiv2.bitcoinaverage.com/indices/global/ticker/BTCUSD
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

symbol
stringBTCUSD

Currency Pair

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "ask": 418.79,
  "bid": 418.35,
  "last": 418.66,
  "high": 418.83,
  "low": 417.1,
  "open": {
    "day": "417.73",
    "week": "408.74",
    "month": "439.27685451203826"
  },
  "averages": {
    "daily": 418.98,
    "weekly": 418.39,
    "monthly": 419.76
  },
  "volume": 56542.49,
  "changes": {
    "price": {
      "weekly": 9.92,
      "monthly": -20.62,
      "daily": 0.93
    },
    "percent": {
      "weekly": 2.43,
      "monthly": -4.69,
      "daily": 0.22
    }
  },
  "volume_percent": 66.42,
  "timestamp": 1458754392,
  "display_timestamp": "Wed, 23 Mar 2016 17:33:12 +0000"
}

Short

GET https://apiv2.bitcoinaverage.com/indices/global/ticker/short?crypto=BTC&fiats=USD,EUR
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

crypto
stringBTC

Crypto

fiats
stringUSD,EUR

Fiat

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
    "BTCAED": {
        "last": 1537.87,
        "averages": {
            "daily": 1538.88882018
        }
    },
    "BTCAFN": {
        "last": 28622.42,
        "averages": {
            "daily": 28641.47321898
        }
    },
    "BTCALL": {
        "last": 51817.38,
        "averages": {
            "daily": 51851.87587098
        }
    },
    "BTCAMD": {
        "last": 201234.11,
        "averages": {
            "daily": 201368.07228102
        }
    },
}

Ticker Changes Per Symbol

GET https://apiv2.bitcoinaverage.com/indices/global/ticker/BTCUSD/changes
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

symbol
stringBTCUSD

Currency Pair

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "ask": 604.35,
  "bid": 603.66,
  "last": 604.03,
  "high": 627.41,
  "low": 595.72,
  "open": {
    "hour": 599.86,
    "day": 599.86,
    "week": 553.21,
    "month": 517.18,
    "month_3": 759.43,
    "month_6": 831.14,
    "year": 926.2
  },
  "averages": {
    "day": 599.4,
    "week": 640.77,
    "month": 641.14
  },
  "volume": 195910.48,
  "changes": {
    "percent": {
      "hour": -0.69,
      "day": -0.69,
      "week": -7.76,
      "month": -12.57,
      "month_3": 34.64,
      "month_6": 60.25,
      "year": 114.3
    },
    "price": {
      "hour": -4.17,
      "day": -4.17,
      "week": -50.82,
      "month": -86.85,
      "month_3": 155.4,
      "month_6": 227.11,
      "year": 322.17
    }
  },
  "volume_percent": 39.44,
  "timestamp": 1470136512,
  "display_timestamp": "2016-08-02 11:15:12"
}

Custom

GET https://apiv2.bitcoinaverage.com/indices/ticker/custom/include/BTCUSD?exchanges=bitstamp,bitfinex
URI Parameters
HideShow
inex
stringinclude

Include or Exclude

Possible values:include exclude

symbol
stringBTCUSD

Currency pair symbol

exchanges
stringbitstamp,bitfinex

Exchange Name or list of comma separated exchanges

Response

200

HideShow
Headers
Content-Type: application/json
Body
...

Historical Data

GET https://apiv2.bitcoinaverage.com/indices/global/history/BTCUSD?period=daily&format=json
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

symbol
stringBTCUSD

Currency pair symbol

period
stringdaily

Window for returned data

Possible values:daily monthly alltime

format
stringjson

Datatype for returned historical data

Possible values:csv json

Response

200

HideShow
Headers
Content-Type: text/csv
Body
[
    {
        "time": "2016-03-23 17:40:00",
        "average": 418.81
    },
    {
        "time": "2016-03-23 17:39:00",
        "average": 418.57
    },
    {
        "time": "2016-03-23 17:38:00",
        "average": 418.57
    },
    {
        "time": "2016-03-23 17:37:00",
        "average": 418.7
    },
    {
        "time": "2016-03-23 17:36:00",
        "average": 418.68
    },
    {
        "time": "2016-03-23 17:35:00",
        "average": 418.57
    },
]

Data Since Timestamp

GET https://apiv2.bitcoinaverage.com/indices/global/history/BTCUSD?since=1405394590
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

symbol
stringBTCUSD

Currency pair symbol

since
integer1405394590

Timestamp

Response

200

HideShow
Headers
Content-Type: text/csv
Body
[
    {
        "ts": 1460624400.0,
        "average": 424.06,
        "time": "2016-04-14 09:00:00"
    },
    {
        "ts": 1460620800.0,
        "average": 423.90,
        "time": "2016-04-14 08:00:00"
    },
    {
        "ts": 1460617200.0,
        "average": 424.14,
        "time": "2016-04-14 07:00:00"
    },
]

Price at Timestamp

GET https://apiv2.bitcoinaverage.com/indices/global/history/BTCUSD?at=1402476700
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

symbol
stringBTCUSD

Currency pair symbol

at
integer1402476700

Timestamp

Response

200

HideShow
Headers
Content-Type: text/csv
Body
{
  "average": 424.79,
  "time": "2016-04-14 00:00:00"
}

Exchange Data by Symbol

GET https://apiv2.bitcoinaverage.com/exchanges/all?symbol=LTCEUR
URI Parameters
HideShow
symbol
stringLTCEUR

Currency pair symbol

Response

200

HideShow
Headers
Content-Type: application/json
Body
[
  {
    "name": "kraken",
    "display_name": "Kraken",
    "url": "https://kraken.com/",
    "timestamp": 1470735708,
    "data_source": "api",
    "symbols": {
      "LTCEUR": {
        "last": 3.42,
        "volume": 865.72,
        "ask": 3.44,
        "bid": 3.41
      }
    }
  }
]

All Exchange Data

GET https://apiv2.bitcoinaverage.com/exchanges/all?crypto=BTC&fiat=USD,EUR
URI Parameters
HideShow
crypto
stringBTC

Crypto currency symbol

fiat
stringUSD,EUR

Fiat currency symbol

Response

200

HideShow
Headers
Content-Type: application/json
Body
[
    {
        "name": "bitcurex",
        "display_name": "Bitcurex",
        "url": "https://bitcurex.com/",
        "timestamp": 1458755176,
        "data_source": "api",
        "symbols": {
            "BTCPLN": {
                "ask": 1610.00,
                "bid": 1609.00,
                "last": 1610.00,
                "volume": 47.22
            },
            "BTCEUR": {
                "ask": 373.10,
                "bid": 370.23,
                "last": 373.10,
                "volume": 98.86
            }
        }
    },
    {
        "name": "bitex",
        "display_name": "Bitex.la",
        "url": "https://bitex.la/",
        "timestamp": 1458755194,
        "data_source": "api",
        "symbols": {
            "BTCUSD": {
                "ask": 417.00,
                "bid": 415.57,
                "last": 416.70,
                "volume": 133.54
            }
        }
    },
]

Per Exchange Data

GET https://apiv2.bitcoinaverage.com/exchanges/bitstamp
URI Parameters
HideShow
exchange_name
stringbitstamp

Exchange Name

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "name": "bitstamp",
  "display_name": "Bitstamp",
  "url": "https://bitstamp.net/",
  "timestamp": 1458755191,
  "data_source": "api",
  "symbols": {
    "BTCUSD": {
      "ask": 417.79,
      "bid": 417.33,
      "last": 417.38,
      "volume": 4418.99
    }
  }
}

Ignored Exchanges

GET https://apiv2.bitcoinaverage.com/exchanges/ignored
URI Parameters
HideShow
state
stringignored

Exchange's status

Possible values:ignored inactive

Response

200

HideShow
Headers
Content-Type: application/json
Body
[
  {
    "name": "cointrader",
    "display_name": "Cointrader",
    "url": "https://www.cointrader.net/",
    "timestamp": 1458755278,
    "ignore_reason": "Exchange has no daily volume"
  }
]

Get integration counts

GET https://apiv2.bitcoinaverage.com/exchanges/count
Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "included": 44,
  "ignored": 3,
  "count": 47,
  "success": true
}

Get Outliers

GET https://apiv2.bitcoinaverage.com/exchanges/outliers
Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "last": {
    "BTCUSD": {
      "localbitcoins": 489.99
    },
    "BTCEUR": {
      "hitbtc": 452
    },
    "BTCCAD": {
      "localbitcoins": 586.59
    }
  },
  "bid": {
    "BTCUSD": {
      "independentreserve": 414.06
    },
    "BTCEUR": {
      "btcgreece": 367.87
    }
  },
  "ask": {
    "BTCUSD": {
      "bitkonan": 438.99
    }
  }
}

Exchange Weights

GET https://apiv2.bitcoinaverage.com/weighting/exchanges
Response

200

HideShow
Headers
Content-Type: application/json
Body
{
    "bit2c": {
        "BTCILS": 100.00
    },
    "bitbargain": {
        "BTCGBP": 9.00
    },
    "bitbay": {
        "BTCPLN": 87.00,
        "BTCEUR": 0.00
    },
    "bitcoin_co_id": {
        "BTCIDR": 100.00
    },
    "bitcoin_de": {
        "BTCEUR": 3.00
    },
    "bitcurex": {
        "BTCPLN": 12.00,
        "BTCEUR": 0.00
    },
}

Currency Weights

GET https://apiv2.bitcoinaverage.com/weighting/currencies
Response

200

HideShow
Headers
Content-Type: application/json
Body
{
    "BTCUSD": {
        "market_share": 56.77
    },
    "BTCEUR": {
        "market_share": 25.81
    },
    "BTCHKD": {
        "market_share": 3.54
    },
    "BTCSGD": {
        "market_share": 2.37
    },
    "BTCRUB": {
        "market_share": 2.02
    },
    "BTCGBP": {
        "market_share": 1.87
    },
}

Perform Conversion

GET https://apiv2.bitcoinaverage.com/convert/global?from=BTC&to=USD&amount=1
URI Parameters
HideShow
market
stringglobal

Market

Possible values:global local

from
stringBTC

Source currency code

to
stringUSD

Target currency code

amount
number1 1

Amount to convert

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "success": true,
  "time": "14-04-2016 13:55:32",
  "price": 424.93
}

Price at Transaction Time

GET https://apiv2.bitcoinaverage.com/blockchain/tx_price/BTCUSD/8a3b4394ba811a9e2b0bbf3cc56888d053ea21909299b2703cdc35e156c860ff
URI Parameters
HideShow
symbol
stringBTCUSD

crypto-fiat pair

hash
string8a3b4394ba811a9e2b0bbf3cc56888d053ea21909299b2703cdc35e156c860ff

valid transaction hash

Response

200

HideShow
Headers
Content-Type: application/json
Body
{
  "time": "2016-05-17 00:00:00",
  "average": 457.91
}