Querying Data on Hedera: SDK vs Mirror Node REST API

By Ed Marquez

When you are building applications on Hedera, a key action you will need to do is querying entity data, such as account balances or transaction history.

Developers have two main ways to query network data:

1. Using the Hiero SDKs, which interact with the consensus nodes
2. [Recommended] Using the Mirror Node REST API, which provides read access to historical and current data

Both options work, but they serve different purposes. Let’s look at how each works and why the Mirror Node REST API is the preferred method for production applications.

Option 1: Querying Data with the Hiero SDK

The Hiero SDKs provide direct access to Hedera’s consensus nodes. You can use queries such as AccountBalanceQuery or AccountInfoQuery to check balances or retrieve account details.

Here is an example in

import { Client, AccountBalanceQuery } from "@hiero-ledger/sdk";

const client = Client.forTestnet().setOperator(process.env.MY_ACCOUNT_ID, process.env.MY_PRIVATE_KEY);

const balance = await new AccountBalanceQuery()
  .setAccountId("0.0.800")
  .execute(client);

console.log(`Account balance: ${balance.hbars.toString()}`);

This type of query goes directly to a consensus node, which processes and returns the latest balance available from that node’s state.

Why SDK queries are not ideal

• Performance impact: Consensus nodes are optimized to validate and process transactions, not to handle large volumes of read requests.
• Consensus Assurance: SDK queries return data from a single consensus node’s local state and are not validated by network-wide consensus.
• Deprecations: Token balance queries through consensus nodes were deprecated with HIP-367, and future SDK updates may limit or remove some balance query functions.
• Complexity and Cost: You need to sign and configure your client properly for each network environment. Also, while some SDK queries are currently free, these are subject to change in the future.

For these reasons, developers should begin transitioning to the Mirror Node REST API for all read operations.

Option 2: Querying Data with the Mirror Node REST API (Recommended)

The Mirror Node REST API is the recommended and future-proof method for querying data on Hedera. Mirror nodes store and serve network data, including balances, transactions, tokens, topics, and more. These queries source data that has been finalized, signed, and verified across a majority of consensus nodes, providing strong assurances of accuracy and immutability.

Unlike consensus nodes, mirror nodes are optimized for reading and indexing data. They provide an efficient, low-cost way to perform queries, are easy to integrate with, and scale well for production applications.

While Hedera offers a free, Hedera-hosted mirror node suitable for development and testing, production applications should use commercial mirror node providers such as Arkhia, Hgraph, LinkPool or Validation Cloud, which offer paid plans with a large number of queries included, dedicated infrastructure, high throughput, and service-level guarantees.

Querying an Account Balance from the Mirror Node API

Mirror node queries are simple HTTP requests, which makes them easy to use from any language or environment. Below are a few examples:

Example 1: JavaScript with fetch

const accountId = "0.0.800";
const url = `https://testnet.mirrornode.hedera.com/api/v1/balances?account.id=${accountId}`;

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

console.log("Account balance:", data.balances[0].balance, "tinybars");

Example 2: curl

Enter the following command in your terminal:

curl "https://testnet.mirrornode.hedera.com/api/v1/balances?account.id=0.0.800"

Example 3: Browser

Open this URL directly in your browser. You will see a JSON response that includes the account ID, the HBAR balance (in tinybars), and any token balances if they exist.

https://testnet.mirrornode.hedera.com/api/v1/balances?account.id=0.0.800

For more examples with other endpoints and additional query parameters, check out this article on How to Look Up Transaction History on Hedera Using Mirror Nodes.

Understanding Mirror Node Balance Timing

Mirror nodes receive balance files from the Hedera network periodically. These files contain snapshots of all account balances at a specific timestamp. When you query a mirror node, the result represents the most recent snapshot available.

If a transaction has just completed, there may be a small delay before that balance appears in the mirror node data. This delay depends on network conditions but is typically short enough for most application needs.

If your application requires real-time confirmation of a balance change (for example, right after a transaction submission), you can still use an SDK query as a temporary fallback. However, for the majority of use cases, relying on the mirror node is more efficient and scalable.

How to Prepare Your Code for the Future

To make your applications future-proof:

1. Abstract balance queries: Write your code so that your balance-fetching logic is separate from business logic. This allows you to switch easily between SDK and REST API methods.
2. Start migrating: Begin using the Mirror Node REST API in testing and production environments.
3. Avoid assumptions: Remember that mirror node balances represent snapshots. Always confirm timing expectations when displaying balances in UI or reports.
4. Test across networks: Use https://testnet.mirrornode.hedera.com during development, and switch to https://mainnet.mirrornode.hedera.com for production.
5. Remember that the free, Hedera-hosted mirror node is intended to support testing and development. Use a commercial mirror node provider once you deploy your application in production.

Try It Yourself: Developer Playground

The 👉 Hedera Developer Playground 👈 gives you a simple, interactive way to experiment with Mirror Node queries.

Try the example above 👆 and see how you can create a new Hedera account, create a new fungible token managed by that new account, and then query the account balances with the Mirror Node REST API.

It is a great way to get familiar with the REST API and see how responses look in real time.

Summary

Key Takeaways for Devs

• Use the Mirror Node REST API for querying balances and data
• Balances reflect snapshot timing, which provides the perfect level of freshness for applications like wallets, explorers, analytics, and more
• Migrate away from SDK-based balance queries to avoid disruptions with any future SDK changes

Use the Developer Playground to try Mirror Node queries today!

Join the Hedera community!

• X
• Discord
• Telegram
• LinkedIn
• YouTube
• StackOverflow
• Medium
• Reddit
• Instagram

Querying Data on Hedera: SDK vs Mirror Node REST API was originally published in Hedera Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.