BlockfrostSwiftSDK

master

Swift SDK for Blockfrost.io API
blockfrost/blockfrost-swift

Swift5 API client for Blockfrost

CI badge

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

Note: work is in progress, we need to cover endpoints with tests.

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 (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.

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
Haskellblockfrost-haskell

Overview

This API client was generated by the OpenAPI Generator project. By using the openapi-spec from a remote server, you can easily generate an API client.

  • API version: 0.1.27
  • Package version:
  • Build package: org.openapitools.codegen.languages.Swift5ClientCodegen For more information, please visit https://blockfrost.io

Usage

API uses a simple completion callbacks, returning Swift.Result<R, Error>, where R is defined by the particular API call.

// import the SDK on the beginning of the file
import BlockfrostSwiftSDK

// define project-wide settings
BlockfrostStaticConfig.basePath = "https://cardano-mainnet.blockfrost.io/api/v0"  // or leave default
BlockfrostStaticConfig.projectId = "your-project-id"
let api = CardanoAddressesAPI()

_ = api.getAddressDetails(address: "addr1q8zu4smzyf2r2mfqjd6tc6vxf2p8rccdfk82ye3eut2udkw9etpkygj5x4kjpym5h35cvj5zw83s6nvw5fnrnck4cmvshkfm4y") { resp in
    switch (resp) {
    case let .failure(err):
        // TODO: handle error here, `err` contains the error 
        break
    case let .success(r):
        // `r` contains result of the call, here, it is of type `AddressContentTotal`
        break
    }
}

You can also define API-specific configuration

let config = BlockfrostConfig()
config.basePath = "https://cardano-testnet.blockfrost.io/api/v0"
config.projectId = "project-id-for-testnet"
config.retryPolicy = BlockfrostRetryPolicy(retryLimit: 10)    // specify custom retry policy

let api = CardanoAddressesAPI(config: config)

Installation

Carthage

Run carthage update

CocoaPods

Run pod install

Documentation for API Endpoints

All URIs are relative to https://cardano-mainnet.blockfrost.io/api/v0

Class Method HTTP request Description
CardanoAccountsAPI getAccountAddresses GET /accounts/{stake_address}/addresses Account associated addresses
CardanoAccountsAPI getAccountAssets GET /accounts/{stake_address}/addresses/assets Assets associated with the account addresses
CardanoAccountsAPI getAccountByStakeAddress GET /accounts/{stake_address} Specific account address
CardanoAccountsAPI getAccountDelegationHistory GET /accounts/{stake_address}/delegations Account delegation history
CardanoAccountsAPI getAccountHistory GET /accounts/{stake_address}/history Account history
CardanoAccountsAPI getAccountMirHistory GET /accounts/{stake_address}/mirs Account MIR history
CardanoAccountsAPI getAccountRegistrationHistory GET /accounts/{stake_address}/registrations Account registration history
CardanoAccountsAPI getAccountRewardHistory GET /accounts/{stake_address}/rewards Account reward history
CardanoAccountsAPI getAccountWithdrawalHistory GET /accounts/{stake_address}/withdrawals Account withdrawal history
CardanoAddressesAPI getAddress GET /addresses/{address} Specific address
CardanoAddressesAPI getAddressDetails GET /addresses/{address}/total Address details
CardanoAddressesAPI getAddressTransactions GET /addresses/{address}/transactions Address transactions
CardanoAddressesAPI getAddressTxs GET /addresses/{address}/txs Address transactions
CardanoAddressesAPI getAddressUtxos GET /addresses/{address}/utxos Address UTXOs
CardanoAssetsAPI getAsset GET /assets/{asset} Specific asset
CardanoAssetsAPI getAssetAddresses GET /assets/{asset}/addresses Asset addresses
CardanoAssetsAPI getAssetHistory GET /assets/{asset}/history Asset history
CardanoAssetsAPI getAssetTransactions GET /assets/{asset}/transactions Asset transactions
CardanoAssetsAPI getAssetTxs GET /assets/{asset}/txs Asset transactions
CardanoAssetsAPI getAssets GET /assets Assets
CardanoAssetsAPI getPolicyAssets GET /assets/policy/{policy_id} Assets of a specific policy
CardanoBlocksAPI getBlock GET /blocks/{hash_or_number} Specific block
CardanoBlocksAPI getBlockInEpochInSlot GET /blocks/epoch/{epoch_number}/slot/{slot_number} Specific block in a slot in an epoch
CardanoBlocksAPI getBlockInSlot GET /blocks/slot/{slot_number} Specific block in a slot
CardanoBlocksAPI getBlockTransactions GET /blocks/{hash_or_number}/txs Block transactions
CardanoBlocksAPI getLatestBlock GET /blocks/latest Latest block
CardanoBlocksAPI getNextBlocks GET /blocks/{hash_or_number}/next Listing of next blocks
CardanoBlocksAPI getPreviousBlocks GET /blocks/{hash_or_number}/previous Listing of previous blocks
CardanoBlocksAPI getTransactionsInLatestBlock GET /blocks/latest/txs Latest block transactions
CardanoEpochsAPI getActiveStakesForEpoch GET /epochs/{number}/stakes Stake distribution
CardanoEpochsAPI getActiveStakesForEpochAndPool GET /epochs/{number}/stakes/{pool_id} Stake distribution by pool
CardanoEpochsAPI getBlocksForEpoch GET /epochs/{number}/blocks Block distribution
CardanoEpochsAPI getBlocksForEpochAndPool GET /epochs/{number}/blocks/{pool_id} Block distribution by pool
CardanoEpochsAPI getEpoch GET /epochs/{number} Specific epoch
CardanoEpochsAPI getEpochParam GET /epochs/{number}/parameters Protocol parameters
CardanoEpochsAPI getLatestEpoch GET /epochs/latest Latest epoch
CardanoEpochsAPI getLatestEpochParam GET /epochs/latest/parameters Latest epoch protocol parameters
CardanoEpochsAPI getNextEpochs GET /epochs/{number}/next Listing of next epochs
CardanoEpochsAPI getPreviousEpochs GET /epochs/{number}/previous Listing of previous epochs
CardanoLedgerAPI getGenesis GET /genesis Blockchain genesis
CardanoMetadataAPI getTransactionMetadataCborForLabel GET /metadata/txs/labels/{label}/cbor Transaction metadata content in CBOR
CardanoMetadataAPI getTransactionMetadataJsonForLabel GET /metadata/txs/labels/{label} Transaction metadata content in JSON
CardanoMetadataAPI getTransactionMetadataLabels GET /metadata/txs/labels Transaction metadata labels
CardanoNetworkAPI getNetwork GET /network Network information
CardanoPoolsAPI getPool GET /pools/{pool_id} Specific stake pool
CardanoPoolsAPI getPoolBlocks GET /pools/{pool_id}/blocks Stake pool blocks
CardanoPoolsAPI getPoolDelegators GET /pools/{pool_id}/delegators Stake pool delegators
CardanoPoolsAPI getPoolHistory GET /pools/{pool_id}/history Stake pool history
CardanoPoolsAPI getPoolMetadata GET /pools/{pool_id}/metadata Stake pool metadata
CardanoPoolsAPI getPoolRelays GET /pools/{pool_id}/relays Stake pool relays
CardanoPoolsAPI getPoolUpdates GET /pools/{pool_id}/updates Stake pool updates
CardanoPoolsAPI getPools GET /pools List of stake pools
CardanoPoolsAPI getRetiredPools GET /pools/retired List of retired stake pools
CardanoPoolsAPI getRetiringPools GET /pools/retiring List of retiring stake pools
CardanoScriptsAPI getScript GET /scripts/{script_hash} Specific script
CardanoScriptsAPI getScriptRedeemers GET /scripts/{script_hash}/redeemers Redeemers of a specific script
CardanoScriptsAPI getScripts GET /scripts Scripts
CardanoTransactionsAPI getTransaction GET /txs/{hash} Specific transaction
CardanoTransactionsAPI getTransactionDelegations GET /txs/{hash}/delegations Transaction delegation certificates
CardanoTransactionsAPI getTransactionMetadata GET /txs/{hash}/metadata Transaction metadata
CardanoTransactionsAPI getTransactionMetadataCbor GET /txs/{hash}/metadata/cbor Transaction metadata in CBOR
CardanoTransactionsAPI getTransactionMirs GET /txs/{hash}/mirs Transaction MIRs
CardanoTransactionsAPI getTransactionPoolRetires GET /txs/{hash}/pool_retires Transaction stake pool retirement certificates
CardanoTransactionsAPI getTransactionPoolUpdates GET /txs/{hash}/pool_updates Transaction stake pool registration and update certificates
CardanoTransactionsAPI getTransactionRedeemers GET /txs/{hash}/redeemers Transaction redeemers
CardanoTransactionsAPI getTransactionStakes GET /txs/{hash}/stakes Transaction stake addresses certificates
CardanoTransactionsAPI getTransactionUtxos GET /txs/{hash}/utxos Transaction UTXOs
CardanoTransactionsAPI getTransactionWithdrawals GET /txs/{hash}/withdrawals Transaction withdrawal
CardanoTransactionsAPI submitTransaction POST /tx/submit Submit a transaction
HealthAPI getApiRoot GET / Root endpoint
HealthAPI getCurrentBackendTime GET /health/clock Current backend time
HealthAPI getHealth GET /health Backend health status
IPFSAddAPI add POST /ipfs/add Add a file to IPFS
IPFSGatewayAPI callGet GET /ipfs/gateway/{IPFS_path} Relay to an IPFS gateway
IPFSPinsAPI getPinList GET /ipfs/pin/list/ List pinned objects
IPFSPinsAPI getPinListByIpfsPath GET /ipfs/pin/list/{IPFS_path} Get details about pinned object
IPFSPinsAPI pinAdd POST /ipfs/pin/add/{IPFS_path} Pin an object
IPFSPinsAPI removePin POST /ipfs/pin/remove/{IPFS_path}
MetricsAPI getMetrics GET /metrics/ Blockfrost usage metrics
MetricsAPI getMetricsEndpoints GET /metrics/endpoints Blockfrost endpoint usage metrics
NutLinkAPI getAddress GET /nutlink/{address}
NutLinkAPI getAddressTickers GET /nutlink/{address}/tickers
NutLinkAPI getTickerRecordsByAddressAndTicker GET /nutlink/{address}/tickers/{ticker}
NutLinkAPI getTickerRecordsByTicker GET /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

Description

  • Swift Tools 5.3.0
View More Packages from this Author

Dependencies

Last updated: Thu Nov 10 2022 10:29:10 GMT-0500 (GMT-05:00)