openapi: 3.0.3
info:
version: 0.1.87
title: Blockfrost.io ~ API Documentation
x-logo:
url: 'https://staging.blockfrost.io/images/logo.svg'
altText: Blockfrost
contact:
name: Blockfrost Team
url: 'https://blockfrost.io'
email: [email protected]
license:
name: MIT
url: 'https://opensource.org/licenses/MIT'
termsOfService: 'https://blockfrost.io/terms'
description: >
Blockfrost is an API as a service that allows users to interact with the
Cardano blockchain, Midnight blockchain, and parts of their ecosystems.
## 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`.
<table>
<tbody>
<tr>
<td>
<b>Network</b>
</td>
<td>
<b>Endpoint</b>
</td>
</tr>
<tr>
<td>Cardano mainnet</td>
<td>
<code>https://cardano-mainnet.blockfrost.io/api/v0</code>
</td>
</tr>
<tr>
<td>Cardano preprod</td>
<td>
<code>https://cardano-preprod.blockfrost.io/api/v0</code>
</td>
</tr>
<tr>
<td>Cardano preview</td>
<td>
<code>https://cardano-preview.blockfrost.io/api/v0</code>
</td>
</tr>
<tr>
<td>Midnight mainnet</td>
<td>
<code>https://midnight-mainnet.blockfrost.io/api/v0</code>
</td>
</tr>
<tr>
<td>InterPlanetary File System</td>
<td>
<code>https://ipfs.blockfrost.io/api/v0</code>
</td>
</tr>
</tbody>
</table>
## Concepts
* All endpoints return either a JSON object or an array.
* Data is returned in *ascending* (oldest first, newest last) order, if not
stated otherwise.
* 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 (except `server_time`) are in
seconds 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.
* Only pinned IPFS files are counted towards the IPFS quota.
* Non-pinned IPFS files are subject to regular garbage collection and will
be removed unless pinned.
* We allow maximum of 100 queued pins per IPFS user.
## 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 `425` return code is used in Cardano networks, when the user has
submitted a transaction when the mempool is already full, not accepting new
txs straight away.
* HTTP `425` return code is used in IPFS network, when the user has
submitted a pin when the pin queue is already full, not accepting new pins
straight away.
* 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.
```json
{
"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 attempts
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.
<table>
<tbody>
<tr>
<td><b>Programming language</b></td>
<td><b>SDK</b></td>
</tr>
<tr>
<td>JavaScript</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-js">blockfrost-js</a>
</td>
</tr>
<tr>
<td>Haskell</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-haskell">blockfrost-haskell</a>
</td>
</tr>
<tr>
<td>Python</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-python">blockfrost-python</a>
</td>
</tr>
<tr>
<td>Rust</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-rust">blockfrost-rust</a>
</td>
</tr>
<tr>
<td>Golang</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-go">blockfrost-go</a>
</td>
</tr>
<tr>
<td>Ruby</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-ruby">blockfrost-ruby</a>
</td>
</tr>
<tr>
<td>Java</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-java">blockfrost-java</a>
</td>
</tr>
<tr>
<td>Scala</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-scala">blockfrost-scala</a>
</td>
</tr>
<tr>
<td>Swift</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-swift">blockfrost-swift</a>
</td>
</tr>
<tr>
<td>Kotlin</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-kotlin">blockfrost-kotlin</a>
</td>
</tr>
<tr>
<td>Elixir</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-elixir">blockfrost-elixir</a>
</td>
</tr>
<tr>
<td>.NET</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-dotnet">blockfrost-dotnet</a>
</td>
</tr>
<tr>
<td>Arduino</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-arduino">blockfrost-arduino</a>
</td>
</tr>
<tr>
<td>PHP</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-php">blockfrost-php</a>
</td>
</tr>
<tr>
<td>Crystal</td>
<td>
<a href="https://github.com/blockfrost/blockfrost-crystal">blockfrost-crystal</a>
</td>
</tr>
</tbody>
</table>
## Midnight API
The Midnight Indexer API exposes a GraphQL API that enables clients to query
and subscribe to blockchain data — blocks, transactions, contracts, and
wallet-related events — indexed from the Midnight blockchain.
Available networks: `mainnet`, `preprod`, `preview`
| Service | URL | Protocol |
|---------|-----|----------|
| **Indexer HTTP API** | `https://midnight-{network}.blockfrost.io/api/v0` |
HTTP POST (GraphQL) |
| **Indexer Subscriptions API** |
`wss://midnight-{network}.blockfrost.io/api/v0/ws` | WebSocket |
| **Node RPC** | `https://rpc.midnight-{network}.blockfrost.io` | JSON-RPC |
For the full documentation — queries, mutations, subscriptions,
authentication options, and examples — see the Midnight GraphQL API
Reference:
[](./midnight/)
servers:
- url: 'https://cardano-mainnet.blockfrost.io/api/v0'
description: Cardano Mainnet network
- url: 'https://cardano-preprod.blockfrost.io/api/v0'
description: Cardano Preprod network
- url: 'https://cardano-preview.blockfrost.io/api/v0'
description: Cardano Preview network
- url: 'https://localhost:3000'
description: local
security:
- project_id: []
tags:
- name: Health
- name: Metrics
- name: Cardano » Accounts
- name: Cardano » Addresses
- name: Cardano » Assets
- name: Cardano » Blocks
- name: Cardano » Epochs
- name: Cardano » Governance
- name: Cardano » Ledger
- name: Cardano » Mempool
- name: Cardano » Metadata
- name: Cardano » Network
- name: Cardano » Pools
- name: Cardano » Scripts
- name: Cardano » Transactions
- name: Cardano » Utilities
- name: IPFS » Add
- name: IPFS » Gateway
- name: IPFS » Pins
paths:
/:
get:
tags:
- Health
summary: Blockfrost Root Endpoint
description: >
Root endpoint has no other function than to point end users to
documentation.
responses:
'200':
description: Information pointing to the documentation.
content:
application/json:
schema:
type: object
properties:
url:
type: string
example: 'https://blockfrost.io/'
version:
type: string
example: 0.1.0
required:
- url
- version
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/health:
get:
tags:
- Health
summary: Blockfrost Backend Health Status
security: []
description: >
Return backend status as a boolean. Your application should handle
situations when backend for the given chain is unavailable.
responses:
'200':
description: Return the boolean indicating the health of the backend.
content:
application/json:
schema:
type: object
properties:
is_healthy:
type: boolean
example: true
required:
- is_healthy
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/health/clock:
get:
tags:
- Health
summary: Blockfrost Current Backend Time
description: |
This endpoint provides the current UNIX time. Your application might
use this to verify if the client clock is not out of sync.
responses:
'200':
description: Return the current UNIX time in milliseconds.
content:
application/json:
schema:
type: object
properties:
server_time:
type: integer
format: int64
example: 1603400958947
required:
- server_time
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/blocks/latest:
get:
tags:
- Cardano » Blocks
summary: Blockfrost Latest Block
description: |
Return the latest block available to the backends, also known as the
tip of the blockchain.
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/blocks/latest/txs:
get:
tags:
- Cardano » Blocks
summary: Blockfrost Latest Block Transactions
description: Return the transactions within the latest block.
parameters:
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: >
Ordered by tx index in the block.
The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first,
newest last.
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content_txs'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/blocks/latest/txs/cbor:
get:
tags:
- Cardano » Blocks
summary: Blockfrost Latest Block Transactions with CBOR Data
description: >-
Return the transactions within the latest block, including CBOR
representations.
parameters:
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: >
Ordered by tx index in the block.
The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first,
newest last.
responses:
'200':
description: Return the contents of the block with CBOR data
content:
application/json:
schema:
$ref: '#/components/schemas/block_content_txs_cbor'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
'/blocks/{hash_or_number}':
get:
tags:
- Cardano » Blocks
summary: Blockfrost Specific Block
description: |
Return the content of a requested block.
parameters:
- in: path
name: hash_or_number
required: true
schema:
type: string
format: 64-character case-sensitive hexadecimal string or block number.
description: Hash or number of the requested block.
example: 4ea1ba291e8eef538635a53e59fddba7810d1679631cc3aed7c8e6c4091a516a
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
'/blocks/{hash_or_number}/next':
get:
tags:
- Cardano » Blocks
summary: Blockfrost Listing of Next Blocks
description: |
Return the list of blocks following a specific block.
parameters:
- in: path
name: hash_or_number
required: true
schema:
type: string
format: 64-character case-sensitive hexadecimal string or block number.
description: Hash of the requested block.
example: 5ea1ba291e8eef538635a53e59fddba7810d1679631cc3aed7c8e6c4091a516a
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content_array'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
'/blocks/{hash_or_number}/previous':
get:
tags:
- Cardano » Blocks
summary: Blockfrost Listing of Previous Blocks
description: |
Return the list of blocks preceding a specific block.
parameters:
- in: path
name: hash_or_number
required: true
schema:
type: string
format: 64-character case-sensitive hexadecimal string or block number.
description: Hash of the requested block
example: '4873401'
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content_array'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
'/blocks/slot/{slot_number}':
get:
tags:
- Cardano » Blocks
summary: Blockfrost Specific Block in a Slot
description: |
Return the content of a requested block for a specific slot.
parameters:
- in: path
name: slot_number
required: true
schema:
type: integer
format: slot number
description: Slot position for requested block.
example: 30895909
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
'/blocks/epoch/{epoch_number}/slot/{slot_number}':
get:
tags:
- Cardano » Blocks
summary: Blockfrost Specific Block in a Slot in an Epoch
description: |
Return the content of a requested block for a specific slot in an epoch.
parameters:
- in: path
name: epoch_number
required: true
schema:
type: integer
format: slot number
description: Epoch for specific epoch slot.
example: 219
- in: path
name: slot_number
required: true
schema:
type: integer
format: slot number
description: Slot position for requested block.
example: 30895909
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
'/blocks/{hash_or_number}/txs':
get:
tags:
- Cardano » Blocks
summary: Blockfrost Block Transactions
description: Return the transactions within the block.
parameters:
- in: path
name: hash_or_number
required: true
schema:
type: string
format: 64-character case-sensitive hexadecimal string or block number.
description: Hash of the requested block.
example: '4873401'
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: >
Ordered by tx index in the block.
The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first,
newest last.
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content_txs'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
'/blocks/{hash_or_number}/txs/cbor':
get:
tags:
- Cardano » Blocks
summary: Blockfrost Block Transactions with CBOR Data
description: >-
Return the transactions within the block, including CBOR
representations.
parameters:
- in: path
name: hash_or_number
required: true
schema:
type: string
format: 64-character case-sensitive hexadecimal string or block number.
description: Hash of the requested block.
example: '4873401'
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: >
Ordered by tx index in the block.
The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first,
newest last.
responses:
'200':
description: Return the contents of the block with CBOR data
content:
application/json:
schema:
$ref: '#/components/schemas/block_content_txs_cbor'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
'/blocks/{hash_or_number}/addresses':
get:
tags:
- Cardano » Blocks
summary: Blockfrost Addresses Affected in a Specific Block
description: >-
Return list of addresses affected in the specified block with additional
information, sorted by the bech32 address, ascending.
parameters:
- in: path
name: hash_or_number
required: true
schema:
type: string
format: 64-character case-sensitive hexadecimal string or block number.
description: Hash of the requested block.
example: '4873401'
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
responses:
'200':
description: Return the contents of the block
content:
application/json:
schema:
$ref: '#/components/schemas/block_content_addresses'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/genesis:
get:
tags:
- Cardano » Ledger
summary: Blockfrost Blockchain Genesis
description: Return the information about blockchain genesis.
responses:
'200':
description: Return the genesis parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/genesis_content'
'400':
$ref: '#/components/responses/400'
'403':
$ref: '#/components/responses/403'
'418':
$ref: '#/components/responses/418'
'429':
$ref: '#/components/responses/429'
'500':
$ref: '#/components/responses/500'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/governance/dreps:
get:
tags:
- Cardano » Governance
summary: Blockfrost Delegate Representatives (DReps)
description: Return the information about Delegate Representatives (DReps)
parameters:
- in: query
name: count
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 100
description: The number of results displayed on one page.
- in: query
name: page
required: false
schema:
type: integer
minimum: 1
maximum: 21474836
default: 1
description: The page number for listing the results.
- in: query
name: order
required: false
schema:
type: string
enum:
- asc
- desc
default: asc
description: >
The ordering of items from the point of view of the blockchain,
not the page listing itself. By default, we return oldest first,
n
# --- truncated at 32 KB (452 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/blockfrost/refs/heads/main/openapi/blockfrost-openapi.yaml