blockfrost-client: basic client

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]


Simple Blockfrost clients for use with transformers or mtl

[Skip to Readme]


Change log
Dependencies base (>=4.7 && <5), blockfrost-api (>=0.3.1 && <0.4), blockfrost-client, blockfrost-client-core, bytestring, data-default, directory, filepath, mtl, servant (>=0.18 && <0.19), servant-client, servant-client-core, text [details]
License Apache-2.0
Copyright 2021
Category Cardano
Home page
Source repo head: git clone
Uploaded by srk at 2022-02-17T13:28:53Z


[Index] [Quick Jump]


Manual Flags


Build examples


Production build

Automatic Flags

Turn off optimizations


Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info


Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees

Readme for blockfrost-client-

[back to package description]


Haskell SDK for API.

Development shell

nix-shell # from repository root, optional
cabal repl blockfrost-client

Usage API token is required to use this SDK.

Obtaining token

Create a project at and save the generated token to a file.

For authentication, client uses a Project type which carries an environment and a token itself, for example Project Testnet "someToken".

Project from file

Instead of constructing this type manually, you can load the Project from file using projectFromFile "/secrets/blockfrost-testnet-token".

In this case, token needs to be prefixed with the enviromnent to which it belongs to. The format expected is <env><token> (similar to human readable identifiers used for Cardano keys and addresses), examples:

Using environment variables

In similar manner to loading project from file, you can use projectFromEnv function to load the Project from file pointed to by BLOCKFROST_TOKEN_PATH environment variable.

For custom variable name, a principled version projectFromEnv' "CUSTOM_ENV_VAR" can be used instead.

Exploring the API

You can now perform queries from cabal repl blockfrost-client, an example session follows:

λ: testnet <- projectFromFile "/secrets/blockfrost.testnet.token"
λ: testnet
Project {projectEnv = Testnet, projectId = "censored"}
λ: runBlockfrost testnet $ getLatestBlock
Right (Block {_blockTime = 1629716610s, ... })
λ: runBlockfrost testnet $ listPools
Right [PoolId "pool1adur9jcn0dkjpm3v8ayf94yn3fe5xfk2rqfz7rfpuh6cw6evd7w", ... ]

Pagination and sorting

Some API functions have a variant with trailing '. These accept Paged and SortOrder arguments for querying multiple pages and setting a custom sort order.

For example to query the second page of pool list, we can use listPools'

λ: runBlockfrost testnet $ listPools' (page 2) desc

To use default ordering (which is asc or Ascending), you can just use re-exported def from Data.Default.

λ: runBlockfrost testnet $ listPools' (page 2) def

Similar, to just change an ordering but use default page size and a first page:

λ: runBlockfrost testnet $ listPools' def desc

Catching errors

We can use tryError inside BlockfrostClient monad to try a call, when we it may fail (dealing with external inputs, enumerating addresses).

Complete program example with error handling:

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE ScopedTypeVariables #-}
module Main

import Blockfrost.Client

main = do
  -- reads token from BLOCKFROST_TOKEN_PATH
  -- environment variable. It expects token
  -- prefixed with Blockfrost environment name
  -- e.g.: testnet-someTokenHash
  prj <- projectFromEnv
  res <- runBlockfrost prj $ do
    latestBlocks <- getLatestBlock
    (ers :: Either BlockfrostError [AccountReward]) <-
        tryError $ getAccountRewards "gonnaFail"
    pure (latestBlocks, ers)

  print res