TrueBlocks API (2.5.8-release)

Download OpenAPI specification:Download

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

How to use this API effectively

The endpoints in this API 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 data returned by each command, 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> [ items <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)

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

Responses

Response samples

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

Export details

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

query Parameters
addrs
required
Array of strings <address> [ items <address > ]

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

topics
Array of strings <topic> [ items <topic > ]

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

fourbytes
Array of strings <fourbyte> [ items <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

withdrawals
boolean

export withdrawals for the given address

articulate
boolean

articulate transactions, traces, logs, and outputs

cacheTraces
boolean

force the transaction's traces into the cache

count
boolean

for --appearances mode only, display only the count 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> [ items <address > ]

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

topic
Array of strings <topic> [ items <topic > ]

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

reverted
boolean

export only transactions that were reverted

asset
Array of strings <address> [ items <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)

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

ether
boolean

export values in ether

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> [ items <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

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

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> [ items <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

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

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> [ items <address > ]

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

known
boolean

load common 'known' ABIs from cache

proxyFor
string

redirects the query to this implementation

find
Array of strings <string> [ items <string > ]

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

hint
Array of strings <string> [ items <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

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

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

query Parameters
blocks
required
Array of strings <blknum> [ items <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

traces
boolean

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

uniq
boolean

display a list of uniq address appearances per transaction

flow
string
Enum: "from" "to" "reward"

for the --uniq option only, export only from or to (including trace from or to)

logs
boolean

display only the logs found in the block(s)

emitter
Array of strings <address> [ items <address > ]

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

topic
Array of strings <topic> [ items <topic > ]

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

withdrawals
boolean

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

articulate
boolean

for the --logs option only, articulate the retrieved data if ABIs can be found

bigRange
number <uint64>

for the --logs option only, allow for block ranges larger than 500

count
boolean

display only the count of appearances for --addrs or --uniq

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

ether
boolean

export values in ether

raw
boolean

report raw data directly from the source

Responses

Response samples

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

Get transactions

Retrieve one or more transactions from the chain or local cache. Corresponds to the chifra transactions command line.

query Parameters
transactions
required
Array of strings <tx_id> [ items <tx_id > ]

a space-separated list of one or more transaction identifiers

articulate
boolean

articulate the retrieved data if ABIs can be found

traces
boolean

include the transaction's traces in the results

uniq
boolean

display a list of uniq addresses found in the transaction

flow
string
Enum: "from" "to"

for the uniq option only, export only from or to (including trace from or to)

logs
boolean

display only the logs found in the transaction(s)

emitter
Array of strings <address> [ items <address > ]

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

topic
Array of strings <topic> [ items <topic > ]

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

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

ether
boolean

export values in ether

raw
boolean

report raw data directly from the source

Responses

Response samples

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

Get receipts

Retrieve receipts for the given transaction(s). Corresponds to the chifra receipts command line.

query Parameters
transactions
required
Array of strings <tx_id> [ items <tx_id > ]

a space-separated list of one or more transaction identifiers

articulate
boolean

articulate the retrieved data if ABIs can be found

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

raw
boolean

report raw data directly from the source

Responses

Response samples

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

Get logs

Retrieve logs for the given transaction(s). Corresponds to the chifra logs command line.

query Parameters
transactions
required
Array of strings <tx_id> [ items <tx_id > ]

a space-separated list of one or more transaction identifiers

emitter
Array of strings <address> [ items <address > ]

filter logs to show only those logs emitted by the given address(es)

topic
Array of strings <topic> [ items <topic > ]

filter logs to show only those with this topic(s)

articulate
boolean

articulate the retrieved data if ABIs can be found

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

raw
boolean

report raw data directly from the source

Responses

Response samples

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

Get traces

Retrieve traces for the given transaction(s). Corresponds to the chifra traces command line.

query Parameters
transactions
required
Array of strings <tx_id> [ items <tx_id > ]

a space-separated list of one or more transaction identifiers

articulate
boolean

articulate the retrieved data if ABIs can be found

filter
string

call the node's trace_filter routine with bang-separated filter

count
boolean

display only the number of traces for the transaction (fast)

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

ether
boolean

export values in ether

raw
boolean

report raw data directly from the source

Responses

Response samples

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

Get block dates

Find block(s) based on date, blockNum, timestamp, or 'special'. Corresponds to the chifra when command line.

query Parameters
blocks
Array of strings <string> [ items <string > ]

one or more dates, block numbers, hashes, or special named blocks (see notes)

list
boolean

export a list of the 'special' blocks

timestamps
boolean

display or process timestamps

count
boolean

with --timestamps only, returns the number of timestamps in the cache

repair
boolean

with --timestamps only, repairs block(s) in the block range by re-querying from the chain

check
boolean

with --timestamps only, checks the validity of the timestamp data

deep
boolean

with --timestamps --check only, verifies timestamps from on chain (slow)

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

Responses

Response samples

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

Chain State

Access to account and token state

Get balance(s)

Retrieve account balance(s) for one or more addresses at given block(s). Corresponds to the chifra state command line.

query Parameters
addrs
required
Array of strings <address> [ items <address > ]

one or more addresses (0x...) from which to retrieve balances

blocks
Array of strings <blknum> [ items <blknum > ]

an optional list of one or more blocks at which to report balances, defaults to 'latest'

parts
Array of strings
Items Enum: "none" "some" "all" "balance" "nonce" "code" "proxy" "deployed" "accttype"

control which state to export

changes
boolean

only report a balance when it changes from one block to the next

noZero
boolean

suppress the display of zero balance accounts

call
string

call a smart contract with a solidity syntax, a four-byte and parameters, or encoded call data

articulate
boolean

for the --call option only, articulate the retrieved data if ABIs can be found

proxyFor
string

for the --call option only, redirects calls to this implementation

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

ether
boolean

export values in ether

Responses

Response samples

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

Get token balance(s)

Retrieve token balance(s) for one or more addresses at given block(s). Corresponds to the chifra tokens command line.

query Parameters
addrs
required
Array of strings <address> >= 2 items [ items <address > ]

two or more addresses (0x...), the first is an ERC20 token, balances for the rest are reported

blocks
Array of strings <blknum> [ items <blknum > ]

an optional list of one or more blocks at which to report balances, defaults to 'latest'

parts
Array of strings
Items Enum: "name" "symbol" "decimals" "totalSupply" "version" "all"

which parts of the token information to retrieve

byAcct
boolean

consider each address an ERC20 token except the last, whose balance is reported for each token

changes
boolean

only report a balance when it changes from one block to the next

noZero
boolean

suppress the display of zero balance accounts

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

Responses

Response samples

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

Admin

Control the scraper and build the index

Manage config

Report on and edit the configuration of the TrueBlocks system. Corresponds to the chifra config command line.

query Parameters
mode
string
Enum: "show" "edit"

either show or edit the configuration

paths
boolean

show the configuration paths for the system

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

Responses

Response samples

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

Get status on caches

Report on the state of the internal binary caches. Corresponds to the chifra status command line.

query Parameters
modes
Array of strings
Items Enum: "index" "blooms" "blocks" "transactions" "traces" "logs" "statements" "results" "state" "tokens" "monitors" "names" "abis" "slurps" "staging" "unripe" "maps" "some" "all"

the (optional) name of the binary cache to report on, terse otherwise

diagnose
boolean

same as the default but with additional diagnostics

firstRecord
number <uint64>

the first record to process

maxRecords
number <uint64>

the maximum number of records to process

chains
boolean

include a list of chain configurations in the output

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

Responses

Response samples

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

Scrape index

Scan the chain and update the TrueBlocks index of appearances. Corresponds to the chifra scrape command line.

query Parameters
blockCnt
number <uint64>

maximum number of blocks to process per pass

sleep
number <double>

seconds to sleep between scraper passes

touch
number <uint64>

first block to visit when scraping (snapped back to most recent snap_to_grid mark)

chain
string

the chain to use

Responses

Response samples

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

Manage chunks

Manage, investigate, and display the Unchained Index. Corresponds to the chifra chunks command line.

query Parameters
mode
required
string
Enum: "manifest" "index" "blooms" "pins" "addresses" "appearances" "stats"

the type of data to process

blocks
Array of strings <blknum> [ items <blknum > ]

an optional list of blocks to intersect with chunk ranges

check
boolean

check the manifest, index, or blooms for internal consistency

pin
boolean

pin the manifest or each index chunk and bloom

publish
boolean

publish the manifest to the Unchained Index smart contract

remote
boolean

prior to processing, retrieve the manifest from the Unchained Index smart contract

belongs
Array of strings <address> [ items <address > ]

in index mode only, checks the address(es) for inclusion in the given index chunk

firstBlock
number <blknum>

first block to process (inclusive)

lastBlock
number <blknum>

last block to process (inclusive)

maxAddrs
number <blknum>

the max number of addresses to process in a given chunk

deep
boolean

if true, dig more deeply during checking (manifest only)

rewrite
boolean

for the --pin --deep mode only, writes the manifest back to the index folder (see notes)

count
boolean

for the pins mode only, display only the count of records

sleep
number <double>

for --remote pinning only, seconds to sleep between API calls

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

Responses

Response samples

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

Initialize index

Initialize the TrueBlocks system by downloading the Unchained Index from IPFS. Corresponds to the chifra init command line.

query Parameters
all
boolean

in addition to Bloom filters, download full index chunks (recommended)

dryRun
boolean

display the results of the download without actually downloading

firstBlock
number <blknum>

do not download any chunks earlier than this block

sleep
number <double>

seconds to sleep between downloads

chain
string

the chain to use

Responses

Response samples

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

Other

Access to other and external data

Slurp Etherscan

Fetch data from Etherscan for any address. Corresponds to the chifra slurp command line.

query Parameters
addrs
required
Array of strings <address> [ items <address > ]

one or more addresses to slurp from Etherscan

blocks
Array of strings <blknum> [ items <blknum > ]

an optional range of blocks to slurp

types
Array of strings
Items Enum: "ext" "int" "token" "nfts" "1155" "miner" "uncles" "withdrawals" "all"

which types of transactions to request

appearances
boolean

show only the blocknumber.tx_id appearances of the exported transactions

articulate
boolean

articulate the retrieved data if ABIs can be found

source
string
Enum: "etherscan" "key"

the source of the slurped data

count
boolean

for --appearances mode only, display only the count of records

sleep
number <double>

seconds to sleep between requests

fmt
string

export format, one of [none

chain
string

the chain to use

noheader
boolean

suppress the header in the output

cache
boolean

force the results of the query into the cache

decache
boolean

removes related items from the cache

ether
boolean

export values in ether

raw
boolean

report raw data directly from the source

Responses

Response samples

Content type
application/json
[
  • {
    }
]