BlockFrost Service API
INTRODUCTION
This library is for accessing the Cardano blockchain via BlockFrost service nodes. BlockFrost allows access to the blockchain for light clients that do not wish to run a dedicated, resource intensive, Cardano node locally.
This code is available as a package on pub.dev: https://pub.dev/packages/blockfrost
Warning: This library is a minimal unofficial Blockfrost implementation created to support Flutter SDK.
Tests
To run the tests, you must download a apiKey from https://blockfrost.io, then place the key in the parent directory of your project in a file with the name:
blockfrost_project_id.txt
i.e.
echo "your-project-id" > ../blockfrost_project_id.txt
MyApiKeyAuthInterceptor
will read the key on startup and insert it into the REST header requests.
final instance = Blockfrost(
basePathOverride: testnet,
interceptors: [MyApiKeyAuthInterceptor()],
);
Production
To use this code in production, simply replace MyApiKeyAuthInterceptor
with BlockfrostApiKeyAuthInterceptor
, passing your project_id
key into the constructor:
BlockfrostApiKeyAuthInterceptor(projectId:'your-project-id')
Here is an implemenation - blockfrost_api_key_auth.dart
:
import 'package:dio/dio.dart';
import 'package:blockfrost/src/auth/auth.dart';
class BlockfrostApiKeyAuthInterceptor extends AuthInterceptor {
final String projectId;
BlockfrostApiKeyAuthInterceptor({required this.projectId});
@override
void onRequest(RequestOptions options, RequestInterceptorHandler handler) {
options.headers['project_id'] = projectId;
super.onRequest(options, handler);
}
}
Usage
Refer to the generated documentation below and tests for example usage. Be aware, this is very low-level, blockchain-specific code. If you wish to send transactions or work with smart contracts, you'll need a higher level API. The cardano_wallet_sdk (by the same author) is a good resource for code and tests that demonstrate how to use this API to build higher level services.
Status
Five Binaries was granted $10,000 in Fund 6 to implement an official BlockFrost Dart binding:
https://cardano.ideascale.com/c/idea/369239
The source code can be found here:
https://github.com/blockfrost/blockfrost-dart/
When the official implementation matures, this project will be discontinued.
Support
This is not an official blockfrost package so please do not contract BlockFrost with issues specific to this code.
GENERATED DOCUMENTATION - blockfrost (EXPERIMENTAL)
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
.
Network | Endpoint |
Cardano mainnet | https://cardano-mainnet.blockfrost.io/api/v0 |
Cardano testnet | https://cardano-testnet.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.
- You might use the
?order=desc
query parameter to reverse this order.
- You might use the
- 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 code402
or429
. - 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.
Authentication
This Dart package is automatically generated by the OpenAPI Generator project:
- API version: 0.1.23
- Build package: org.openapitools.codegen.languages.DartDioNextClientCodegen For more information, please visit https://blockfrost.io
Requirements
- Dart 2.12.0 or later OR Flutter 1.26.0 or later
- Dio 4.0.0+
Installation & Usage
pub.dev
To use the package from pub.dev, please include the following in pubspec.yaml
dependencies:
blockfrost: 1.0.0
Github
If this Dart package is published to Github, please include the following in pubspec.yaml
dependencies:
blockfrost:
git:
url: https://github.com/GIT_USER_ID/GIT_REPO_ID.git
#ref: main
Local development
To use the package from your local drive, please include the following in pubspec.yaml
dependencies:
blockfrost:
path: /path/to/blockfrost
Getting Started
Please follow the installation procedure and then run the following:
import 'package:blockfrost/blockfrost.dart';
final api = CardanoAccountsApi();
final stakeAddress = stake1u9ylzsgxaa6xctf4juup682ar3juj85n8tx3hthnljg47zctvm3rc; // String | Bech32 stake address.
final count = 56; // int | The number of results displayed on one page.
final page = 56; // int | The page number for listing the results.
final order = order_example; // String | 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.
try {
final response = await api.accountsStakeAddressAddressesAssetsGet(stakeAddress, count, page, order);
print(response);
} catch on DioError (e) {
print("Exception when calling CardanoAccountsApi->accountsStakeAddressAddressesAssetsGet: $e\n");
}
Documentation for API Endpoints
All URIs are relative to https://cardano-mainnet.blockfrost.io/api/v0
Class | Method | HTTP request | Description |
---|---|---|---|
CardanoAccountsApi | accountsStakeAddressAddressesAssetsGet | get /accounts/{stake_address}/addresses/assets | Assets associated with the account addresses |
CardanoAccountsApi | accountsStakeAddressAddressesGet | get /accounts/{stake_address}/addresses | Account associated addresses |
CardanoAccountsApi | accountsStakeAddressDelegationsGet | get /accounts/{stake_address}/delegations | Account delegation history |
CardanoAccountsApi | accountsStakeAddressGet | get /accounts/{stake_address} | Specific account address |
CardanoAccountsApi | accountsStakeAddressHistoryGet | get /accounts/{stake_address}/history | Account history |
CardanoAccountsApi | accountsStakeAddressMirsGet | get /accounts/{stake_address}/mirs | Account MIR history |
CardanoAccountsApi | accountsStakeAddressRegistrationsGet | get /accounts/{stake_address}/registrations | Account registration history |
CardanoAccountsApi | accountsStakeAddressRewardsGet | get /accounts/{stake_address}/rewards | Account reward history |
CardanoAccountsApi | accountsStakeAddressWithdrawalsGet | get /accounts/{stake_address}/withdrawals | Account withdrawal history |
CardanoAddressesApi | addressesAddressGet | get /addresses/{address} | Specific address |
CardanoAddressesApi | addressesAddressTotalGet | get /addresses/{address}/total | Address details |
CardanoAddressesApi | addressesAddressTransactionsGet | get /addresses/{address}/transactions | Address transactions |
CardanoAddressesApi | addressesAddressTxsGet | get /addresses/{address}/txs | Address transactions |
CardanoAddressesApi | addressesAddressUtxosGet | get /addresses/{address}/utxos | Address UTXOs |
CardanoAssetsApi | assetsAssetAddressesGet | get /assets/{asset}/addresses | Asset addresses |
CardanoAssetsApi | assetsAssetGet | get /assets/{asset} | Specific asset |
CardanoAssetsApi | assetsAssetHistoryGet | get /assets/{asset}/history | Asset history |
CardanoAssetsApi | assetsAssetTransactionsGet | get /assets/{asset}/transactions | Asset transactions |
CardanoAssetsApi | assetsAssetTxsGet | get /assets/{asset}/txs | Asset transactions |
CardanoAssetsApi | assetsGet | get /assets | Assets |
CardanoAssetsApi | assetsPolicyPolicyIdGet | get /assets/policy/{policy_id} | Assets of a specific policy |
CardanoBlocksApi | blocksEpochEpochNumberSlotSlotNumberGet | get /blocks/epoch/{epoch_number}/slot/{slot_number} | Specific block in a slot in an epoch |
CardanoBlocksApi | blocksHashOrNumberGet | get /blocks/{hash_or_number} | Specific block |
CardanoBlocksApi | blocksHashOrNumberNextGet | get /blocks/{hash_or_number}/next | Listing of next blocks |
CardanoBlocksApi | blocksHashOrNumberPreviousGet | get /blocks/{hash_or_number}/previous | Listing of previous blocks |
CardanoBlocksApi | blocksHashOrNumberTxsGet | get /blocks/{hash_or_number}/txs | Block transactions |
CardanoBlocksApi | blocksLatestGet | get /blocks/latest | Latest block |
CardanoBlocksApi | blocksLatestTxsGet | get /blocks/latest/txs | Latest block transactions |
CardanoBlocksApi | blocksSlotSlotNumberGet | get /blocks/slot/{slot_number} | Specific block in a slot |
CardanoEpochsApi | epochsLatestGet | get /epochs/latest | Latest epoch |
CardanoEpochsApi | epochsLatestParametersGet | get /epochs/latest/parameters | Latest epoch protocol parameters |
CardanoEpochsApi | epochsNumberBlocksGet | get /epochs/{number}/blocks | Block distribution |
CardanoEpochsApi | epochsNumberBlocksPoolIdGet | get /epochs/{number}/blocks/{pool_id} | Block distribution |
CardanoEpochsApi | epochsNumberGet | get /epochs/{number} | Specific epoch |
CardanoEpochsApi | epochsNumberNextGet | get /epochs/{number}/next | Listing of next epochs |
CardanoEpochsApi | epochsNumberParametersGet | get /epochs/{number}/parameters | Protocol parameters |
CardanoEpochsApi | epochsNumberPreviousGet | get /epochs/{number}/previous | Listing of previous epochs |
CardanoEpochsApi | epochsNumberStakesGet | get /epochs/{number}/stakes | Stake distribution |
CardanoEpochsApi | epochsNumberStakesPoolIdGet | get /epochs/{number}/stakes/{pool_id} | Stake distribution by pool |
CardanoLedgerApi | genesisGet | get /genesis | Blockchain genesis |
CardanoMetadataApi | metadataTxsLabelsGet | get /metadata/txs/labels | Transaction metadata labels |
CardanoMetadataApi | metadataTxsLabelsLabelCborGet | get /metadata/txs/labels/{label}/cbor | Transaction metadata content in CBOR |
CardanoMetadataApi | metadataTxsLabelsLabelGet | get /metadata/txs/labels/{label} | Transaction metadata content in JSON |
CardanoPoolsApi | poolsGet | get /pools | List of stake pools |
CardanoPoolsApi | poolsPoolIdBlocksGet | get /pools/{pool_id}/blocks | Stake pool blocks |
CardanoPoolsApi | poolsPoolIdDelegatorsGet | get /pools/{pool_id}/delegators | Stake pool delegators |
CardanoPoolsApi | poolsPoolIdGet | get /pools/{pool_id} | Specific stake pool |
CardanoPoolsApi | poolsPoolIdHistoryGet | get /pools/{pool_id}/history | Stake pool history |
CardanoPoolsApi | poolsPoolIdMetadataGet | get /pools/{pool_id}/metadata | Stake pool metadata |
CardanoPoolsApi | poolsPoolIdRelaysGet | get /pools/{pool_id}/relays | Stake pool relays |
CardanoPoolsApi | poolsPoolIdUpdatesGet | get /pools/{pool_id}/updates | Stake pool updates |
CardanoPoolsApi | poolsRetiredGet | get /pools/retired | List of retired stake pools |
CardanoPoolsApi | poolsRetiringGet | get /pools/retiring | List of retiring stake pools |
CardanoTransactionsApi | txSubmitPost | post /tx/submit | Submit a transaction |
CardanoTransactionsApi | txsHashDelegationsGet | get /txs/{hash}/delegations | Transaction delegation certificates |
CardanoTransactionsApi | txsHashGet | get /txs/{hash} | Specific transaction |
CardanoTransactionsApi | txsHashMetadataCborGet | get /txs/{hash}/metadata/cbor | Transaction metadata in CBOR |
CardanoTransactionsApi | txsHashMetadataGet | get /txs/{hash}/metadata | Transaction metadata |
CardanoTransactionsApi | txsHashMirsGet | get /txs/{hash}/mirs | Transaction MIRs |
CardanoTransactionsApi | txsHashPoolRetiresGet | get /txs/{hash}/pool_retires | Transaction stake pool retirement certificates |
CardanoTransactionsApi | txsHashPoolUpdatesGet | get /txs/{hash}/pool_updates | Transaction stake pool registration and update certificates |
CardanoTransactionsApi | txsHashStakesGet | get /txs/{hash}/stakes | Transaction stake addresses certificates |
CardanoTransactionsApi | txsHashUtxosGet | get /txs/{hash}/utxos | Transaction UTXOs |
CardanoTransactionsApi | txsHashWithdrawalsGet | get /txs/{hash}/withdrawals | Transaction withdrawal |
HealthApi | healthClockGet | get /health/clock | Current backend time |
HealthApi | healthGet | get /health | Backend health status |
HealthApi | rootGet | get / | Root endpoint |
IPFSAddApi | ipfsAddPost | post /ipfs/add | Add a file or directory to IPFS |
IPFSGatewayApi | ipfsGatewayIPFSPathGet | get /ipfs/gateway/{IPFS_path} | Relay to an IPFS gateway |
IPFSPinsApi | ipfsPinAddIPFSPathPost | post /ipfs/pin/add/{IPFS_path} | Pin an object |
IPFSPinsApi | ipfsPinListGet | get /ipfs/pin/list/ | |
IPFSPinsApi | ipfsPinListIPFSPathGet | get /ipfs/pin/list/{IPFS_path} | |
IPFSPinsApi | ipfsPinRemoveIPFSPathPost | post /ipfs/pin/remove/{IPFS_path} | |
MetricsApi | metricsEndpointsGet | get /metrics/endpoints | Blockfrost endpoint usage metrics |
MetricsApi | metricsGet | get /metrics/ | Blockfrost usage metrics |
NutLinkApi | nutlinkAddressGet | get /nutlink/{address} | |
NutLinkApi | nutlinkAddressTickersGet | get /nutlink/{address}/tickers | |
NutLinkApi | nutlinkAddressTickersTickerGet | get /nutlink/{address}/tickers/{ticker} | |
NutLinkApi | nutlinkTickersTickerGet | get /nutlink/tickers/{ticker} |
Documentation For Models
- AccountContent
- AddressContent
- AddressContentTotal
- Asset
- AssetMetadata
- BlockContent
- EpochContent
- EpochParamContent
- GenesisContent
- InlineResponse200
- InlineResponse2001
- InlineResponse2002
- InlineResponse2003
- InlineResponse2004
- InlineResponse2005
- InlineResponse2006
- InlineResponse2007
- InlineResponse400
- InlineResponse403
- InlineResponse404
- InlineResponse418
- InlineResponse429
- InlineResponse500
- NutlinkAddress
- Pool
- PoolMetadata
- TxContent
- TxContentOutputAmount
- TxContentUtxo
- TxContentUtxoInputs
- TxContentUtxoOutputs
Documentation For Authorization
ApiKeyAuth
- Type: API key
- API key parameter name: project_id
- Location: HTTP header