Track Universal Transaction

Overview

Track the status of a universal transaction using the hash of the chain where it was originally submitted, whether that transaction started on Push Chain or an external chain.

This is useful for re-checking transaction progress, restoring status after a page refresh, polling from a backend, or tracking a transaction created in a different session.

Note: trackTransaction() can be used independently of sendTransaction(). You can pass any previously stored transaction hash and origin chain to resume tracking.

Track Universal Transaction

pushChainClient.universal.trackTransaction(txHash, {options}): Promise<UniversalTxResponse>

const response = await pushChainClient.universal.trackTransaction(
  '0xbd765a6b60da077eaa89a382cd59c0469a4eaabcaca2707d3e6dcdeafc497a39',
  {
    progressHook: (progress) => {
      console.log(`${progress.id}: ${progress.message}`);
    },
  }
);

TheseArgumentsare mandatory

Arguments	Type	Default	Description
txHash	string	-	Transaction hash or signature to track on the origin chain. Format depends on the chain where the transaction was originally submitted.
options.chain	CHAIN	CHAIN.PUSH_TESTNET_DONUT	The chain on which the transaction was submitted.
options.progressHook	(event: ProgressEvent) => void	undefined	Callback invoked at each tracking step showing progress. Progress hook follows the same structure as Send Universal Transaction - Progress Hook.
options.waitForCompletion	boolean	true	When true, waits for on-chain confirmation before resolving. When false, returns immediately after the first status check.

Advanced Arguments

Arguments	Type	Default	Description
options.advanced.pollingIntervalMs	number	2000	Milliseconds between polling attempts. Minimum: 500.
options.advanced.timeout	number	60000	Maximum milliseconds to wait before throwing a timeout error.
options.advanced.rpcUrls	Partial<Record<CHAIN, string[]>>	{}	Custom RPC URLs to use when querying status.

Returns `UniversalTxResponse` <object>

The returned UniversalTxResponse contains the latest resolved transaction state, including Push Chain execution details and external-chain details when applicable.

For the full response shape, see Send Universal Transaction - TxResponse object.

Live Playground

VIRTUAL NODE IDE

Copy playground link

Copy code

Using tx.wait() vs trackTransaction()

Both methods return identical TransactionReceipt objects. The difference is how you call them:

tx.wait() — Chain off sendTransaction()

Use when you just sent a transaction in the same session and want to wait inline:

const tx = await pushChainClient.universal.sendTransaction({
  to: '0x35B84d6848D16415177c64D64504663b998A6ab4',
  value: BigInt(1000),
});

// Inline wait — no separate hash lookup needed
const receipt = await tx.wait();
console.log('Confirmed at block:', receipt.blockNumber.toString());

trackTransaction() — Track any hash independently

Use when you have a hash from somewhere else — stored in a database, received from a user, or from a previous session:

// Works with any valid Push Chain tx hash
const response = await pushChainClient.universal.trackTransaction(
  '0xbd765a6b60da077eaa89a382cd59c0469a4eaabcaca2707d3e6dcdeafc497a39',
  {
    waitForCompletion: true,
    progressHook: (event) => console.log(`${event.id}: ${event.message}`),
  }
);

Error Handling

try {
  const response = await pushChainClient.universal.trackTransaction(txHash, {
    waitForCompletion: true,
    advanced: { timeout: 30000 },
  });

  // Get the receipt to check status
  const receipt = await response.wait();
  if (receipt.status === 0) {
    console.error('Transaction reverted on-chain');
  } else {
    console.log('Transaction confirmed:', response.hash);
  }
} catch (error) {
  if (error.message.includes('Timeout')) {
    console.error('Timed out — try increasing advanced.timeout');
  } else if (error.message.includes('Invalid')) {
    console.error('Invalid hash — must be 0x-prefixed 32-byte hex');
  } else {
    console.error('Tracking error:', error.message);
  }
}

Error	Cause	Fix
Invalid hash format	Not a valid 32-byte hex with 0x prefix	Hash must be 66 characters starting with 0x
Timeout	Transaction not confirmed within advanced.timeout	Increase timeout or check network congestion
Transaction not found	Hash doesn't exist on the specified chain	Verify hash and options.chain value
Network error	RPC unreachable	Supply custom URLs via advanced.rpcUrls

Next Steps

• Learn about signing messages with Sign Universal Message
• Explore helper functions in Utility Functions
• Build rich UIs with transaction tracking using the UI Kit
• Read blockchain state with Reading Blockchain State