A Guide to Hedera's Mirror Node API.

Blockchain technologies and the web3 space have seen tremendous growth in recent years. Many people believe that the blockchain has the potential to take power away from corporate entities and place it in the hands of individuals, allowing them to control their data online.

This shared thought, belief, and vision have resulted in the development of various blockchains such as Bitcoin, Ethereum, and Solana. While they remain the most popular blockchain technologies at the moment, there are other companies building blockchain technologies to truly give power back to the individual, one of which is Hedera.

So, what is Hedera?

Hedera is a fully open source, proof-of-stake, public network and governing body for building and deploying decentralized applications. It offers developers three primary services: Solidity-based smart contracts, consensus, and token services. Hedera is unique in that it is incredibly fast, energy-efficient (carbon negative), and secure — these advantages can be attributed to its underlying hashgraph consensus algorithm. - hedera.com

In layman's terms, the Hedera network's goal is to give every individual the ability to create and control what happens in their online space without exchanging anything in return like your time. The network is more than just a platform for processing transactions and developing smart contracts; it has a burning desire to assist you in making your digital world what you want it to be.

Now that you understand what Hedera is all about, what is the Mirror Node API?.

The Mirror Node API

Hedera's Mirror Node API is like a diary or database to put it more into perspective, that contains the history of all transactions that occurred on the mainnet, testnet, and previewnet. In case you are unfamiliar with these terms, here's what they mean:

• Mainnet (main network): The mainnet is Hedera's fully developed, stable, and deployed network. It is the operational portion of the network.
• Testnet (test Network): A testnet is a network that allows developers to run various experiments without risking actual funds (or $HBAR in this case) or disrupting the actual network.
• Previewnet (preview network): Hedera developers wanted to be able to test new features before they were deployed to the mainnet or testnet. To that end, Hedera established a preview network where developers could see new features and make contributions/corrections before deployed to the main chains.

The Mirror Node API for each network (mainnet, testnet, and previewnet) consists of nine different endpoints for retrieving various information, which are as follows:

• Accounts.
• Balances.
• Blocks.
• Contracts.
• Networks.
• Schedules.
• Tokens.
• Topics.
• Transactions.

In this article, we will go over the Mirror Node API's Accounts, Balances, Networks, and Transactions endpoints. Because the Mirror Node API is used to retrieve information, all API calls must be in the form of a GET request. The tutorial will also query the mainnet network because that is where the real transactions take place.

To easily code along and understand how the APIs work, you need:

• Basic knowledge of JavaScript
• Understanding of how to call APIs using 'fetch' from the 'node-fetch' package. You can learn more about the 'node-fetch' package here.

Accounts Endpoint.

Mirror Node accounts API fetches information relating to users' accounts with the accounts endpoint on the network. The information available with this API are:

• Lists of all the accounts on the network.
• Information about a particular account.
• Crypto allowances available on an account.
• Fungible token allowances avaiable on an account.
• NFTs available on an account.

List of all accounts on the network.

This endpoint returns data on all accounts created on the Hedera network. Make a request to fetch accounts using the code below.

Code.

Endpoint: /api/v1/accounts

import fetch from "node-fetch";

let url = "https://mainnet-public.mirrornode.hedera.com/api/v1/accounts"

const response = await fetch(url)
const json_reponse = await response.json();

console.log(json_reponse)

Response.

{
      account: '0.0.1',
      alias: null,
      auto_renew_period: 17775,
      balance: [Object],
      decline_reward: true,
      deleted: false,
      ethereum_nonce: 0,
      evm_address: null,
      expiry_timestamp: null,
      key: [Object],
      max_automatic_token_associations: 0,
      memo: '',
      receiver_sig_required: null,
      staked_account_id: null,
      staked_node_id: 10,
      stake_period_start: '1658966400.000000000'
    }

The API responds with the first 25 accounts and an API link to the next 25 accounts. The above response displays key-value pairs for an individual account. Each response includes the account id, which uniquely identifies the user.

Information about a particular account.

You can request information about a specific account by using the account ID. That is exactly what the code below does.

Code

Endpoint: /api/v1/accounts?account.id={some account number}

import fetch from "node-fetch";

let url = "https://mainnet-public.mirrornode.hedera.com/api/v1/accounts?account.id=0.0.1000"

const response = await fetch(url)
const json_reponse = await response.json();

const account_balance = json_reponse["accounts"][0]["balance"]["balance"]

console.log(account_balance+ " Tiny HBARS")

A parameter account.id with the value '0.0.1000', a user's account number, is attached to the URL. This API returns specific information about the user's account. The code above simply indexes the response's account balance. The end result?

Response.

236804813479 Tiny HBARS

The user with the account ID '0.0.1000' has a total of 236804813479 HBARS.

Crypto Allowances on an Account

Allowances on Hedera allow users to grant other users access to their wallet funds. Similar to a regular bank account, but with more than one signatory. In this case, the owner of the account authorizes the spender to use a certain amount.

The code below is requesting information about the crypto allowances on an account with the ID '1001'.

Code.

Endpoint: /api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/crypto

async function getCryptoAllowances(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/accounts/1001/allowances/crypto")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

console.log(await getCryptoAllowances())

Response.

{ allowances: [], links: { next: null } }

This user has not yet approved any allowance for any spender.

Fungible Token Allowances on an Account

You can also use the accounts endpoint to view a user's fungible token allowances. For an example, see the code below.

Code.

Endpoint: /api/v1/accounts/{idOrAliasOrEvmAddress}/allowances/tokens

async function getTokenAllowances(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/accounts/8/allowances/tokens")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

console.log(await getTokenAllowances())

This API requests the token allowances for the user with account id 8. The end result?

Response.

{ allowances: [], links: { next: null } }

This user does not have any token allowances.

NFTs Available on the Account.

This accounts endpoint also provides information about the NFTs that a user has access to.

Code.

Endpoint: /api/v1/accounts/{idOrAliasOrEvmAddress}/nfts

async function getNFTs(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/accounts/1000/nfts")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

console.log(await getNfts())

Response.

{ nfts: [], links: { next: null } }

The above result indicates that the user with account ID '1000' does not have NFTs.

Balances Endpoint.

The balances endpoint is a straightforward endpoint that returns an account's balance. The balance here refers to the number of tiny hbars in the account at any given time. The code below uses this API to retrieve the balance of an account with the ID '0.0.1001'.

Code.

Endpoint: /api/v1/balances

async function getBalances(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/balances?account.id=1001")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

console.log(await getBalances())

Response.

{
  timestamp: '1661265000.265552000',
  balances: [ { account: '0.0.1001', balance: 571916653506, tokens: [Array] } ],
  links: { next: null }
}

The API response displays the time of the request, the account id, the balance, and the available tokens. At the time of this request, this user had a balance of 571916653506 tiny HBARs.

Networks Endpoint.

The network endpoint provides information about the current state of the Hedera network. With this endpoint, you can fetch:

• The network's exchange rate.
• The network's fees.
• The network's nodes.
• The network's stake
• The network's supply.

The Network's Exchange Rate

This endpoint returns the network's current exchange rate value in cents, hbars, and the network's rate expiration time in Unix epoch (the number of seconds that have elapsed since January 1, 1970). It also returns the next rates as well as the expiration time. Send a request to the network's exchange rate using the code below.

Code.

Endpoint: /api/v1/network/exchangerate

async function getExchangeRate(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/network/exchangerate")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}


console.log(await getExchangeRate())

Response.

{
  current_rate: {
    cent_equivalent: 198916,
    expiration_time: 1661266800,
    hbar_equivalent: 30000
  },
  next_rate: {
    cent_equivalent: 201309,
    expiration_time: 1661270400,
    hbar_equivalent: 30000
  },
  timestamp: '1661263273.013587691'
}

The response returned the current and next rates, as well as the expiration and current times, all in Unix epoch.

The Network's Fees

The network fees endpoint returns the estimated gas fees in tiny hbars at a given point in time.

• Call a contract.
• Create a contract.
• Perform an ethereum transaction.

To access the network fees, use the code below.

Code.

Endpoint: /api/v1/network/fees

async function getNetworkFees(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/network/fees")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

console.log(await getNetworkFees())

Response.

{
  fees: [
    { gas: 127, transaction_type: 'ContractCall' },      
    { gas: 127, transaction_type: 'ContractCreate' },    
    { gas: 127, transaction_type: 'EthereumTransaction' }
  ],
  timestamp: '1660671750.212501966'
}

According to the response, carrying out all three transactions would cost 127 tiny hbars each.

The Networks's Nodes.

In the context of blockchain, a node is a computer that runs the blockchain software and stores a history of all transactions that have occurred on the network. The node endpoint of the network returns a list of all the nodes running Hedera's blockchain software.

To get a list of all network nodes, use the code below.

Code.

Endpoint: /api/v1/network/nodes

async function getNetworkNodes(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/network/nodes")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

console.log(await getNetworkNodes())

Response.

{
      description: '',
      file_id: '0.0.102',
      max_stake: 192307692307692320,
      memo: '',
      min_stake: 96153846153846160,
      node_id: 2,
      node_account_id: '0.0.5',
      node_cert_hash: '0xe55c559975c1c9285c5262d6c94262287e5d501c66a0c770f0c9a88f7234e0435c5643e03664eb9c8ce2d9f94de717ec',
      public_key: '0x308201a2300d06092a864886f70d01010105000382018f003082018a0282018100b2ccac65ad0fc7645a817bfabc487ad7e41311e7a3198b37fb842d84c395b3f67d6bd848f10c6f03c290e8f7daa8d001a8441dc352a19160a3193e68b82edf19ae67693a9a33d4cb87e789a1070715515ea772caa8b86a569b91c5450835d9c354f0dacec97fe77091b45b147698b7f8601422dcd2261e928de4dac9c42dcbafdf96c07233ba3027076f37c969e8ed30b6b5d8f5034be7d92c596f8be861e51fcc3a242bf9d8be9e2a9e8e0f155ebcff23effa7cd57c10542811d80776c9585526fdb0eaa34ee1955d51119390fe873e4c04dedd29165884b98b46308788ae7fc4d4aa4a8fc9bc2674ba321493b624455ad410c1de71bc95d1d91fa0f201418a795e309eaf297b699bf27c9fa2763cd59ceb021e16b8200c1060f2817fd83cfc767183489461e3599291b380d6e939baa4b19232a6a272dde651f8046fdc34db276a777d6fb2bec3255b2cc244b4af566b105f30c6506ddae0eb3deddcf947bcb9c60e000984f3b4a8c6c4ed4bf90bc1932b7f94dc3ae6b360008eb902040f9b0203010001',
      reward_rate_start: 0,
      service_endpoints: [Array],
      stake: 0,
      stake_not_rewarded: 0,
      stake_rewarded: 57349500000000,
      stake_total: 0,
      staking_period: [Object],
      timestamp: [Object]
    }

The response above gives information about a node such as its ID, public key, stake, stake not rewarded, stake rewarded, among others.

The Network's Stake

Staking is the process of storing your funds in a blockchain for a set period of time in order to facilitate token exchange on the network. Users who stake their funds on a blockchain can earn rewards. The rewards are usually a percentage of the transaction fees.

To obtain stake information for Hedera's network, use the code below.

Code.

Endpoint: api/v1/network/stake

async function getNetworkStake(){

    try {
        const response = await fetch("https://testnet.mirrornode.hedera.com/api/v1/network/stake")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

console.log(await getNetworkStake())

Response.

{
  max_staking_reward_rate_per_hbar: 0,
  node_reward_fee_fraction: 0,
  stake_total: 0,
  staking_period: { from: '1661212800.000000000', to: '1661299200.000000000' },
  staking_period_duration: 0,
  staking_periods_stored: 0,
  staking_reward_fee_fraction: 0,
  staking_reward_rate: 0,
  staking_start_threshold: 0
}

The response contains information about the total stake on the network, such as the maximum staking reward rate per hbar, total stake on the network, and staking period.

Note: The zeros for the various staking values are due to the response coming from the testnet API. The reason for using the testnet rather than the mainnet, as previously stated, is that it returned 'undefined' as its response.

The Network's Supply

The supply of a network refers to the total number of tokens in circulation at any given time. A token is a virtual currency used for transactions and payments on a blockchain network.

To find the supply of tokens on Hedera, send a request to the network's endpoint. To find out, use the code below.

Code.

Endpoint: /api/v1/network/supply

async function getNetworkSupply(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/network/supply")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

Response.

{
  released_supply: '2281892368795344266',
  timestamp: '1661282100.971360000',
  total_supply: '5000000000000000000'
}

The API response displays the number of tokens currently in circulation as well as the total number of tokens the network will ever have.

Transactions Endpoint.

The transactions endpoint provides data on successful and failed transactions on the Hedera network. With this endpoint you can find out the:

• List of transactions on the network.
• A particular transaction using its transaction ID.
• The transaction's state proof

List of Transactions on the Network.

Using the transactions endpoint, you can fetch the list of transactions on the Hedera network. Use the code below to fetch the transactions.

Code.

Endpoint: /api/v1/transactions

async function getTransactions(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/transactions")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}

console.log(await getTransactions())

Response.

{
      bytes: null,
      charged_tx_fee: 254623,
      consensus_timestamp: '1661282256.222567283',
      entity_id: '0.0.120438',
      max_fee: '4000000',
      memo_base64: '',
      name: 'CONSENSUSSUBMITMESSAGE',
      node: '0.0.3',
      nonce: 0,
      parent_consensus_timestamp: null,
      result: 'SUCCESS',
      scheduled: false,
      transaction_hash: 'p1NxpoQQeEHwZMrWeTmJiubyB6YOvYkb/J/lOocolWwzQX3fNRh/MGI0oyB2JvA1',
      transaction_id: '0.0.41104-1661282245-644008944',
      transfers: [Array],
      valid_duration_seconds: '120',
      valid_start_timestamp: '1661282245.644008944'
    }

The API responds with transaction details such as the transaction fee, hash, id, result, and name, among others.

Particular Transaction Using Its Transaction ID

Using the transaction ID, you can obtain information about a transaction. The following code retrieves information about the transaction with the ID '0.0.34776-1661282245-906570926'. The transaction ID takes the format "shard.realm.num-sss-nnn". The:

• "shard.realm.num" refers to the users account ID.
• "sss" refers to the time in seconds.
• "nnn" refers to the time in nanoseconds.

Code.

Endpoint: /api/v1/transaction/{transactionId}

async function getTransactionWithId(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/transactions/0.0.34776-1661282245-906570926?nonce=0")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}


console.log(await getTransactionWithId())

Response.

transactions: [
    {
      bytes: null,
      charged_tx_fee: 178785,
      consensus_timestamp: '1661282256.328057987',
      entity_id: '0.0.145780',
      max_fee: '200000000',
      memo_base64: '',
      name: 'CONSENSUSSUBMITMESSAGE',
      node: '0.0.14',
      nonce: 0,
      parent_consensus_timestamp: null,
      result: 'SUCCESS',
      scheduled: false,
      transaction_hash: 'ds1CHgOa+9+IxNiuXNwgwba+Y4xima3Mw4s1JTiKyufRza/VCVyEgZMerGxKy3rb',
      transaction_id: '0.0.34776-1661282245-906570926',
      transfers: [Array],
      valid_duration_seconds: '120',
      valid_start_timestamp: '1661282245.906570926'
    }
  ]

This response indicates that the transaction cost 178785 tiny hbars, took place on Tuesday, August 23, 2022, 7:17:25.906 PM GMT, and was successful.

Transactions Stateproof.

What is a stateproof?

A state proof is a cryptographically secure and portable data structure that is optionally returned as part of a query response. A state proof proves that the returned data is valid, that is, is part of the state of Hedera. Simply put, it allows any actor presented with the data and the corresponding state proof to be able to verify the data. - Hedera.com

State proofs aid in verifying that information on the Hedera network is accurate. Use the code below to obtain the state proof for the transaction queried in the previous section.

Code.

Endpoint: /api/v1/transaction/{transactionId}/stateproof

async function getTransactionStateproof(){

    try {
        const response = await fetch("https://mainnet-public.mirrornode.hedera.com/api/v1/transactions/0.0.34776-1661282245-906570926/stateproof")

        if (!response.ok) {
            throw new Error(`Error status ${response.status}`)
        }

        const result = await response.json()
        return result
    } catch (err) {
        console.log(err)
    }
}


console.log(await getTransactionStateproof())

Response.

The response is lengthy (covers 30 pages in a word document), and the full version is available here. It contains a long code that serves as a transaction validator.

Recap.

In this article, we covered:

• Hedera's Mission.
• The Mirror Node API.
• Types of Mirror Node API.
• The Accounts Endpoint.
• The Balances Endpoint.
• The Network Endpoint
• The Transactions Endpoint.

To learn more about the network, visit Hedera's documentation. You can also get regular updates on the network status by following on Twitter and LinkedIn.

Thank you for reading this blog post. if you liked it, please share it.

You can follow me on Twitter and LinkedIn, and please leave a comment below if you have any questions. For the time being, bye.

Image Cover: Hedera.com