Blockfrost API
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…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
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.
Network
Endpoint
Cardano mainnet
https://cardano-mainnet.blockfrost.io/api/v0
Cardano preprod
https://cardano-preprod.blockfrost.io/api/v0
Cardano preview
https://cardano-preview.blockfrost.io/api/v0
Midnight mainnet
https://midnight-mainnet.blockfrost.io/api/v0
InterPlanetary File System
https://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, if not stated otherwise.
- You might use the
?order=descquery parameter to reverse this order. - By default, we return 100 results at a time. You have to use
?page=2to 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
400return code is used when the request is not valid. - HTTP
402return code is used when the projects exceed their daily request limit. - HTTP
403return code is used when the request is not authenticated. - HTTP
404return code is used when the resource doesn't exist. - HTTP
418return code is used when the user has been auto-banned for flooding too much after previously receiving error code402or429. - HTTP
425return 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
425return 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
429return code is used when the user has sent too many requests in a given amount of time and therefore has been rate-limited. - HTTP
500return 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 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.
Programming language
SDK
JavaScript
blockfrost-js
Haskell
blockfrost-haskell
Python
blockfrost-python
Rust
blockfrost-rust
Golang
blockfrost-go
Ruby
blockfrost-ruby
Java
blockfrost-java
Scala
blockfrost-scala
Swift
blockfrost-swift
Kotlin
blockfrost-kotlin
Elixir
blockfrost-elixir
.NET
blockfrost-dotnet
Arduino
…
Endpoints 125
Health
- GETRoot endpoint
/Root endpoint has no other function than to point end users to documentation. - GETBackend health status
/healthReturn backend status as a boolean. Your application should handle situations when backend for the given chain is unavailable. - GETCurrent backend time
/health/clockThis endpoint provides the current UNIX time. Your application might use this to verify if the client clock is not out of sync.
Metrics
- GETBlockfrost usage metrics
/metricsHistory of your Blockfrost usage metrics in the past 30 days. - GETBlockfrost endpoint usage metrics
/metrics/endpointsHistory of your Blockfrost usage metrics per endpoint in the past 30 days.
Cardano » Accounts
- GETSpecific account address
/accounts/:stake_addressObtain information about a specific stake account. - GETAccount reward history
/accounts/:stake_address/rewardsObtain information about the reward history of a specific account. - GETAccount history
/accounts/:stake_address/historyObtain information about the history of a specific account. - GETAccount delegation history
/accounts/:stake_address/delegationsObtain information about the delegation of a specific account. - GETAccount registration history
/accounts/:stake_address/registrationsObtain information about the registrations and deregistrations of a specific account. - GETAccount withdrawal history
/accounts/:stake_address/withdrawalsObtain information about the withdrawals of a specific account. - GETAccount MIR history
/accounts/:stake_address/mirsObtain information about the MIRs of a specific account. - GETAccount associated addresses
/accounts/:stake_address/addressesObtain information about the addresses of a specific account. <b>Be careful</b>, as an account could be part of a mangled address and does not necessarily… - GETAssets associated with the account addresses
/accounts/:stake_address/addresses/assetsObtain information about assets associated with addresses of a specific account. <b>Be careful</b>, as an account could be part of a mangled address and does… - GETDetailed information about account associated addresses
/accounts/:stake_address/addresses/totalObtain summed details about all addresses associated with a given account. <b>Be careful</b>, as an account could be part of a mangled address and does not… - GETAccount UTXOs
/accounts/:stake_address/utxosUTXOs associated with the account. - GETAccount transactions
/accounts/:stake_address/transactionsTransactions associated with the stake address.
Cardano » Addresses
- GETSpecific address
/addresses/:addressObtain information about a specific address. - GETExtended information of a specific address
/addresses/:address/extendedObtain extended information about a specific address. - GETAddress details
/addresses/:address/totalObtain details about an address. - GETAddress UTXOs
/addresses/:address/utxosUTXOs of the address. - GETAddress UTXOs of a given asset
/addresses/:address/utxos/:assetUTXOs of the address. - GETAddress txs
/addresses/:address/txsDeprecated. Transactions on the address. - GETAddress transactions
/addresses/:address/transactionsTransactions on the address.
Cardano » Assets
- GETAssets
/assetsList of assets. If an asset is completely burned, it will stay on the list with quantity 0 (order of assets is immutable). - GETSpecific asset
/assets/:assetInformation about a specific asset - GETAsset history
/assets/:asset/historyHistory of a specific asset - GETAsset txs
/assets/:asset/txsDeprecated. List of a specific asset transactions - GETAsset transactions
/assets/:asset/transactionsList of a specific asset transactions - GETAsset addresses
/assets/:asset/addressesList of a addresses containing a specific asset - GETAsset UTXOs
/assets/:asset/utxosList of unspent UTxOs containing the specified native asset. - GETAssets of a specific policy
/assets/policy/:policy_idList of asset minted under a specific policy
Cardano » Blocks
- GETLatest block
/blocks/latestReturn the latest block available to the backends, also known as the tip of the blockchain. - GETLatest block transactions
/blocks/latest/txsReturn the transactions within the latest block. - GETLatest block transactions with CBOR data
/blocks/latest/txs/cborReturn the transactions within the latest block, including CBOR representations. - GETSpecific block
/blocks/:hash_or_numberReturn the content of a requested block. - GETListing of next blocks
/blocks/:hash_or_number/nextReturn the list of blocks following a specific block. - GETListing of previous blocks
/blocks/:hash_or_number/previousReturn the list of blocks preceding a specific block. - GETSpecific block in a slot
/blocks/slot/:slot_numberReturn the content of a requested block for a specific slot. - GETSpecific block in a slot in an epoch
/blocks/epoch/:epoch_number/slot/:slot_numberReturn the content of a requested block for a specific slot in an epoch. - GETBlock transactions
/blocks/:hash_or_number/txsReturn the transactions within the block. - GETBlock transactions with CBOR data
/blocks/:hash_or_number/txs/cborReturn the transactions within the block, including CBOR representations. - GETAddresses affected in a specific block
/blocks/:hash_or_number/addressesReturn list of addresses affected in the specified block with additional information, sorted by the bech32 address, ascending.
Cardano » Epochs
- GETLatest epoch
/epochs/latestReturn the information about the latest, therefore current, epoch. - GETLatest epoch protocol parameters
/epochs/latest/parametersReturn the protocol parameters for the latest epoch. - GETSpecific epoch
/epochs/:numberReturn the content of the requested epoch. - GETListing of next epochs
/epochs/:number/nextReturn the list of epochs following a specific epoch. - GETListing of previous epochs
/epochs/:number/previousReturn the list of epochs preceding a specific epoch. - GETStake distribution
/epochs/:number/stakesReturn the active stake distribution for the specified epoch. - GETStake distribution by pool
/epochs/:number/stakes/:pool_idReturn the active stake distribution for the epoch specified by stake pool. - GETBlock distribution
/epochs/:number/blocksReturn the blocks minted for the epoch specified. - GETBlock distribution by pool
/epochs/:number/blocks/:pool_idReturn the block minted for the epoch specified by stake pool. - GETProtocol parameters
/epochs/:number/parametersReturn the protocol parameters for the epoch specified.
Cardano » Governance
- GETConstitutional committee
/governance/committeeInformation about the currently active constitutional committee When is_dissolved is true, the committee has been removed by an enacted NoConfidence… - GETConstitutional committee votes
/governance/committee/votesHistory of all votes cast by constitutional committee members across all committees (current and past). Not scoped to the currently active committee. - GETConstitutional committee member votes
/governance/committee/:cc_id/votesVotes cast under a given constitutional committee credential. Accepts both the CIP-129 hot bech32 (cc_hot1...) and the cold bech32 (cc_cold1...). When queried… - GETDelegate Representatives (DReps)
/governance/drepsReturn the information about Delegate Representatives (DReps) - GETSpecific DRep
/governance/dreps/:drep_idDRep information. - GETDRep delegators
/governance/dreps/:drep_id/delegatorsList of Drep delegators. - GETDRep metadata
/governance/dreps/:drep_id/metadataDRep metadata information. - GETDRep updates
/governance/dreps/:drep_id/updatesList of certificate updates to the DRep. - GETDRep votes
/governance/dreps/:drep_id/votesHistory of Drep votes. - GETProposals
/governance/proposalsReturn the information about Proposals - GETSpecific proposal
/governance/proposals/:tx_hash/:cert_indexProposal information. - GETSpecific parameters proposal
/governance/proposals/:tx_hash/:cert_index/parametersParameters proposal details. - GETSpecific withdrawals proposal
/governance/proposals/:tx_hash/:cert_index/withdrawalsWithdrawal proposal details. - GETProposal votes
/governance/proposals/:tx_hash/:cert_index/votesHistory of Proposal votes. - GETSpecific proposal metadata
/governance/proposals/:tx_hash/:cert_index/metadataProposal metadata information. If this endpoint returns 404 or empty metadata for a known proposal, the off-chain metadata could not be fetched (e.g.… - GETGovActionID proposal
/governance/proposals/:gov_action_idProposal information. - GETGovActionID Proposal parameters
/governance/proposals/:gov_action_id/parametersParameters proposal details. - GETGovActionID Proposal withdrawals
/governance/proposals/:gov_action_id/withdrawalsWithdrawal proposal details. - GETGovActionID Proposal votes
/governance/proposals/:gov_action_id/votesHistory of Proposal votes. - GETGovActionID proposal metadata
/governance/proposals/:gov_action_id/metadataProposal metadata information.
Cardano » Ledger
- GETBlockchain genesis
/genesisReturn the information about blockchain genesis.
Cardano » Mempool
- GETMempool
/mempoolReturn transactions that are currently stored in Blockfrost mempool, waiting to be included in a newly minted block. Shows only transactions submitted via… - GETSpecific transaction in the mempool
/mempool/:hashReturn content of the requested transaction. <p> <span class="hosted">Hosted</span> Endpoint only available for hosted variant. </p> - GETMempool by address
/mempool/addresses/:addressList of mempool transactions where at least one of the transaction inputs or outputs belongs to the address. Shows only transactions submitted via…
Cardano » Metadata
- GETTransaction metadata labels
/metadata/txs/labelsList of all used transaction metadata labels. - GETTransaction metadata content in JSON
/metadata/txs/labels/:labelTransaction metadata per label. - GETTransaction metadata content in CBOR
/metadata/txs/labels/:label/cborTransaction metadata per label.
Cardano » Network
- GETNetwork information
/networkReturn detailed network information. - GETQuery summary of blockchain eras
/network/erasReturns start and end of each era along with parameters that can vary between hard forks.
Cardano » Pools
- GETList of stake pools
/poolsList of registered stake pools. - GETList of stake pools with additional information
/pools/extendedList of registered stake pools with additional information. - GETList of retired stake pools
/pools/retiredList of already retired pools. - GETList of retiring stake pools
/pools/retiringList of stake pools retiring in the upcoming epochs - GETSpecific stake pool
/pools/:pool_idPool information. - GETStake pool history
/pools/:pool_id/historyHistory of stake pool parameters over epochs. - GETStake pool metadata
/pools/:pool_id/metadataStake pool registration metadata. - GETStake pool relays
/pools/:pool_id/relaysRelays of a stake pool. - GETStake pool delegators
/pools/:pool_id/delegatorsList of current stake pools delegators. - GETStake pool blocks
/pools/:pool_id/blocksList of stake pools blocks. - GETStake pool updates
/pools/:pool_id/updatesList of certificate updates to the stake pool. - GETStake pool votes
/pools/:pool_id/votesHistory of stake pools votes.
Cardano » Scripts
- GETScripts
/scriptsList of scripts. - GETSpecific script
/scripts/:script_hashInformation about a specific script - GETScript JSON
/scripts/:script_hash/jsonJSON representation of a timelock script - GETScript CBOR
/scripts/:script_hash/cborCBOR representation of a plutus script - GETRedeemers of a specific script
/scripts/:script_hash/redeemersList of redeemers of a specific script - GETUTXOs holding the script as a reference script
/scripts/:script_hash/utxosList of UTXOs that hold the given script as a reference script (CIP-33). These outputs can be used as reference inputs (CIP-31) in a transaction to execute… - GETDatum value
/scripts/datum/:datum_hashQuery JSON value of a datum by its hash - GETDatum CBOR value
/scripts/datum/:datum_hash/cborQuery CBOR serialised datum by its hash
Cardano » Transactions
- GETSpecific transaction
/txs/:hashReturn content of the requested transaction. - GETTransaction UTXOs
/txs/:hash/utxosReturn the inputs and UTXOs of the specific transaction. - GETTransaction stake addresses certificates
/txs/:hash/stakesObtain information about (de)registration of stake addresses within a transaction. - GETTransaction delegation certificates
/txs/:hash/delegationsObtain information about delegation certificates of a specific transaction. - GETTransaction withdrawal
/txs/:hash/withdrawalsObtain information about withdrawals of a specific transaction. - GETTransaction MIRs
/txs/:hash/mirsObtain information about Move Instantaneous Rewards (MIRs) of a specific transaction. - GETTransaction stake pool registration and update certificates
/txs/:hash/pool_updatesObtain information about stake pool registration and update certificates of a specific transaction. - GETTransaction stake pool retirement certificates
/txs/:hash/pool_retiresObtain information about stake pool retirements within a specific transaction. - GETTransaction metadata
/txs/:hash/metadataObtain the transaction metadata. - GETTransaction metadata in CBOR
/txs/:hash/metadata/cborObtain the transaction metadata in CBOR. - GETTransaction redeemers
/txs/:hash/redeemersObtain the transaction redeemers. - GETTransaction required signers
/txs/:hash/required_signersObtain the extra transaction witnesses. - GETTransaction CBOR
/txs/:hash/cborObtain the CBOR serialized transaction - POSTSubmit a transaction
/tx/submitSubmit an already serialized transaction to the network. <p> <span class="hosted">Hosted</span> Endpoint only available for hosted variant. </p>
Cardano » Utilities
- GETDerive an address
/utils/addresses/xpub/:xpub/:role/:indexDerive Shelley address from an xpub - POSTSubmit a transaction for execution units evaluation
/utils/txs/evaluateSubmit an already serialized transaction to evaluate how much execution units it requires. <p> <span class="hosted">Hosted</span> Endpoint only available for… - POSTSubmit a transaction for execution units evaluation (additional UTXO set)
/utils/txs/evaluate/utxosSubmit a JSON payload with transaction CBOR and additional UTXO set to evaluate how much execution units it requires. <p> <span class="hosted">Hosted</span>…
IPFS » Add
- POSTAdd a file to IPFS
https://ipfs.blockfrost.io/api/v0/ipfs/addYou need to /ipfs/pin/add an object to avoid it being garbage collected. This usage is being counted in your user account quota. <p> <span…
IPFS » Gateway
- GETRelay to an IPFS gateway
https://ipfs.blockfrost.io/api/v0/ipfs/gateway/:IPFS_pathRetrieve an object from the IPFS gateway (useful if you do not want to rely on a public gateway, such as ipfs.blockfrost.dev). <p> <span…
IPFS » Pins
- POSTPin an object
https://ipfs.blockfrost.io/api/v0/ipfs/pin/add/:IPFS_pathPinning is necessary to avoid regular garbage collection (deletion) of IPFS objects. Non-pinned objects are regularly being removed without prior notice.… - GETList pinned objects
https://ipfs.blockfrost.io/api/v0/ipfs/pin/listList objects pinned to local storage <p> <span class="hosted">Hosted</span> Endpoint only available for hosted variant. </p> - GETGet details about pinned object
https://ipfs.blockfrost.io/api/v0/ipfs/pin/list/:IPFS_pathGet information about locally pinned IPFS object <p> <span class="hosted">Hosted</span> Endpoint only available for hosted variant. </p> - POSTRemove a IPFS pin
https://ipfs.blockfrost.io/api/v0/ipfs/pin/remove/:IPFS_pathRemove pinned objects from local storage <p> <span class="hosted">Hosted</span> Endpoint only available for hosted variant. </p> Note: If the object was…
API details
- Base URL
https://cardano-mainnet.blockfrost.io/api/v0https://cardano-preprod.blockfrost.io/api/v0https://cardano-preview.blockfrost.io/api/v0https://localhost:3000- Authentication
- An API key in the project_id header
- Operations
- 125 operations on 125 pathsGET 119POST 6
2 marked deprecated - Main resources
- Cardano » Governance 20Cardano » Transactions 14Cardano » Accounts 12Cardano » Pools 12Cardano » Blocks 11Cardano » Epochs 10Cardano » Assets 8Cardano » Scripts 8Cardano » Addresses 7IPFS » Pins 4
- Response formats
application/jsonapplication/octet-stream- Description format
- OpenAPI 3.0.3, API version
0.1.93 - Links
- OpenAPI document · Terms of service · Support
- Listed from
- Blockfrost's published OpenAPI description (blockfrost/openapi) (MIT)
How to test the Blockfrost API in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Blockfrost API collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the project_id header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Root endpoint” (GET /), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Blockfrost API?
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… It is listed under Finance & banking and has 125 endpoints.
Who publishes the Blockfrost API?
It is listed from Blockfrost's public API description (an OpenAPI document), not published by Blockfrost on Swastik Codes. Anyone who controls blockfrost.io can claim the profile by adding a DNS TXT record.
What is the base URL of the Blockfrost API?
Its description lists 4 base URLs: https://cardano-mainnet.blockfrost.io/api/v0, https://cardano-preprod.blockfrost.io/api/v0, https://cardano-preview.blockfrost.io/api/v0, https://localhost:3000. The first is the usual one; the others are typically sandbox or regional servers.
How do I authenticate with the Blockfrost API?
With an API key in the project_id header.
How many endpoints does the Blockfrost API have?
125 operations on 125 paths (119 GET, 6 POST). The largest groups are Cardano » Governance, Cardano » Transactions, Cardano » Accounts, Cardano » Pools.
Is forking the Blockfrost API free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.