TrueBlocks API (0.15.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_t>

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_t>

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

topics
Array of strings <topic_t>

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

fourbytes
Array of strings <fourbyte_t>

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 transaction list

statements
boolean

for use with --accounting option only, export only reconciliation statements

logs
boolean

export logs instead of transaction list

traces
boolean

export traces instead of transaction list

accounting
boolean

export accounting records instead of transaction list

articulate
boolean

articulate transactions, traces, logs, and outputs

cache_txs
boolean

write transactions to the cache (see notes)

cache_traces
boolean

write traces to the cache (see notes)

emitter
boolean

for log export only, export only if one of the given export addresses emitted the event

source
Array of strings <address_t>

for log export only, export only one of these addresses emitted the event

relevant
boolean

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

count
boolean

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

first_record
string

the first record to process

max_records
string

the maximum number of records to process before reporting

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_t>

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 all existing 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_t>

a space separated list of one or more search terms

expand
boolean

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

match_case
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_t>

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

sol
string

file name of .sol file from which to create a new known abi (without .sol)

find
Array of strings <string_t>

try to search for a function declaration given a four byte code

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_t>

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 only the list of address appearances in the block

uniq
boolean

display only the list of uniq address appearances in the block

uniq_tx
boolean

display only the list of uniq address appearances in each transaction

count
boolean

display the number of the lists of appearances for --apps, --uniq, or --uniq_tx

cache
boolean

force a write of the block to the cache

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.

query Parameters
transactions
required
Array of strings <tx_id_t>

a space-separated list of one or more transaction identifiers

articulate
boolean

articulate the retrieved data if ABIs can be found