REST API
The mirror node REST API offers the ability to query transaction information.
Hedera Mirror Nodes store the history of transactions that occurred on mainnet, testnet, and previewnet. Each transaction generates a record that is stored in a record file. The transaction contents can be accessed by the mirror node Rest APIs
To make a request, use the network endpoint and the Rest API of choice. For example, to get a list of transactions on mainnet you would make the following request.
You can also view the Hedera Mirror Node Swagger UI documentation where you can submit requests and view responses for previewnet, testnet, and mainnet.
Public mainnet mirror node requests are throttled at 100 requests per second (rps). This may change in the future depending upon performance or security considerations. At this time, no authentication is required.
The accounts object represents the information associated with an account and returns a list of account information.
Account IDs take the following format: 0.0.<account number>.
Example: 0.0.1000
Account IDs can also take the account number as an input value. For example, for account ID 0.0.1000, the number 1000 can be specified in the request.
get
/api/v1/accounts
List account entities on network
Response Item | Description |
account | The ID of the account |
alias | RFC4648 no-padding base32 encoded account alias |
auto renew period | The period in which the account will auto renew |
balance | The timestamp and account balance of the account |
decline_reward | Whether or not the account has opted to decline a staking reward |
ethereum_nonce | The ethereum transaction nonce associated with this account |
evm_address | A network entity encoded as an EVM encoded hex |
tokens | The tokens and their balances associated to the specified account |
deleted | Whether the account was deleted or not (Boolean) |
expiry timestamp | The expiry date for the entity as set by a create or update transaction |
key | The public key associated with the account |
max_automatic_token_associations | The number of automatic token associations, if any |
pending_reward | The account's pending staking reward that has not been transferred to the account |
memo | The account memo, if any |
receiver_sig_required | Whether or not the account requires a signature to receive a transfer into the account |
staked_account_id | The account ID the account is staked to, if set |
staked_node_id | The node ID the account is staked to, if set |
stake period start | The start of the staking period |
links.next | Hyperlink to the next page of results |
Operator | Example | Description |
|---|---|---|
lt (less than) | /api/v1/accounts?account.id=lt:0.0.1000 | Returns account IDs less then 1000 |
lte (less than or equal to) | /api/v1/accounts?account.id=lte:0.0.1000 | Returns account IDs less than or equal to 1000 |
gt (greater than) | /api/v1/accounts?account.id=gt:0.0.1000 | Returns account IDs greater than 1000 |
gte (greater than or equal to) | /api/v1/accounts?account.id=gte:0.0.1000 | Returns account IDs greater than or equal to 1000 |
order (order asc or desc values) | /api/v1/accounts?order=asc /api/v1/accounts?order=desc | Returns account information in ascending order Returns account information in descending order |
Example Requests | Description |
|---|---|
/api/v1/accounts?account.id=0.0.1001 | Returns the account information of account 1001 |
/api/v1/accounts?account.balance=gt:1000 | Returns all account information that have a balance greater than 1000 tinybars |
/api/v1/accounts?account.publickey=2b60955bcbf0cf5e9ea880b52e5b63f664b08edf6ed 15e301049517438d61864 | Returns all account information for 2b60955bcbf0cf5e9ea880b52e5b63f664b08edf6ed15e301049517438d61864 public key |
/api/v1/accounts/2?transactionType=cryptotransfer | Returns the crypto transfer transactions for account 2. |
get
/api/v1/accounts/{idOrAliasOrEvmAddress}
Get account by alias, id, or evm address
get
/api/v1/accounts/{accountId}/nfts
NFTs by account ID
get
/api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/crypto
Get crypto allowances for an account info
get
/api/v1/accounts/{accountAliasOrAccountId}/allowances/tokens
Fungible token allowances for an account
get
/api/v1/accounts/{idOrAliasOrEvmAddress}/tokens
Get token relationships info for an account
The balance object represents the balance of accounts on the Hedera network. You can retrieve this to view the most recent balance of all the accounts on the network at that given time. The balances object returns the account ID and the balance in hbars. Balances are checked on a periodic basis and thus return the most recent snapshot of time captured prior to the request.
get
/api/v1/balances
account balances
Response Item | Description |
|---|---|
timestamp | The seconds.nanoseconds of the timestamp at which the list of balances for each account are returned |
balances | List of balances for each account |
account | The ID of the account |
balance | The balance of the account |
tokens | The tokens that are associated to this account |
tokens.token_id | The ID of the token associated to this account |
tokens.balance | The token balance for the specified token associated to this account |
links.next | Hyperlink to the next page of results |
Operator | Example | Description |
|---|---|---|
lt (less than) | /api/v1/balances?account.id=lt:0.0.1000 | Returns the balances of account IDs less than 1,000 |
lte (less than or equal to) | /api/v1/balances?account.id=lte:0.0.1000 | Returns the balances account IDs less than or equal to 1,000 |
gt (greater than) | /api/v1/balances?account.id=gt:0.0.1000 | Returns the balances of account IDs greater than to 1,000 |
gte (greater than or equal to) | /api/v1/balances?account.id=gte:0.0.1000 | Returns the balances of account IDs greater than or equal to 1,000 |
order (order asc or desc values) | /api/v1/balances?order=asc /api/v1/balances?order=desc | Lists balances in ascending order Lists balances in descending order |
Example Requests | Description |
|---|---|
/api/v1/balances?account.id=0.0.1000 | Returns balance for account ID 1,000 |
/api/v1/balances?account.balance=gt:1000 | Returns all account IDs that have a balance greater than 1000 tinybars |
/api/v1/balances?timestamp=1566562500.040961001 | Returns all account balances referencing the latest snapshot that occurred prior to 1566562500 seconds and 040961001 nanoseconds |
/api/v1/balances?account.publickey=2b60955bcbf0cf5e9ea880b52e5b6 3f664b08edf6ed15e301049517438d61864 | Returns balance information for 2b60955bcbf0cf5e9ea880b52e5b63f664b08edf6ed 15e301049517438d61864 public key |
The transaction object represents the transactions processed on the Hedera network. You can retrieve this to view the transaction metadata information including transaction id, timestamp, transaction fee, transfer list, etc. If a transaction was submitted to multiple nodes, the successful transaction and duplicate transaction(s) will be returned as separate entries in the response with the same transaction ID. Duplicate transactions will still be assessed network fees.
get
/api/v1/transactions
transactions
Response Item | Description |
|---|---|
consensus timestamp | The consensus timestamp in seconds.nanoseconds |
transaction hash | The hash value of the transaction processed on the Hedera network |
valid start timestamp | The time the transaction is valid |
charged tx fee | The transaction fee that was charged for that transaction |
transaction id | The ID of the transaction |
memo base64 | The memo attached to the transaction encoded in Base64 format |
result | Whether the cryptocurrency transaction was successful or not |
entity ID | The entity ID that is created from create transactions (AccountCreateTransaction, TopicCreateTransaction, TokenCreateTransaction, ScheduleCreateTransaction, ContractCreateTransaction, FileCreateTransaction). |
name | The type of transaction |
max fee | The maximum transaction fee the client is willing to pay |
valid duration seconds | The seconds for which a submitted transaction is to be deemed valid beyond the start time. The transaction is invalid if consensusTimestamp is greater than transactionValidStart + valid_duration_seconds. |
node | The ID of the node that submitted the transaction to the network |
transfers | A list of the account IDs the crypto transfer occurred between and the amount that was transferred. A negative (-) sign indicates a debit to that account. The transfer list includes the transfers between the from account and to account, the transfer of the node fee, the transfer of the network fee, and the transfer of the service fee for that transaction. If the transaction was not processed, a network fee is still assessed. |
token transfers | The token ID, account, and amount that was transferred to by this account in this transaction. This will not be listed if it did not occur in the transaction |
assessed custom fees | The fees that were charged for a custom fee token transfer |
links.next | A hyperlink to the next page of responses |
Operator | Example | Description |
|---|---|---|
lt (less than) | /api/v1/transactions?account.id=lt:0.0.1000 | Returns account.id transactions less than 1,000 |
lte (less than or equal to) | /api/v1/transactions?account.id=lte:0.0.1000 | Returns account.id transactions less than or equal to 1,000 |
gt (greater than) | /api/v1/transactions?account.id=gt:0.0.1000 | Returns account.id transactions greater than 1,000 |
gte (greater than or equal to) | api/v1/transactions?account.id=gte:0.0.1000 | Returns account.id transactions greater than or equal to 1,000 |
order (order asc or desc values) | /api/v1/transactions?order=asc /api/v1/transactions?order=desc | Lists transactions in ascending order Lists transactions descending order |
Note: It is recommended that the account.id query should not select no more than 1000 accounts in a query. If the range specified in the query results in selecting more than 1000 accounts, the API will automatically only search for the first 1000 accounts that match the query in the database and return the transactions for those. For example, if you use
?account.id=gt:0.0.15000 or if you use?account.id=gt:0.0.15000&account.id=lt:0.0.30000, then the API will only return results or some 1000 accounts in this range that match the rest of the query filters.A single transaction can also be returned by specifying the transaction ID in the request. If a transaction was submitted to multiple nodes, the response will return entries for the successful transaction along with separate entries for the duplicate transaction(s). The "result" key indicates "success" for the node that processed the transaction and "DUPLICATE_TRANSACTION" for each additional node submission. Duplicate entries are still charged network fees.
Parameter | Description |
|---|---|
{transaction_ID} | A specific transaction can be returned by specifying a transaction ID |
Example Request | Description |
|---|---|
/api/v1/transactions/?account.id=0.0.1000 | Returns transaction for account ID 1,000 |
/api/v1/transactions?timestamp=1565779209.711927001 | Returns transactions at 1565779209 seconds and 711927001 nanoseconds |
/api/v1/transactions?result=fail | Returns all transactions that have failed |
/api/v1/transactions?account.id=0.0.13622&type=credit /api/v1/transactions?account.id=0.0.13622&type=debit | Returns all transactions that deposited into an account ID 0.0.13622 Returns all transactions that withdrew from account ID 0.0.13622
|
/api/v1/transactions?transactionType=cryptotransfer | Returns all cryptotransfer transactions |
get
/api/v1/transactions/{transactionId}
transaction by transaction ID
get
/api/v1/topics/{topicId}/messages/
topic messages
Response Item | Description |
|---|---|
consensus_timestamp | The consensus timestamp of the message in seconds.nanoseconds |
topic_id | The ID of the topic the message was submitted to |
message | The content of the message |
running_hash | The new running hash of the topic that received the message |
sequence_number | The sequence number of the message relative to all other messages for the same topic |
get
/api/v1/topics/{topicId}/messages/{sequenceNumber}
topic message by ID and sequence number
get
/api/v1/topics/messages/{consensusTimestamp}
topic messages by consensus timestamp
get
/api/v1/tokens
tokens
Response Item | Description |
|---|---|
token_Id | The ID of the token in x.y.z format |
symbol | The symbol of the token |
adminKey | The admin key for the token |
type | The type of token (fungible or non-fungible) |
Example Request | Description |
|---|---|
/api/v1/tokens?publickey=3c3d546321ff6f63d70 1d2ec5c277095874e19f4a235bee1e6bb19258bf362be | All tokens with matching admin key |
/api/v1/tokens?account.id=0.0.8 | All tokens for matching account |
/api/v1/tokens?token.id=gt:0.0.1001 | All tokens in range |
/api/v1/tokens?order=desc | All tokens in descending order of token.id |
/api/v1/tokens?limit=x | All tokens taking the first x number of tokens |
get
/api/v1/tokens/{tokenId}/balances
token balances
Response Item | Description |
|---|---|
timestamp | The timestamp of the recorded balances in seconds.nanoseconds |
balances | The balance of the tokens in those accounts |
account | The ID of the account that has the token balance |
balance | The balance of the token associated with the account |
Example Request | Description |
|---|---|
/api/v1/tokens/<token_id>/balances?order=asc | The balance of the token in ascending order |
/api/v1/tokens/<token_id>/balances?account.id=0.0.1000 | The balance of the token for account ID 0.0.1000 |
/api/v1/tokens/<token_id>/balances?account.balance=gt:1000 | The balance for the token greater than 1000 |
/api/v1/tokens/<token_id>/balances?timestamp=1566562500.040961001 | The token balances for the specified timestamp |
get
/api/v1/tokens/{tokenId}
token info
Response Item | Description |
|---|---|
admin_key | The token's admin key, if specified |
auto_renew_account | The auto renew account ID |
auto_renew_period | The period at which the auto renew account will be charged a renewal fee |
created_timestamp | The timestamp of when the token was created |
decimals | The number of decimal places a token is divisible by |
expiry_timestamp | The epoch second at which the token should expire |
freeze_default | Whether or not accounts created |
fee_schedule_key | The fee schedule key, if any |
freeze_key | The freeze key for the token, if specified |
initial_supply | The initial supply of the token |
kyc_key | The KYC key for the token, if specified |
modified_timestamp | The last time the token properties were modified |
name | The name of the token |
supply_key | The supply key for the token, if specified |
symbol | The token symbol |
token_id | The token ID |
total_supply | The total supply of the token |
treasury_account_id | The treasury account of the token |
type | whether a token is a fungible or non-fungible token |
wipe_key | The wipe key for the token, if specified |
custom_fees | The custom fee schedule for the token, if any |
pause_key | The pause key for a token, if specified |
pause_status | Whether or not the token is paused |
get
/api/v1/tokens/{tokenId}/nfts
NFTs
Response Item | Description |
|---|---|
account_id | The account ID of the account associated with the NFT |
created_timestamp | The timestamp of when the NFT was created |
deleted | Whether the token was deleted or not |
metadata | The meta data of the NFT |
modified_timestamp | The last time the token properties were modified |
serial_number | The serial number of the NFT |
token_id | The token ID of the NFT |
get
/api/v1/tokens/{tokenId}/nfts/{serialNumber}
NFT info
Response Item | Description |
|---|---|
account_id | The account ID of the account associated with the NFT |
created_timestamp | The timestamp of when the NFT was created |
deleted | Whether the token was deleted or not |
metadata | The meta data of the NFT |
modified_timestamp | The last time the token properties were modified |
serial_number | The serial number of the NFT |
token_id | The token ID of the NFT |
get
/api/v1/tokens/{tokenId}/nfts/{serialNumber}/transactions
NFT transaction history
Response Item | Description |
|---|---|
created_timestamp | The timestamp of the transaction |
id | The timestamp of the transaction |
receiver_account_id | The account that received the NFT |
sender_account_id | The account that sent the NFT |
type | The type of transaction |
token_id | The token ID of the NFT |
get
/api/v1/network/supply
network supply
get
/api/v1/schedules
schedule list
Response Item | Description |
|---|---|
schedules | List of schedules |
adminKey | The admin key on the schedule |
adminKey._type | The type of key |
adminKey.key | The admin public key |
consensus_timestamp | The consensus timestamp of when the schedule was created |
creator_account_id | The account ID of the creator of the schedule |
executed_timestamp | The timestamp at which the transaction that was scheduled was executed at |
memo | A string of characters associated with the memo if set |
payer_account_id | The account ID of the account paying for the execution of the transaction |
schedule_id | The ID of the schedule entity |
signatures | The list of keys that signed the transaction |
signatures.consensus_timestamp | The consensus timestamp at which the signature was added |
signatures.public_key_prefix | The signatures public key prefix |
signatures.signature | The signature of the key that signed the schedule transaction |
transaction_body | The transaction body of the transaction that was scheduled |
links.next | Hyperlink to the next page of results |
get
/api/v1/schedules/{scheduleId}
schedule transaction
Response Item | Description |
|---|---|
adminKey | The admin key on the schedule |
adminKey._type | The type of key |
adminKey.key | The admin public key |
consensus_timestamp | The consensus timestamp of when the schedule was created |
creator_account_id | The account ID of the creator of the schedule |
executed_timestamp | The timestamp at which the transaction that was scheduled was executed at |
memo | A string of characters associated with the memo if set |
payer_account_id | The account ID of the account paying for the execution of the transaction |
schedule_id | The ID of the schedule entity |
signatures | The list of keys that signed the transaction |
signatures.consensus_timestamp | The consensus timestamp at which the signature was added |
signatures.public_key_prefix | The signatures public key prefix |
signatures.signature | The signature of the key that signed the schedule transaction |
transaction_body | The transaction body of the transaction that was scheduled |
get
/api/v1/contracts
contracts
Response Item | Description |
|---|---|
admin_key | The admin key of the contract, if specified |
auto_renew_account | The account paying the auto renew fees, if set |
auto_renew_period | The period at which the contract auto renews |
bytecode | The bytecode of the contract |
contract_id | The contract ID |
created_timestamp | The timestamp the contract was created at |
deleted | Whether or not the contract is deleted |
evm_address | The EVM address of the contract |
expiration_timestamp | The timestamp of when the contract is set to expire |
file_id | The ID of the file that stored the contract bytecode |
max_automatic_token_associations | The number of automatic token association slots |
memo | The memo of the contract, if specified |
obtainer_id | The ID of the account or contract that will receive any remaining balance when the contract is deleted |
permanent_removal | Set to true when the system expires a contract |
proxy_account_id | The proxy account ID (disabled) |
solidity_address | The solidity address |
timestamp | The period for which the attributes are valid for |
get
/api/v1/contracts/{contractId}
contract by ID
get
/api/v1/contracts/results
List contract results from all contracts on the network
get
/api/v1/contracts/{contractId}/results
contract results
get
/api/v1/contracts/{contractId}/results/{timestamp}
contract result by timestamp
get
/api/v1/contracts/{contractIdOrAddress}/results/logs
contract logs
get
/api/v1/contracts/results/{transactionId}
contract result by transaction ID
get
/api/v1/contracts/results/logs
List contracts logs across many contracts on the network
get
/api/v1/contracts/results/{transactionIdOrHash}/actions
Get the contract actions from a contract on the network for a given transactionId or ethereum transaction hash
get
/api/v1/contracts/{contractIdOrAddress}/state
The contract current state from a contract on the network
get
/api/v1/blocks
List blocks
get
/api/v1/blocks/{hashOrNumber}
Get block by hash or number
The Hedera Mirror Node state proof alpha api provides the ability to cryptographically prove a transaction is valid on Hedera network. The request returns the content of the address book file, signature files, and record file that can be used to validate the transaction occurred on the Hedera network. The address book file contains the consensus node account IDs and their public key files. The signature files are of the supermajority consensus nodes that signed the record file the transaction is contained in.
get
/api/v1/transactions/{transactionId}/stateproof
Get stateproof information
Response Item | Description | Format |
|---|---|---|
record_file | The record file content for the specified transaction | base64 encoding |
signature_files | The signatures file content from the consensus nodes that signed the transaction | base64 encoding |
address_books | The address book file contents | base64 encoding |
Save the response to a json file and use the check-state-proof cli commands to confirm the validity of the transaction. You can find the instructions here.
get
/api/v1/network/supply
Get the network supply
get
/api/v1/network/fees
Get the network fees
get
/api/v1/network/exchangerate
Get the network exchange rate to estimate costs
get
/api/v1/network/nodes
Get the network address book nodes
get
/api/v1/network/stake
Get network stake information
Last modified 5d ago