Blockfrost.io ~ API Documentation (0.1.25)

Download OpenAPI specification:Download

Blockfrost is an API as a service that allows users to interact with the Cardano blockchain and parts of its ecosystem.

Tokens

After signing up on https://blockfrost.io, a project_id token is automatically generated for each project. HTTP header of your request MUST include this project_id in order to authenticate against Blockfrost servers.

Available networks

At the moment, you can use the following networks. Please, note that each network has its own project_id.

NetworkEndpoint
Cardano mainnethttps://cardano-mainnet.blockfrost.io/api/v0
Cardano testnethttps://cardano-testnet.blockfrost.io/api/v0
InterPlanetary File Systemhttps://ipfs.blockfrost.io/api/v0

Concepts

  • All endpoints return either a JSON object or an array.
  • Data is returned in ascending (oldest first, newest last) order.
    • You might use the ?order=desc query parameter to reverse this order.
  • By default, we return 100 results at a time. You have to use ?page=2 to list through the results.
  • All time and timestamp related fields are in milliseconds of UNIX time.
  • All amounts are returned in Lovelaces, where 1 ADA = 1 000 000 Lovelaces.
  • Addresses, accounts and pool IDs are in Bech32 format.
  • All values are case sensitive.
  • All hex encoded values are lower case.
  • Examples are not based on real data. Any resemblance to actual events is purely coincidental.
  • We allow to upload files up to 100MB of size to IPFS. This might increase in the future.

Errors

HTTP Status codes

The following are HTTP status code your application might receive when reaching Blockfrost endpoints and it should handle all of these cases.

  • HTTP 400 return code is used when the request is not valid.
  • HTTP 402 return code is used when the projects exceed their daily request limit.
  • HTTP 403 return code is used when the request is not authenticated.
  • HTTP 404 return code is used when the resource doesn't exist.
  • HTTP 418 return code is used when the user has been auto-banned for flooding too much after previously receiving error code 402 or 429.
  • HTTP 429 return code is used when the user has sent too many requests in a given amount of time and therefore has been rate-limited.
  • HTTP 500 return code is used when our endpoints are having a problem.

Error codes

An internal error code number is used for better indication of the error in question. It is passed using the following payload.

{
  "status_code": 403,
  "error": "Forbidden",
  "message": "Invalid project token."
}

Limits

There are two types of limits we are enforcing:

The first depends on your plan and is the number of request we allow per day. We defined the day from midnight to midnight of UTC time.

The second is rate limiting. We limit an end user, distinguished by IP address, to 10 requests per second. On top of that, we allow each user to send burst of 500 requests, which cools off at rate of 10 requests per second. In essence, a user is allowed to make another whole burst after (currently) 500/10 = 50 seconds. E.g. if a user attemtps to make a call 3 seconds after whole burst, 30 requests will be processed. We believe this should be sufficient for most of the use cases. If it is not and you have a specific use case, please get in touch with us, and we will make sure to take it into account as much as we can.

SDKs

We support a number of SDKs that will help you in developing your application on top of Blockfrost.

Programming languageSDK
JavaScriptblockfrost-js

Authentication

ApiKeyAuth

There are multiple token types available based on network you choose when creating a Blockfrost a project, for a list of token types see Available networks

Security Scheme Type API Key
Header parameter name: project_id

Health

Root endpoint

Root endpoint has no other function than to point end users to documentation.

Responses

Response samples

Content type
application/json
{}

Backend health status

Return backend status as a boolean. Your application should handle situations when backend for the given chain is unavailable.

Responses

Response samples

Content type
application/json
{
  • "is_healthy": true
}

Current backend time

This endpoint provides the current UNIX time. Your application might use this to verify if the client clock is not out of sync.

Responses

Response samples