coinlayer API

The coinlayer API is capable of delivering accurate exchange rate data for more than 385 cryptocurrencies in real-time. Crypto data is gathered from some of the largest cryptocurrency exchanges, requested using HTTP GET and returned in straightforward JSON format. Thanks to a refined fallback algorithm availablity, consistency and reliablity of crypto data returned by the coinlayer API are at the highest level.

The API comes with a series of endpoints, functionalities and options. Find below a technical documentation containing descriptions, integration guides and examples in different programming languages.

Quickstart Tool

No time for a long read? Once signed up for a free or paid subscription plan you will be able to use our Quickstart Tool, allowing you to test any API endpoint at the click of a button.

Get a free API access key to start using the Quickstart tool.

Get free API Access Key

Getting Started

API Access Key

Your API access key is your unique authentication token used to gain access to the coinlayer API. You can find yours by logging in to your coinlayer account dashboard.

In order to authenticate with the API, simply append the access_key parameter to the API's base URL and set it to your API access key value.

Base URL:

https://api.coinlayer.com/

Append your API access key: Here is an example API call illustrating how to authenticate with the coinlayer API:

https://api.coinlayer.com/live
    ? access_key = YOUR_ACCESS_KEY

API Response

In the example API request above, the coinlayer API's live endpoint was used. Below you will see the standard API response in JSON format containing exchange rate data for all available cryptocurrencies.

{
  "success": true,
  "terms": "https://coinlayer.com/terms",
  "privacy": "https://coinlayer.com/privacy",
  "timestamp": 1529571067,
  "target": "USD",
  "rates": {
    "611": 0.389165,
    "ABC": 59.99,
    "ACP": 0.014931,
    "ACT": 0.15927,
    "ACT*": 0.14371,
    "ADA": 0.160502,
    "ADCN": 0.001406,
    "ADL": 121.5,
    "ADX": 0.427854,
    "ADZ": 0.02908,
    "AE": 2.551479,
    "AGI": 0.12555,
    "AIB": 0.005626,
    "AIDOC": 0.02605,
    [...]
  }
}

The basic structure of the counlayer API's JSON response is similar across all API endpoints. Throughout the API Endpoints section you will learn more about the meaning of each response object.

Available Endpoints

In total the coinlayer API is offering 6 API endpoints, each different in functionality. Find a quick summary below.

  • Live Data Query the API for the latest available exchange rate data.
  • Historical Data Look up crypto rates for a specific date.
  • Conversion Endpoint Convert amounts between cryptocurrencies and target currencies.
  • Time-Frame Data Query the API for crypto data in a specific period.
  • Change Data Retrieve data about rate fluctuation in a specific period.
  • List Endpoint Retrieve a list of all available cryptocurrencies and target currencies.

Connecting via HTTPS

All paid subscription plans available for the coinlayer API come with support for 256-bit SSL encryption. To connect to the API via HTTPS, simply use the https protocol instead of standard http.

JSONP Callbacks

The coinlayer API supports JSONP Callbacks, enabling you to enter a function name and cause the API to return your requested API result wrapped inside that function. In order to specify a callback, pass a function name into the API's callback GET parameter.

Example Request: In our example request we are specifying the function name to be MY_FUNCTION

https://api.coinlayer.com/134.201.250.155
    ? access_key = YOUR_ACCESS_KEY
    & callback = FUNCTION_NAME

Example Response: Your API response will be wrapped inside your preferred callback function.

FUNCTION_NAME (
  {
    "success": true,
    "terms": "https://coinlayer.com/terms",
    "privacy": "https://coinlayer.com/privacy",
    "timestamp": 1529571067,
    "target": "USD",
    "rates": {
      "611": 0.389165,
      "ABC": 59.99,
      "ACP": 0.014931,
      "ACT": 0.15927,
      [...]
    }
  }
)

Error Codes

Whenever a requested resource is not available or an API call fails for another reason, a JSON error is returned. Errors always come with an error code and a description.

Example Error: The following error is returned if your monthly API request volume has been exceeded.

{
  "success": false,
  "error": {
    "code": 104,
    "type": "monthly_limit_reached",
    "info": "Your monthly API request volume has been reached. Please upgrade your plan."    
  }
}

Other Errors:

Code Type Info
404 404_not_found The requested resource does not exist.
101 invalid_access_key No API Key was specified or an invalid API Key was specified.
103 invalid_api_function The requested API endpoint does not exist.
104 usage_limit_reached The maximum allowed API amount of monthly API requests has been reached.
105 function_access_restricted The current subscription plan does not support this API endpoint.
106 no_rates_available The current request did not return any results.
102 inactive_user The account this API request is coming from is inactive.
201 invalid_target_currency An invalid target currency has been entered.
202 invalid_currency_symbols One or more invalid symbols have been specified.
302 invalid_date An invalid date has been specified. [historical, convert]
403 invalid_conversion_amount No or an invalid amount has been specified. [convert]
501 no_timeframe_supplied No or an invalid timeframe has been specified. [timeframe]
502 invalid_start_date No or an invalid "start_date" has been specified. [timeframe, change]
503 invalid_end_date No or an invalid "end_date" has been specified. [timeframe, change]
504 invalid_time_frame An invalid timeframe has been specified. [timeframe, change]
505 time_frame_too_long The specified timeframe is too long, exceeding 365 days. [timeframe, change]

Endpoints

List Endpoint
Supported on: All Plans

The coinlayer API's list endpoint can be used to list all available crypto and standard (fiat) currencies. Available cryptocurrencies will be returned as objects containing additional details, such as maximum supply amount and icon URLs. To use this endpoint, simply attach list to the API's base URL, followed by your API access key.

Example API Request:

https://api.coinlayer.com/list
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

Parameter Description
access_key [Required] Your API access key.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.

Example API Response:

{
  "success": true,
  "crypto": {
    "611": {
      "symbol": "611",
      "name": "SixEleven",
      "name_full": "SixEleven (611)",
      "max_supply": 611000,
      "icon_url": "https://coinlayer.com/images/assets/coinlayer_icons/611.png"
    },
    "ABC": {
      "symbol": "ABC",
      "name": "AB-Chain",
      "name_full": "AB-Chain (ABC)",
      "max_supply": 210000000,
      "icon_url": "https://coinlayer.com/images/assets/coinlayer_icons/ABC.png"
    },
    [...]
  },
  "fiat": {
    "AED": "United Arab Emirates Dirham",
    "AFN": "Afghan Afghani",
    "ALL": "Albanian Lek",
    "AMD": "Armenian Dram",
    "ANG": "Netherlands Antillean Guilder",
    "AOA": "Angolan Kwanza",
    [...]
  }
}

Response Objects:

Object Description
success Returns true or false depending on whether or not the given API request was successful.
crypto > symbol Returns the symbol of the respective cryptocurrency.
crypto > name Returns the short name of the respective cryptocurrency.
crypto > name_full Returns the extended name of the respective cryptocurrency, including its symbol.
crypto > max_supply Returns the maximum amount of circulating supply of the respective cryptocurrency.
crypto > icon_url Returns an URL to a PNG icon of the respective cryptocurrency.

Live Data
Supported on: All Plans

The coinlayer API's live endpoint is used to get the latest crypto rates for all available or a specific set of cryptocurrencies. To use this endpoint, simply append live to your API request URL, followed by your API access key and any of your preferred options.

Example API Request:

https://api.coinlayer.com/live
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

Parameter Description
access_key [Required] Your API access key.
target [optional] Specify your preferred target currency. You can view all available symbols on the Target Currencies page.
symbols [optional] Specify one or multiple (comma-separated) cryptocurrency symbols to be included in your API result. You can view all available values on the Available Cryptocurrencies page.
expand [optional] Set to 1 to receive extended results. Learn more about Extended Results.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.

Example API Response:

{
  "success": true,
  "terms": "https://coinlayer.com/terms",
  "privacy": "https://coinlayer.com/privacy",
  "timestamp": 1529571067,
  "target": "USD",
  "rates": {
    "611": 0.389165,
    "ABC": 59.99,
    "ACP": 0.014931,
    "ACT": 0.15927,
    "ACT*": 0.14371,
    "ADA": 0.160502,
    "ADCN": 0.001406,
    "ADL": 121.5,
    "ADX": 0.427854,
    "ADZ": 0.02908,
    "AE": 2.551479,
    "AGI": 0.12555,
    "AIB": 0.005626,
    "AIDOC": 0.02605,
    [...]
  }
}

Response Objects:

Object Description
success Returns true or false depending on whether or not the given API request was successful.
terms Returns a URL leading to the coinlayer Terms of Service.
privacy Returns a URL leading to the coinlayer Privacy Policy.
timestamp Returns the exact time (UTC timestamp) the given crypto data was collected.
target Returns the default or specified target currency.
rates Returns a JSON array containing the requested cryptocurrency data.

Historical Data
Supported on: All Plans

Using the coinlayer API's Historical Rates endpoint you will be able to query the API for historical crypto data all the way back to the year 2011. To use this endpoint, simply append a date (format: YYYY-MM-DD) of your choice to the API's base URL, followed by your API access key and any of your preferred additional options.

Example API Request:

https://api.coinlayer.com/2018-04-30
    ? access_key = YOUR_ACCESS_KEY

Request Parameters:

Parameter Description
YYYY-MM-DD [Required] Append a date of your choice in YYYY-MM-DD format.
access_key [Required] Your API access key.
target [optional] Specify your preferred target currency. You can view all available symbols on the Target Currencies page.
symbols [optional] Specify one or multiple (comma-separated) cryptocurrency symbols to be included in your API result. You can view all available values on the Available Cryptocurrencies page.
expand [optional] Set to 1 to receive extended results. Learn more about Extended Results.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.

Example API Response:

{
  "success": true,
  "terms": "https://coinlayer.com/terms",
  "privacy": "https://coinlayer.com/privacy",
  "timestamp": 1525132744,
  "target": "USD",
  "historical": true,
  "date": "2018-04-30",
  "rates": {
    "611": 0.389165,
    "ABC": 59.99,
    "ACP": 0.014931,
    "ACT": 0.37332,
    "ACT*": 0.352401,
    "ADA": 0.340976,
    "ADCN": 0.003209,
    "ADL": 121.551125,
    "ADX": 1.074753,
    "ADZ": 0.02168,
    "AE": 4.423674,
    "AGI": 0.22478,
    "AIB": 0.005626,
    [...]
  }
}

Response Objects:

Object Description
success Returns true or false depending on whether or not the given API request was successful.
terms Returns a URL leading to the coinlayer Terms of Service.
privacy Returns a URL leading to the coinlayer Privacy Policy.
timestamp Returns the exact time (UTC timestamp) the given crypto data was collected.
target Returns the default or specified target currency.
historical Returns true whenever historical rates are requested.
date Returns the date for which historical rates are requested.
rates Returns a JSON array containing the requested cryptocurrency data.

Conversion Endpoint
Supported on: Basic Plan and higher

The coinlayer API can also be used to convert amount between any one cryptocurrency and standard (fiat) currency. To convert currencies, simply use the API's convert endpoint and append from, to and amount parameters.

Example API Request:

https://api.coinlayer.com/convert
    ? access_key = YOUR_ACCESS_KEY
    & from = BTC
    & to = ETH
    & amount = 10

Request Parameters:

Parameter Description
access_key [Required] Your API access key.
from [Required] Specify the code of the currency to convert from.
to [Required] Specify the code of the currency to convert to.
amount [Required] Specify the amount to be converted.
date [optional] Specify a date (format: YYYY-MM-DD) to use historical rates for this conversion.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.

Example API Response:

{
  "success": true,
  "terms": "https://coinlayer.com/terms",
  "privacy": "https://coinlayer.com/privacy",
  "query": {
    "from": "BTC",
    "to": "ETH",
    "amount": 10
  },
  "info": {
    "timestamp": 1529790006,
    "rate": 12.960872
  },
  "result": 129.60872
}

Response Objects:

Object Description
success Returns true or false depending on whether or not the given API request was successful.
terms Returns a URL leading to the coinlayer Terms of Service.
privacy Returns a URL leading to the coinlayer Privacy Policy.
query > from Returns the code of the currency converted from.
query > to Returns the code of the currency converted to.
query > amount Returns the amount converted.
info > timestamp Returns the exact time (UTC timestamp) the given crypto data was collected.
info > rate Returns exchange rate used for this conversion.
result Returns the conversion result.

Time-Frame Data
Supported on: Professional Plan and higher

Using the coinlayer API's timeframe endpoint you will be able to query the API for time-series crypto data between two dates of your choice (maximum period: 365 days). To use this endpoint, simply append timeframe to your API request URL and specify start_date and end_date.

Example API Request:

https://api.coinlayer.com/timeframe
    ? access_key = YOUR_ACCESS_KEY
    & start_date = 2018-04-01
    & end_date = 2018-04-30
    & symbols = BTC,ETH

Request Parameters:

Parameter Description
access_key [Required] Your API access key.
start_date [Required] Specify a start date (format: YYYY-MM-DD) for your time frame.
end_date [Required] Specify an end date (format: YYYY-MM-DD) for your time frame.
target [optional] Specify your preferred target currency. You can view all available symbols on the Target Currencies page.
symbols [optional] Specify one or multiple (comma-separated) cryptocurrency symbols to be included in your API result. You can view all available values on the Available Cryptocurrencies page.
expand [optional] Set to 1 to receive extended results. Learn more about Extended Results.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.

Example API Response:

{
  "success": true,
  "terms": "https://coinlayer.com/terms",
  "privacy": "https://coinlayer.com/privacy",
  "timeframe": true,
  "start_date": "2018-04-01",
  "end_date": "2018-04-30",
  "target": "USD",
  "rates": {
    "2018-04-01": {
      "BTC": 6903.113849,
      "ETH": 383.02749
    },
    "2018-04-02": {
      "BTC": 7111.72678,
      "ETH": 387.273437
    },
    "2018-04-03": {
      "BTC": 7490.777653,
      "ETH": 421.655884
    },
    [...]
  }
}

Response Objects:

Object Description
success Returns true or false depending on whether or not the given API request was successful.
terms Returns a URL leading to the coinlayer Terms of Service.
privacy Returns a URL leading to the coinlayer Privacy Policy.
timeframe Returns true whenever a request to the timeframe is made.
start_date Returns the requested start date (format: YYYY-MM-DD).
end_date Returns the requested end date (format: YYYY-MM-DD).
target Returns the default or specified target currency.
rates > YYYY-MM-DD Returns a JSON object containing crypto data for each day in the requested period.

Change Data
Supported on: Professional Plus Plan and higher

Using the coinlayer API you may also request fluctuation data for any number of cryptocurrencies within a specific period of time (maximum period: 365 days). To make use of this feature, simply append the API's change to the base URL, followed by your API access key.

Note: If no start_date and end_date parameters are provided the API will default to yesterday (end of day) as start date and today (live rate) as end date.

Example API Request:

https://api.coinlayer.com/change
    ? access_key = YOUR_ACCESS_KEY
    & start_date = 2018-04-01
    & end_date = 2018-04-30
    & symbols = BTC,ETH,XRP

Request Parameters:

Parameter Description
access_key [Required] Your API access key.
start_date [optional] Specify a start date (format: YYYY-MM-DD) for your time frame.
end_date [optional] Specify an end date (format: YYYY-MM-DD) for your time frame.
target [optional] Specify your preferred target currency. You can view all available symbols on the Target Currencies page.
symbols [optional] Specify one or multiple (comma-separated) cryptocurrency symbols to be included in your API result. You can view all available values on the Available Cryptocurrencies page.
callback [optional] Specify a JSONP callback function name according to the JSONP Callbacks section.

Example API Response:

{
  "success": true,
  "terms": "https://coinlayer.com/terms",
  "privacy": "https://coinlayer.com/privacy",
  "change": true,
  "start_date": "2018-04-01",
  "end_date": "2018-04-30",
  "target": "USD",
  "rates": {
    "BTC": {
      "start_rate": 6903.113849,
      "end_rate": 9245.982724,
      "change": 2342.86887,
      "change_pct": 1.33939305
    },
    "ETH": {
      "start_rate": 383.02749,
      "end_rate": 670.440229,
      "change": 287.412739,
      "change_pct": 1.75037105
    },
    "XRP":{
      "start_rate": 0.482917,
      "end_rate": 0.831833,
      "change": 0.348916,
      "change_pct": 1.72251753
    }
  }
} 

Response Objects:

Object Description
success Returns true or false depending on whether or not the given API request was successful.
terms Returns a URL leading to the coinlayer Terms of Service.
privacy Returns a URL leading to the coinlayer Privacy Policy.
change Returns true whenever a request to the change is made.
start_date Returns the requested start date (format: YYYY-MM-DD).
end_date Returns the requested end date (format: YYYY-MM-DD).
target Returns the default or specified target currency.
rates > start_rate Returns the cryptocurrency's exchange rate at the start date.
rates > end_rate Returns the cryptocurrency's exchange rate at the end date.
rates > change Returns the absolute margin between start and end rate.
rates > change_pct Returns the percentage change within the specified period of time.

Options

Specify Symbols
Supported on: All Plans

Supported API Endpoints: Live, Historical, Time-Frame, Change.

The API's symbols parameter can be used in conjunction with most API endpoints to limit the number of output cryptocurrencies. This parameter can take either one single cryptocurrency value or multiple, comma-separated values.

  [...]
  & symbols = BTC,ETH,XRP
  [...]

The use of this parameter is especially useful to reduce bandwidth and increase the coinlayer API's response time.

Specify Target Currency
Supported on: Basic Plan and higher

Supported API Endpoints: Live, Historical, Time-Frame.

By default, cryptocurrency rates returned by the coinlayer API always translate to US Dollars. Customers subscribed to the Basic Plan or higher can use the API's target parameter to change the Target Currency to any other supported fiat currency code.

  [...]
  & target = EUR
  [...]

The API supports 166 world currencies as target currencies. You can find a list of all supported target currency codes here.

Extended Results
Supported on: Basic Plan and higher

Supported API Endpoints: Live, Historical, Time-Frame.

Basic Plan customers may also append the expand and set it to 1 in order to cause the coinlayer API to return a number of additional fields with an API response.

Example API Request: In this example the Live Rates Endpoint is used.

https://api.coinlayer.com/live
    ? access_key = YOUR_ACCESS_KEY
    & expand = 1

Example API Response:

{
  "success": true,
  "terms": "https://coinlayer.com/terms",
  "privacy": "https://coinlayer.com/privacy",
  "timestamp": 1529836865,
  "target": "USD",
  "rates": {
    "BTC": {
      "rate": 5948.023376,
      "high": 6499.89998,
      "low": 5657,
      "vol": 3665680000,
      "cap": 101785026595.74292,
      "sup": 17112412,
    },
    "ETH": {
      "rate": 449.864211,
      "high": 500,
      "low": 432.547195,
      "vol": 1918470000,
      "cap": 45109034289.89332,
      "sup": 100272556,
    },
    [...]
  } 
}

Response Objects:

Object Description
success Returns true or false depending on whether or not the given API request was successful.
terms Returns a URL leading to the coinlayer Terms of Service.
privacy Returns a URL leading to the coinlayer Privacy Policy.
timestamp Returns the exact time (UTC timestamp) the given crypto data was collected.
target Returns the default or specified target currency.
rates > rate Returns the exchange rate for the requested cryptocurrency.
rates > high Returns the highest midpoint exchange rate recorded on the requested date.
rates > low Returns the lowest midpoint exchange rate recorded on the requested date.
rates > vol Returns the volume of cryptocurrency exchanged on the requested date.
rates > cap Returns the current market cap of the given cryptocurrency.
rates > sup Returns the current supply amount of the given cryptocurrency.

Sample Code

PHP (cURL)

Real-time rates: Find below a simple PHP example for getting exchange rate data via the coinlayer API's live endpoint.

// set API Endpoint and API key 
$endpoint = 'live';
$access_key = 'YOUR_ACCESS_KEY';

// Initialize CURL:
$ch = curl_init('https://api.coinlayer.com/api/'.$endpoint.'?access_key='.$access_key.'');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// Store the data:
$json = curl_exec($ch);
curl_close($ch);

// Decode JSON response:
$exchangeRates = json_decode($json, true);

// Access the exchange rate values, e.g. GBP:
echo $exchangeRates['rates']['BTC'];

Convert currencies: Here is how to convert currencies using PHP cURL.

// set API Endpoint, access key, required parameters
$endpoint = 'convert';
$access_key = 'YOUR_ACCESS_KEY';

$from = 'BTC';
$to = 'GBP';
$amount = 10;

// initialize CURL:
$ch = curl_init('https://api.coinlayer.com/api/'.$endpoint.'?access_key='.$access_key.'&from='.$from.'&to='.$to.'&amount='.$amount.'');   
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

// get the JSON data:
$json = curl_exec($ch);
curl_close($ch);

// Decode JSON response:
$conversionResult = json_decode($json, true);

// access the conversion result
echo $conversionResult['result'];

JavaScript (jQuery.ajax)

Real-time rates: Find below a simple jQuery.ajax example for getting exchange rate data via the cpinlayer API's live endpoint.

// set endpoint and your API access key
endpoint = 'live'
access_key = 'YOUR_ACCESS_KEY';

// get the most recent exchange rates via the "live" endpoint:
$.ajax({
    url: 'https://api.coinlayer.com/api/' + endpoint + '?access_key=' + access_key,   
    dataType: 'jsonp',
    success: function(json) {

        // exchange rata data is stored in json.rates
        alert(json.rates.BTC);
        
        // target currency is stored in json.target
        alert(json.target);
        
        // timestamp can be accessed in json.timestamp
        alert(json.timestamp);
        
    }
});

Convert currencies: Here is how to convert currencies using jQuery.ajax.

// set endpoint and your API key
endpoint = 'convert';
access_key = 'YOUR_ACCESS_KEY';

// define from currency, to currency, and amount
from = 'BTC';
to = 'GBP';
amount = '10';

// execute the conversion using the "convert" endpoint:
$.ajax({
    url: 'https://api.coinlayer.com/api/' + endpoint + '?access_key=' + access_key +'&from=' + from + '&to=' + to + '&amount=' + amount,   
    dataType: 'jsonp',
    success: function(json) {

        // access the conversion result in json.result
        alert(json.result);
                
    }
});

Any questions? We're happy to help! Contact Support