TrueBlocks API (0.17.0-alpha)

Download OpenAPI specification:Download

A REST layer over the TrueBlocks application. With chifra serve, you can run this on your own machine, and make calls to localhost.

How to use this API

This API's endpoints are exact translations of the commands used by the chifra CLI application, and the query parameters mirror the commands' options and flags. If you want details, the commands have their own documentation page. For detailed descriptions of fields, see the data model reference.

Before you begin

  1. Install the trueblocks-core application on your machine, change your configs as needed.
  2. Run chifra serve

Example queries

By default, all calls are to localhost:8080. All options and flags are passed through query parameters.

For example, to get block 100, make a call to /blocks and specify the block you want in the query parameter:

 curl "http://localhost:8080/blocks?blocks=100"

Some parameters support ranges:

 curl "http://localhost:8080/blocks?blocks=100-120"

Other parameters let you filter your responses. For example, to get only the unique addresses from that block range:

 curl "http://localhost:8080/blocks?blocks=100-110&uniq=true"

You might want to cache queries on your local machine.

 "http://localhost:8080/blocks?blocks=100-110&cache=true"

Cacheing speeds up repeat queries significantly. The cache options are particularly useful for calls to data-rich endpoints, like most endpoints in the "Accounts" collection.

Of course, caches occupy local storage. So cache wisely.

Accounts

Access and cache transactional data

List transactions

List every appearance of an address anywhere on the chain.

query Parameters
addrs
required
Array of strings <address>

one or more addresses (0x...) to list

count
boolean

present only the number of records

appearances
boolean

export a list of appearances

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Export details

Export full detail of transactions for one or more addresses.

query Parameters
addrs
required
Array of strings <address>

one or more addresses (0x...) to export

topics
Array of strings <topic>

filter by one or more log topics (only for --logs option)

fourbytes
Array of strings <fourbyte>

filter by one or more fourbytes (only for transactions and trace options)

appearances
boolean

export a list of appearances

receipts
boolean

export receipts instead of transactional data

logs
boolean

export logs instead of transactional data

traces
boolean

export traces instead of transactional data

statements
boolean

export reconciliations instead of transactional data (requires --accounting option)

neighbors
boolean

export the neighbors of the given address

accounting
boolean

attach accounting records to the exported data (applies to transactions export only)

articulate
boolean

articulate transactions, traces, logs, and outputs

cache
boolean

write transactions to the cache (see notes)

cacheTraces
boolean

write traces to the cache (see notes)

count
boolean

only available for --appearances mode, if present, return only the number of records

firstRecord
string

the first record to process

maxRecords
string

the maximum number of records to process before reporting

relevant
boolean

for log and accounting export only, export only logs relevant to one of the given export addresses

emitter
Array of strings <address>

for log export only, export only logs if emitted by one of these address(es)

topic
Array of strings <topic>

for log export only, export only logs with this topic(s)

clean
boolean

clean (i.e. remove duplicate appearances) from all existing monitors

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Manage Monitors

Add, remove, clean, and list address monitors.

query Parameters
addrs
required
Array of strings <address>

one or more addresses (0x...) to process

appearances
boolean

export a list of appearances

count
boolean

present only the number of records

clean
boolean

clean (i.e. remove duplicate appearances) from monitors

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Names

Query addresses or names of well known accounts.

query Parameters
terms
required
Array of strings <string>

a space separated list of one or more search terms

expand
boolean

expand search to include all fields (search name, address, and symbol otherwise)

matchCase
boolean

do case-sensitive search

all
boolean

include all accounts in the search

custom
boolean

include your custom named accounts

prefund
boolean

include prefund accounts

named
boolean

include well know token and airdrop addresses in the search

addr
boolean

display only addresses in the results (useful for scripting)

collections
boolean

display collections data

tags
boolean

export the list of tags and subtags only

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ABIs

Fetches the ABI for a smart contract.

query Parameters
addrs
required
Array of strings <address>

a list of one or more smart contracts whose ABIs to display

sol
boolean

extract the abi definition from the provided .sol file(s)

find
Array of strings <string>

search for function or event declarations given a four- or 32-byte code(s)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Chain Data

Access and cache blockchain-related data

Get blocks

Retrieve one or more blocks from the chain or local cache.

query Parameters
blocks
required
Array of strings <blknum>

a space-separated list of one or more block identifiers

hashes
boolean

display only transaction hashes, default is to display full transaction detail

uncles
boolean

display uncle blocks (if any) instead of the requested block

trace
boolean

export the traces from the block as opposed to the block data

apps
boolean

display a list of uniq address appearances in the block

uniq
boolean

display a list of uniq address appearances per transaction

logs
boolean

display only the logs found in the block(s)

emitter
Array of strings <address>

for the --logs option only, filter logs to show only those logs emitted by the given address(es)

topic
Array of strings <topic>

for the --logs option only, filter logs to show only those with this topic(s)

count
boolean

display the number of the lists of appearances for --addrs or --uniq

cache
boolean

force a write of the block to the cache

Responses

Response samples

Content type
application/json
{
  • "blockNumber": 3141592,
  • "hash": "0x0b4c6fb75ded4b90218cf0346b0885e442878f104e1b60bf75d5b6860eeacd53",
  • "...": "...",
  • "transactions": [ ]
}