React hooks for reading data from the Hiero / Hedera network via the Mirror Node REST API.
- React hooks — accounts, transactions, tokens, NFTs, files, smart contracts, and HCS topics
- TypeScript — full type safety and autocompletion on every hook
- Mirror Node — read Hiero data without running a node or holding a private key
- Lightweight — zero production dependencies
Hedera runs a public read API called the Mirror Node. It indexes everything on the network — every transaction, token transfer, and HCS message — and exposes it over REST.
This library wraps those endpoints in React hooks so you can display blockchain data without writing any fetch logic yourself. It is read-only: you can display balances, transactions, and token data, but cannot send transactions or sign anything.
Your component
└── calls useAccount('0.0.1234')
└── reads mirror URL from HieroProvider
└── GET https://testnet.mirrornode.hedera.com/api/v1/accounts/0.0.1234
└── returns { balance, loading, error }
npm install hiero-reactReact 18 or higher is required as a peer dependency.
import { HieroProvider } from 'hiero-react';
export default function App() {
return (
<HieroProvider network="testnet">
<YourApp />
</HieroProvider>
);
}import { useAccount } from 'hiero-react';
function Wallet({ accountId }: { accountId: string }) {
const { balance, loading, error } = useAccount(accountId);
if (loading) return <p>Loading...</p>;
if (error) return <p>Error: {error.message}</p>;
return <p>Balance: {balance} HBAR</p>;
}<HieroProvider network="testnet"> // Testnet (development)
<HieroProvider network="mainnet"> // Mainnet (production)
<HieroProvider network="previewnet"> // Previewnet (experimental)<HieroProvider network="mainnet" mirrorNodeUrl="https://your-mirror-node.com">Access the current network configuration. Must be inside HieroProvider.
const { network, mirrorNodeUrl } = useHiero();Fetch the HBAR balance for an account.
const { accountId, balance, loading, error } = useAccount('0.0.1234');Fetch recent transactions for an account.
const { transactions, loading, error, refetch } = useTransactions('0.0.1234', 20);Each Transaction has: transactionId, type, result, consensusTimestamp, transfers[].
Fetch fungible tokens held by an account.
const { tokens, loading, error } = useTokens('0.0.1234');
// tokens: Array<{ tokenId, symbol, balance, decimals }>Fetch NFTs held by an account. Metadata is automatically decoded from base64.
const { nfts, loading, error } = useNFTs('0.0.1234');
// nfts: Array<{ tokenId, serialNumber, metadata }>Fetch metadata and raw contents of a file stored on the Hedera file service.
const { file, loading, error, refetch } = useFile('0.0.101');
// file: { fileId, size, expirationTimestamp, deleted, memo, keys[] }
const { contents, loading, error } = useFileContents('0.0.101');
// contents: { fileId, content (base64), encoding }Fetch metadata, historical call results, and emitted event logs for a smart contract.
const { contract, loading, error } = useContract('0.0.2001');
// contract: { contractId, evmAddress, fileId, memo, adminKey, deleted, bytecodeHash, ... }
const { calls, loading, error } = useContractCalls('0.0.2001');
// calls: Array<{ result, gasUsed, errorMessage }>
const { logs, loading, error } = useContractLogs('0.0.2001');
// logs: Array<{ address, blockHash, blockNumber, data, topics[], transactionHash }>Fetch metadata and messages for a Hedera Consensus Service (HCS) topic. Messages are automatically decoded from base64.
const { topic, loading, error } = useTopic('0.0.2');
// topic: { topicId, memo, runningHash, sequenceNumber, adminKey, submitKey, deleted, ... }
const { messages, loading, error } = useTopicMessages('0.0.2', {
limit: 25,
sequenceNumberGte: 100,
sequenceNumberLte: 200,
});
// messages: Array<{ consensusTimestamp, message, sequenceNumber, runningHash, topicId }>This example demonstrates all available hooks against real testnet data. Topic 0.0.2 and file 0.0.101 are Hedera system resources that always exist on testnet — no setup required.
import {
HieroProvider,
useAccount,
useTopic,
useTopicMessages,
useFile,
useFileContents,
useContract,
useContractLogs,
} from 'hiero-react';
function HookTests() {
const { balance, loading: accountLoading } = useAccount('0.0.8241384');
const { topic } = useTopic('0.0.2');
const { messages } = useTopicMessages('0.0.2', { limit: 3 });
const { file } = useFile('0.0.101');
const { contents } = useFileContents('0.0.101');
const { contract } = useContract('0.0.8071440');
const { logs } = useContractLogs('0.0.8071440');
return (
<div style={{ padding: 32, fontFamily: 'monospace', display: 'flex', flexDirection: 'column', gap: 24 }}>
<section>
<h2>useAccount</h2>
{accountLoading ? <p>Loading...</p> : <p>Balance: {balance} HBAR</p>}
</section>
<section>
<h2>useTopic (0.0.2)</h2>
{topic ? (
<p>Sequence number: {topic.sequenceNumber} | Memo: {topic.memo}</p>
) : <p>Loading...</p>}
</section>
<section>
<h2>useTopicMessages (0.0.2)</h2>
{messages.length === 0 ? <p>Loading...</p> : messages.map(m => (
<div key={m.sequenceNumber}>
#{m.sequenceNumber} — {m.consensusTimestamp}
</div>
))}
</section>
<section>
<h2>useFile (0.0.101)</h2>
{file ? (
<p>Size: {file.size} bytes | Deleted: {String(file.deleted)}</p>
) : <p>Loading...</p>}
</section>
<section>
<h2>useFileContents (0.0.101)</h2>
{contents ? (
<p>Content length: {contents.content.length} chars (base64)</p>
) : <p>Loading...</p>}
</section>
<section>
<h2>useContract</h2>
{contract ? (
<p>EVM address: {contract.evmAddress} | Deleted: {String(contract.deleted)}</p>
) : <p>Loading...</p>}
</section>
<section>
<h2>useContractLogs</h2>
{logs.length === 0 ? <p>No logs</p> : logs.map((log, i) => (
<div key={i}>
Block {log.blockNumber} — {log.address}
</div>
))}
</section>
</div>
);
}
export default function App() {
return (
<HieroProvider network="testnet">
<HookTests />
</HieroProvider>
);
}npm install # install dependencies
npm run build # compile TypeScript → dist/
npm test # run test suite
npm run lint # check code style
npm run typecheck # check types without building
npm run dev # build and watch for changesSee CONTRIBUTING.md for the full guide.
All commits must be:
- GPG signed (
git config commit.gpgsign true) - Include a DCO sign-off (
git commit -s)
Apache-2.0 — see LICENSE for details.