blockfrost 1.0.0-dev.3
blockfrost: ^1.0.0-dev.3 copied to clipboard

Dart OpenAPI API blockfrost client based on Dio 4.x

blockfrost (EXPERIMENTAL) #

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

Author Notes #

This document is a code generation artifact, refer to NOTES for usage tips, issues and implementation notes.

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.

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

ClassMethodHTTP requestDescription
CardanoAccountsApiaccountsStakeAddressAddressesAssetsGetget /accounts/{stake_address}/addresses/assetsAssets associated with the account addresses
CardanoAccountsApiaccountsStakeAddressAddressesGetget /accounts/{stake_address}/addressesAccount associated addresses
CardanoAccountsApiaccountsStakeAddressDelegationsGetget /accounts/{stake_address}/delegationsAccount delegation history
CardanoAccountsApiaccountsStakeAddressGetget /accounts/{stake_address}Specific account address
CardanoAccountsApiaccountsStakeAddressHistoryGetget /accounts/{stake_address}/historyAccount history
CardanoAccountsApiaccountsStakeAddressMirsGetget /accounts/{stake_address}/mirsAccount MIR history
CardanoAccountsApiaccountsStakeAddressRegistrationsGetget /accounts/{stake_address}/registrationsAccount registration history
CardanoAccountsApiaccountsStakeAddressRewardsGetget /accounts/{stake_address}/rewardsAccount reward history
CardanoAccountsApiaccountsStakeAddressWithdrawalsGetget /accounts/{stake_address}/withdrawalsAccount withdrawal history
CardanoAddressesApiaddressesAddressGetget /addresses/{address}Specific address
CardanoAddressesApiaddressesAddressTotalGetget /addresses/{address}/totalAddress details
CardanoAddressesApiaddressesAddressTransactionsGetget /addresses/{address}/transactionsAddress transactions
CardanoAddressesApiaddressesAddressTxsGetget /addresses/{address}/txsAddress transactions
CardanoAddressesApiaddressesAddressUtxosGetget /addresses/{address}/utxosAddress UTXOs
CardanoAssetsApiassetsAssetAddressesGetget /assets/{asset}/addressesAsset addresses
CardanoAssetsApiassetsAssetGetget /assets/{asset}Specific asset
CardanoAssetsApiassetsAssetHistoryGetget /assets/{asset}/historyAsset history
CardanoAssetsApiassetsAssetTransactionsGetget /assets/{asset}/transactionsAsset transactions
CardanoAssetsApiassetsAssetTxsGetget /assets/{asset}/txsAsset transactions
CardanoAssetsApiassetsGetget /assetsAssets
CardanoAssetsApiassetsPolicyPolicyIdGetget /assets/policy/{policy_id}Assets of a specific policy
CardanoBlocksApiblocksEpochEpochNumberSlotSlotNumberGetget /blocks/epoch/{epoch_number}/slot/{slot_number}Specific block in a slot in an epoch
CardanoBlocksApiblocksHashOrNumberGetget /blocks/{hash_or_number}Specific block
CardanoBlocksApiblocksHashOrNumberNextGetget /blocks/{hash_or_number}/nextListing of next blocks
CardanoBlocksApiblocksHashOrNumberPreviousGetget /blocks/{hash_or_number}/previousListing of previous blocks
CardanoBlocksApiblocksHashOrNumberTxsGetget /blocks/{hash_or_number}/txsBlock transactions
CardanoBlocksApiblocksLatestGetget /blocks/latestLatest block
CardanoBlocksApiblocksLatestTxsGetget /blocks/latest/txsLatest block transactions
CardanoBlocksApiblocksSlotSlotNumberGetget /blocks/slot/{slot_number}Specific block in a slot
CardanoEpochsApiepochsLatestGetget /epochs/latestLatest epoch
CardanoEpochsApiepochsLatestParametersGetget /epochs/latest/parametersLatest epoch protocol parameters
CardanoEpochsApiepochsNumberBlocksGetget /epochs/{number}/blocksBlock distribution
CardanoEpochsApiepochsNumberBlocksPoolIdGetget /epochs/{number}/blocks/{pool_id}Block distribution
CardanoEpochsApiepochsNumberGetget /epochs/{number}Specific epoch
CardanoEpochsApiepochsNumberNextGetget /epochs/{number}/nextListing of next epochs
CardanoEpochsApiepochsNumberParametersGetget /epochs/{number}/parametersProtocol parameters
CardanoEpochsApiepochsNumberPreviousGetget /epochs/{number}/previousListing of previous epochs
CardanoEpochsApiepochsNumberStakesGetget /epochs/{number}/stakesStake distribution
CardanoEpochsApiepochsNumberStakesPoolIdGetget /epochs/{number}/stakes/{pool_id}Stake distribution by pool
CardanoLedgerApigenesisGetget /genesisBlockchain genesis
CardanoMetadataApimetadataTxsLabelsGetget /metadata/txs/labelsTransaction metadata labels
CardanoMetadataApimetadataTxsLabelsLabelCborGetget /metadata/txs/labels/{label}/cborTransaction metadata content in CBOR
CardanoMetadataApimetadataTxsLabelsLabelGetget /metadata/txs/labels/{label}Transaction metadata content in JSON
CardanoPoolsApipoolsGetget /poolsList of stake pools
CardanoPoolsApipoolsPoolIdBlocksGetget /pools/{pool_id}/blocksStake pool blocks
CardanoPoolsApipoolsPoolIdDelegatorsGetget /pools/{pool_id}/delegatorsStake pool delegators
CardanoPoolsApipoolsPoolIdGetget /pools/{pool_id}Specific stake pool
CardanoPoolsApipoolsPoolIdHistoryGetget /pools/{pool_id}/historyStake pool history
CardanoPoolsApipoolsPoolIdMetadataGetget /pools/{pool_id}/metadataStake pool metadata
CardanoPoolsApipoolsPoolIdRelaysGetget /pools/{pool_id}/relaysStake pool relays
CardanoPoolsApipoolsPoolIdUpdatesGetget /pools/{pool_id}/updatesStake pool updates
CardanoPoolsApipoolsRetiredGetget /pools/retiredList of retired stake pools
CardanoPoolsApipoolsRetiringGetget /pools/retiringList of retiring stake pools
CardanoTransactionsApitxSubmitPostpost /tx/submitSubmit a transaction
CardanoTransactionsApitxsHashDelegationsGetget /txs/{hash}/delegationsTransaction delegation certificates
CardanoTransactionsApitxsHashGetget /txs/{hash}Specific transaction
CardanoTransactionsApitxsHashMetadataCborGetget /txs/{hash}/metadata/cborTransaction metadata in CBOR
CardanoTransactionsApitxsHashMetadataGetget /txs/{hash}/metadataTransaction metadata
CardanoTransactionsApitxsHashMirsGetget /txs/{hash}/mirsTransaction MIRs
CardanoTransactionsApitxsHashPoolRetiresGetget /txs/{hash}/pool_retiresTransaction stake pool retirement certificates
CardanoTransactionsApitxsHashPoolUpdatesGetget /txs/{hash}/pool_updatesTransaction stake pool registration and update certificates
CardanoTransactionsApitxsHashStakesGetget /txs/{hash}/stakesTransaction stake addresses certificates
CardanoTransactionsApitxsHashUtxosGetget /txs/{hash}/utxosTransaction UTXOs
CardanoTransactionsApitxsHashWithdrawalsGetget /txs/{hash}/withdrawalsTransaction withdrawal
HealthApihealthClockGetget /health/clockCurrent backend time
HealthApihealthGetget /healthBackend health status
HealthApirootGetget /Root endpoint
IPFSAddApiipfsAddPostpost /ipfs/addAdd a file or directory to IPFS
IPFSGatewayApiipfsGatewayIPFSPathGetget /ipfs/gateway/{IPFS_path}Relay to an IPFS gateway
IPFSPinsApiipfsPinAddIPFSPathPostpost /ipfs/pin/add/{IPFS_path}Pin an object
IPFSPinsApiipfsPinListGetget /ipfs/pin/list/
IPFSPinsApiipfsPinListIPFSPathGetget /ipfs/pin/list/{IPFS_path}
IPFSPinsApiipfsPinRemoveIPFSPathPostpost /ipfs/pin/remove/{IPFS_path}
MetricsApimetricsEndpointsGetget /metrics/endpointsBlockfrost endpoint usage metrics
MetricsApimetricsGetget /metrics/Blockfrost usage metrics
NutLinkApinutlinkAddressGetget /nutlink/{address}
NutLinkApinutlinkAddressTickersGetget /nutlink/{address}/tickers
NutLinkApinutlinkAddressTickersTickerGetget /nutlink/{address}/tickers/{ticker}
NutLinkApinutlinkTickersTickerGetget /nutlink/tickers/{ticker}

Documentation For Models #

Documentation For Authorization #

ApiKeyAuth #

  • Type: API key
  • API key parameter name: project_id
  • Location: HTTP header

Author #

contact@blockfrost.io

3
likes
100
pub points
39%
popularity

Dart OpenAPI API blockfrost client based on Dio 4.x

Repository (GitHub)
View/report issues

Documentation

API reference

License

Apache 2.0 (LICENSE)

Dependencies

built_collection, built_value, dio

More

Packages that depend on blockfrost