TrueBlocks API (1.0.0-release)

Download OpenAPI specification:Download

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

How to use this API effectively

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 daemon

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. Corresponds to the chifra list command line.

query Parameters
addrs
required
Array of strings <address>

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

count
boolean

display only the count of records for each monitor

noZero
boolean

for the --count option only, suppress the display of zero appearance accounts

bounds
boolean

report first and last block this address appears

unripe
boolean

list transactions labeled upripe (i.e. less than 28 blocks old)

silent
boolean

freshen the monitor only (no reporting)

firstRecord
number <uint64>

the first record to process

maxRecords
number <uint64>

the maximum number of records to process

reversed
boolean

produce results in reverse chronological order

firstBlock
number <blknum>

first block to export (inclusive, ignored when freshening)

lastBlock
number <blknum>

last block to export (inclusive, ignored when freshening)

Responses

Response samples

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

Export details

Export full detail of transactions for one or more addresses. Corresponds to the chifra export command line.

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

neighbors
boolean

export the neighbors of the given address

accounting
boolean

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

statements
boolean

for the accounting options only, export only statements

balances
boolean

traverse the transaction history and show each change in ETH balances

articulate
boolean

articulate transactions, traces, logs, and outputs

cacheTraces
boolean

force the transaction's traces into the cache

count
boolean

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

firstRecord
number <uint64>

the first record to process

maxRecords
number <uint64>

the maximum number of records to process

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)

asset
Array of strings <address>

for the accounting options only, export statements only for this asset

flow
string
Enum: "in" "out" "zero"

for the accounting options only, export statements with incoming, outgoing, or zero value

factory
boolean

for --traces only, report addresses created by (or self-destructed by) the given address(es)

unripe
boolean

export transactions labeled upripe (i.e. less than 28 blocks old)

reversed
boolean

produce results in reverse chronological order

noZero
boolean

for the --count option only, suppress the display of zero appearance accounts

firstBlock
number <blknum>

first block to process (inclusive)

lastBlock
number <blknum>

last block to process (inclusive)

ether
boolean

export values in ether

cache
boolean

force the results of the query into the cache

Responses

Response samples

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

Manage monitors

Add, remove, clean, and list address monitors. Corresponds to the chifra monitors command line.

query Parameters
addrs
Array of strings <address>

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

clean
boolean

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

list
boolean

list monitors in the cache (--verbose for more detail)

watch
boolean

continually scan for new blocks and extract data as per the command file

watchlist
string

available with --watch option only, a file containing the addresses to watch

commands
string

available with --watch option only, the file containing the list of commands to apply to each watched address

batchSize
number <uint64>

available with --watch option only, the number of monitors to process in each batch

sleep
number <double>

available with --watch option only, the number of seconds to sleep between runs

delete
boolean

delete the item, but do not remove it

undelete
boolean

undelete a previously deleted item

remove
boolean

remove a previously deleted item

Responses

Response samples

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

Names

Query addresses or names of well known accounts. Corresponds to the chifra names command line.

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 (including custom) names in the search

custom
boolean

include only custom named accounts in the search

prefund
boolean

include prefund accounts in the search

addr
boolean

display only addresses in the results (useful for scripting, assumes --no_header)

tags
boolean

export the list of tags and subtags only

clean
boolean

clean the data (addrs to lower case, sort by addr)

regular
boolean

only available with --clean, cleans regular names database

dryRun
boolean

only available with --clean or --autoname, outputs changes to stdout instead of updating databases

autoname
string

an address assumed to be a token, added automatically to names database if true

delete
boolean

delete the item, but do not remove it

undelete
boolean

undelete a previously deleted item

remove
boolean

remove a previously deleted item

Responses

Response samples

Content type
application/json
[
  • {
    }
]

ABIs

Fetches the ABI for a smart contract. Corresponds to the chifra abis command line.

query Parameters
addrs
required
Array of strings <address>

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

known
boolean

load common 'known' ABIs from cache

find
Array of strings <string>

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

hint
Array of strings <string>

for the --find option only, provide hints to speed up the search

encode
string

generate the 32-byte encoding for a given cannonical function or event signature

clean
boolean

remove an abi file for an address or all zero-length files if no address is given

Responses