TrueBlocks API (0.15.0-alpha)

Download OpenAPI specification:Download

E-mail: jrush@trueblocks.io URL: https://www.trueblocks.io License: GPL 3.0

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

Install the trueblocks-core application on your machine, change your configs as needed.
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": [{"blockNumber": 8854723,
"transactionIndex": 61,
"address": "0xf503017d7baf7fbc0fff7492b751025c6a78179b",
"name": "TrueBlocks 2020 Wallet 0xf503"
},
{"blockNumber": 8855603,
"transactionIndex": 121,
"address": "0xf503017d7baf7fbc0fff7492b751025c6a78179b",
"name": "TrueBlocks 2020 Wallet 0xf503"
},
{"...": "..."
}
]
}

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": [{"hash": "0x1a898c5448b37f693343917ea40b7ad1c43b28a4ddd37af1bd6d0bb4a0c99891",
"blockHash": "0x1d7f60b34bad8ce0ba5e49e3845c7a62ba8db440b81f8df98ec6349c4d28ca8e",
"blockNumber": 8854723,
"transactionIndex": 61,
"timestamp": 1572639538,
"from": "0xbb984f85bd52d78eb2fbf2c5598bae7abb98c5bc",
"to": "0xf503017d7baf7fbc0fff7492b751025c6a78179b",
"value": 5000000000000000000,
"gas": 21000,
"gasPrice": 10000000000,
"maxFeePerGas": 0,
"maxPriorityFeePerGas": 0,
"isError": 0,
"hasToken": 0,
"receipt": {"contractAddress": "0x0",
"gasUsed": 21000,
"effectiveGasPrice": 10000000000,
"status": 1
},
"compressedTx": "0x ( )",
"gasCost": 210000000000000,
"gasUsed": 21000,
"date": "2019-11-01 20:18:58 UTC",
"ether": 5
}
]
}

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": [{"nApps": 0,
"firstApp": 0,
"latestApp": 0,
"sizeInBytes": 0,
"tags": "string",
"address": "string",
"is_custom": true
}
]
}

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

[{"tags": "50-Tokens:ERC20",
"address": "0xfe5f141bf94fe84bc28ded0ab966c16b17490657",
"name": "LibraToken",
"symbol": "LBA",
"source": "On chain",
"decimals": 18,
"description": "Decentralized lending infrastructure facilitating open access to credit networks on Ethereum."
}
]

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": [{"name": "PairCreated",
"type": "event",
"stateMutability": "nonpayable",
"signature": "PairCreated(address,address,address,uint256)",
"encoding": "0x0d3648bd0f6ba80134a33ba9275ac585d9d315f0ad8355cddefde31afa28d0e9",
"inputs": [{"type": "address",
"name": "token0",
"indexed": true,
"internalType": "address"
},
{"type": "address",
"name": "token1",
"indexed": true,
"internalType": "address"
},
{"type": "address",
"name": "pair",
"internalType": "address"
},
{"type": "uint256",
"name": "val_0",
"internalType": "uint256"
}
]
}
]
}

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