API authorization

To access CoinAPI, we need an API key. This key makes authorized API calls.

How to request an API key

We can easily request an API Key from CoinAPI. From the CoinAPI product homepage, use the following steps:

  1. Click the "GET A FREE API KEY" button. This will redirect the site to the pricing page. A pop-up will appear on top of it.
  2. Fill in the required details in the pop-up and click the "GET A FREE API KEY" button to proceed.

If you're on the CoinAPI documentation page, refer to the following steps:

  1. In the top-right corner, inside the navigation bar, enter your email in the placeholder.
  2. Click the "GET A FREE API KEY" button. The button and the email placeholder will disappear, and a "Check your mailbox" message will appear in their place.

Note: CoinAPI will take a minute to respond to the request and email the API key to the provided email address.

How to use an API key

We need to provide the API key in every HTTP request. There are two ways of inserting an API key inside the HTTP request:

As a custom header

For access authorization, we’ll provide an API key by passing the key in a custom header called X-CoinAPI-Key. We recommend using this method, especially when working in the production environment. Here's a code snippet of how we can do this to make an HTTP get request in Python:

from requests import get
# Define API key here
API_KEY = '<PLACE YOUR API KEY HERE>'
# Define endpoint url here
url = "https://rest-sandbox.coinapi.io/v1/{endpoint_name}"
# Define header elements here
headers = {'authorization': API_KEY}
# Define URL parameters here
params = {}
# Making GET request
res = get(url=url, headers=headers, params=params)

As a query parameter

We can also pass the API key as a string to an additional query parameter called apikey for access authorization. It's best only to use this method in the development phase since parameters are not secure in an HTTP request. Here's a code snippet of how we can do this to make an HTTP get request in Python:

from requests import get
# Define API key here
API_KEY = '<PLACE YOUR API KEY HERE>'
# Define endpoint url here
url = "https://rest-sandbox.coinapi.io/v1/{endpoint_name}?apikey=%s" % API_KEY
# Define header elements here
headers = {}
# Define URL parameters here
params = {
    # If not included in the url itself, we can pass the API key
    # to the params argument. Just uncomment the line below:
    # 'api_key': API_KEY
}
# Making GET request
res = get(url=url, headers=headers, params=params)

How to save an API key

Let’s save the API key that we receive for use throughout the course. To do so:

  1. Click the “Edit” button in the following widget.
  2. Paste the API key in the API_KEY field.
  3. Click the “Save” button.

Now, the API key is automatically saved throughout the course. 

# Define API key here
API_KEY = "{{API_KEY}}"
# Function to fetch exchange rate using CoinAPI
fetch_btc_usd_exchange_rate(API_KEY)

API request and concurrency limits

CoinAPI limits the number of requests and the number of concurrent API calls we can make based on the plan we have with them.

The course is designed so that you can complete it using the free plan, so don’t worry about purchasing a plan exclusively for this course. Also, we'll be displaying the remaining calls on every successful code run on this course. These limits are also stated in the HTTP header of every successful response.

Request limits

A request limit represents the maximum number of requests we can make to the API within 24 hours, depending on our subscription. CoinAPI will reset the requests limit on a 24 hours basis.

It's important to note that these requests don’t always equal a single API call, as one API call could be equal to several requests. This happens if we use the limit query parameter or the API call itself is equal to several calls by design.

With the limit parameter, every 100 data points will have a cost of 1 request. For example, if we pass 200 to the limit parameter, the API call will have a cost of 2 requests.

The following represents the request limit details in the HTTP header:

HTTP header

Type

Description

X-RateLimit-Used

int

This parameter represents the number of requests used in the 24 hours timeframe.

X-RateLimit-Limit

int

This parameter represents the request limit allotted to the API key for a 24 hours timeframe.

X-RateLimit-Remaining

int

This parameter represents the number of remaining requests available in the 24 hours timeframe.

X-RateLimit-Cost

int

This parameter represents the cost in terms of requests for the API call.

X-RateLimit-Reset

timestring

This parameter represents the timestamp when the request limit will reset.

Note: All timestamps received from CoinAPI are from the UTC timezone and follow the ISO 8601 standard for all input and output time values. It can be in either the yyyy-MM-ddTHH:mm:ss.fffffff or yyyyMMddTHHmmssfffffff format.

Concurrency limits

A concurrency limit represents the maximum number of concurrent requests we can make to the API, depending on our subscription. The remaining concurrent calls we can make will decrease on each concurrent API call, and when the call finishes, it will increase. The following represents the concurrency limit details in the HTTP header:

HTTP Header

Type

Description

X-ConcurrencyLimit-Limit

int

This parameter represents the concurrency limit allotted to the API key.

X-ConcurrencyLimit-Remaining

int

This parameter represents the number of remaining concurrent API calls available on the API key.

Time conventions

All timestamps received from CoinAPI are from the UTC timezone and follow the ISO 8601 standard for all input and output time values. It can be in any of the following formats:

  • yyyy-MM-ddTHH:mm:ss.fffffff
  • yyyy-MM-ddTHH:mm:ss.fff
  • yyyy-MM-ddTHH:mm:ss
  • yyyy-MM-ddTHH:mm
  • yyyy-MM-ddTHH
  • yyyy-MM-dd
  • yyyyMMddTHHmmssfffffff
  • yyyyMMddTHHmmssfff
  • yyyyMMddTHHmmss
  • yyyyMMddTHHmm
  • yyyyMMddTHH
  • yyyyMMdd

The following table briefly describes the format modifiers we use with the ISO 8601 standard time value:

Format specifier

Description

yyyy

This specifier represents the year as a four-digit number.

MM

This specifier represents the month as a two-digit number between 01 to 12.

dd

This specifier represents the day as a two-digit number between 01 to 31.

HH

This specifier represents the hour of a 24-hour clock as a two-digit number between 00 to 23.

mm

This specifier represents the minute as a two-digit number between 00 to 59.

ss

This specifier represents the second as a two-digit number between 00 to 59.

fff

This specifier represents milliseconds.

fffffff

This specifier represents ten millionths of a second.