README.md

REST API

The REST API is the main API to retrieve data from the mirror node. Further documentation is available on docs.hedera.com and via our Swagger UI.

Database

This section documents the tables used for different endpoints and query parameters. This information is useful for debugging purposes and for understanding the update cadence of the underlying data.

Endpoint	Tables	Notes
/api/v1/accounts	entity, entity_stake, token_account	Entity tables first used to filter, then joined with token_account
/api/v1/accounts?balance=false	entity, entity_stake	token_account skipped
/api/v1/accounts/:idOrAlias	crypto_transfer, entity, entity_stake, token_account, token_transfer, transaction	Transfers & transactions are present only for legacy reasons.
/api/v1/accounts/:idOrAlias?timestamp=	account_balance, crypto_transfer, entity, entity_history, entity_stake, entity_stake_history, token_balance, token_transfer, transaction	Transfers & transactions are present only for legacy reasons.
/api/v1/accounts/:idOrAlias?transactions=false	entity, entity_stake, token_account
/api/v1/accounts/:id/allowances/crypto	crypto_allowance
/api/v1/accounts/:id/allowances/nfts	nft_allowance
/api/v1/accounts/:id/allowances/tokens	token_allowance
/api/v1/accounts/:alias/allowances/crypto	crypto_allowance, entity	Separate alias lookup first
/api/v1/accounts/:aliasOrAddress/allowances/nfts	nft_allowance, entity	Separate alias or EVM address lookup first
/api/v1/accounts/:alias/allowances/tokens	token_allowance, entity	Separate alias lookup first
/api/v1/accounts/:id/nfts	nft
/api/v1/accounts/:alias/nfts	entity, nft	Separate alias lookup first
/api/v1/accounts/:idOrAlias/rewards	entity, staking_reward_transfer
/api/v1/accounts/:idOrAlias/tokens	entity, token_account
/api/v1/balances	entity, token_account
/api/v1/balances?account.publickey	entity, token_account	entity table used to find by public key
/api/v1/balances?timestamp	account_balance, token_balance
/api/v1/blocks	record_file
/api/v1/blocks/:hashOrNumber	record_file
/api/v1/contracts	contract, entity
/api/v1/contracts/:idOrAddress	contract, entity, file_data	file_data used to get init bytecode
/api/v1/contracts/:idOrAddress?timestamp=	contract, entity, entity_history, file_data	Union both contract tables to find latest timestamp in range
/api/v1/contracts/:idOrAddress/results	contract_result, entity	ethereum_transaction for hash and transaction for index
/api/v1/contracts/:idOrAddress/results?block.hash	contract_result, entity, record_file	Separate block lookup by hash first
/api/v1/contracts/:idOrAddress/results?block.number	contract_result, entity, record_file	Separate block lookup by number first
/api/v1/contracts/:idOrAddress/results/:timestamp	contract_log, contract_result, contract_state_change, contract_transaction, entity, ethereum_transaction, record_file, transaction
/api/v1/contracts/:idOrAddress/results/logs	contract_log, entity, record_file
/api/v1/contracts/results	contract_result, entity, ethereum_transaction, record_file
/api/v1/contracts/results/:transactionIdOrHash	contract_log, contract_result, contract_transaction, contract_transaction_hash,contract_state_change, entity, ethereum_transaction, record_file, transaction
/api/v1/contracts/results/:transactionIdOrHash/actions	contract_action, contract_transaction_hash, transaction
/api/v1/contracts/results/logs	contract_log, entity, record_file
/api/v1/network/exchangerate	file_data
/api/v1/network/fees	file_data
/api/v1/network/nodes	address_book, address_book_entry, address_book_service_endpoint, node_stake
/api/v1/network/stake	network_stake
/api/v1/network/supply	entity
/api/v1/network/supply?timestamp=	account_balance
/api/v1/schedules	entity, schedule, transaction_signature
/api/v1/schedules/:id	entity, schedule, transaction_signature
/api/v1/tokens	entity, token
/api/v1/tokens?account.id	entity, token, token_account
/api/v1/tokens/:id	custom_fee, entity, token
/api/v1/tokens/:id/balances	token_account
/api/v1/tokens/:id/balances?timestamp=	token_balance
/api/v1/tokens/:id/balances?account.publickey	entity, token_balance
/api/v1/tokens/:id/nfts	entity, nft
/api/v1/tokens/:id/nfts/:serial	entity, nft
/api/v1/tokens/:id/nfts/:serial/transactions	nft, nft_history, transaction
/api/v1/topics/:id/messages	topic_message
/api/v1/topics/:id	entity
/api/v1/topics/:id/messages/:number	topic_message
/api/v1/topics/messages/:timestamp	topic_message
/api/v1/transactions	crypto_transfer, token_transfer, transaction	Transfers are present only for legacy reasons
/api/v1/transactions/:idOrHash	assessed_custom_fee, crypto_transfer, nft_transfer, token_transfer, transaction

V2 API

There are a number of endpoints that have unfortunate design decisions that make them difficult to use or that don't scale with terabytes of data. It would be considered a breaking change if we were to change these endpoints. To address them, we would have to create version two of the API. This section documents the API's current shortcomings to note these problems for users, and so we know what to fix if we ever decide to create a v2 API.

• /api/v1/transactions, /api/v1/transactions, and /api/v1/accounts/{id} have max_fee and valid_duration_seconds as strings instead of numbers.
• /api/v1/tokens/{id} has expiry_timestamp as a number instead of a string that supports seconds.nanoseconds format like the same field in other APIs.
• The account.balance query parameter on /api/v1/accounts and /api/v1/balances has performance issues since depending upon the parameter value it can scan a large number of rows.
• List APIs in general have performance issues due to the sharded nature of the underlying tables. We should remove these APIs or change them to only return the most recent data without sorting or pagination.