blockfrost-client: blockfrost.io 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]

Warnings:

Simple Blockfrost clients for use with transformers or mtl


[Skip to Readme]

Properties

Versions 0.1.0.0, 0.2.0.0, 0.2.1.0, 0.3.0.0, 0.3.1.0, 0.4.0.0, 0.4.0.1, 0.5.0.0, 0.6.0.0, 0.7.0.0, 0.7.1.0, 0.7.1.0, 0.7.1.1, 0.8.0.0, 0.8.0.1
Change log CHANGELOG.md
Dependencies base (>=4.7 && <5), blockfrost-api (>=0.7.1 && <0.8), blockfrost-client, blockfrost-client-core (>=0.6 && <0.7), bytestring, data-default, directory, filepath, mtl, servant (>=0.18 && <0.20), servant-client, servant-client-core, text [details]
License Apache-2.0
Copyright 2021 blockfrost.io
Author blockfrost.io
Maintainer srk@48.io
Category Cardano
Home page https://github.com/blockfrost/blockfrost-haskell
Source repo head: git clone https://github.com/blockfrost/blockfrost-haskell
Uploaded by srk at 2023-01-03T14:35:31Z

Modules

[Index] [Quick Jump]

Flags

Manual Flags

NameDescriptionDefault
examples

Build examples

Disabled
production

Production build

Disabled
Automatic Flags
NameDescriptionDefault
buildfast

Turn off optimizations

Enabled

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

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for blockfrost-client-0.7.1.0

[back to package description]

blockfrost-client

Haskell SDK for Blockfrost.io API.

Development shell

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

Usage

Blockfrost.io API token is required to use this SDK.

Obtaining token

Create a project at blockfrost.io 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
  where

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