Skip to main content

​
Overview

Transaction hints allow you to correlate traces with blockchain transactions. When you add a transaction hash to a trace, Mirador follows the transaction wherever it goes — across bridges, through different protocols, and onto other chains — providing full end-to-end visibility from your application code to on-chain settlement.

​
Adding Transaction Hints

trace.web3.evm.addTxHint('0x123abc...', 'ethereum');
Transaction hint methods require the Web3Plugin. See Plugins for setup.

​
With Details

Add optional context about the transaction: 
trace.web3.evm.addTxHint('0x123abc...', 'ethereum', 'Main swap transaction');
trace.web3.evm.addTxHint('0x456def...', 'polygon', 'Bridge to Polygon');

​
With Input Data

Capture the transaction’s calldata for deeper analysis: 
trace.web3.evm.addTxHint('0x123abc...', 'ethereum', {
  input: '0xa9059cbb000000000000000000000000...',
  details: 'ERC-20 transfer'
});
When input is provided, it is emitted as a "Tx input data" event via web3.evm.addTxInputData() — it is not stored in the hint. You can also call trace.web3.evm.addTxInputData(calldata) directly for the same effect.

​
From a Transaction Object

Use web3.evm.addTx() to automatically extract the hash, input data, and chain from a transaction-like object: 
// Works with ethers, viem, or any object with { hash, data/input, chainId }
const tx = await signer.sendTransaction(txData);
trace.web3.evm.addTx(tx);

​
Supported Chains

ChainValue
Ethereum'ethereum'
Polygon'polygon'
Arbitrum'arbitrum'
Base'base'
Optimism'optimism'
BSC'bsc'
import type { ChainName } from '@miradorlabs/web-sdk';

const chain: ChainName = 'ethereum';
trace.web3.evm.addTxHint(txHash, chain);

​
Multiple Transaction Hints

A single trace can include multiple transaction hints. This is useful for complex operations that span multiple transactions. Mirador automatically follows each transaction across chains, bridges, and protocols, so you get full visibility into the entire flow: 
const trace = client.trace({ name: 'CrossChainSwap' })
  .addEvent('swap_initiated');

// First transaction on Ethereum — Mirador follows it through the DEX
trace.web3.evm.addTxHint(ethTxHash, 'ethereum', 'Swap ETH to USDC');

// Bridge transaction — Mirador tracks it as it crosses to Polygon
trace.web3.evm.addTxHint(bridgeTxHash, 'ethereum', 'Bridge to Polygon');

// Final transaction on Polygon — full end-to-end trace across chains
trace.web3.evm.addTxHint(polygonTxHash, 'polygon', 'Receive on Polygon');
For Safe multisig message and transaction hints, see Safe Multisig Integration.

​
Complete Example

import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key', {
  plugins: [Web3Plugin()]
});

async function executeSwap(params: SwapParams) {
  const trace = client.trace({ name: 'TokenSwap' })
    .addAttributes({
      inputToken: params.inputToken,
      outputToken: params.outputToken,
      inputAmount: params.amount,
      userAddress: params.userAddress
    })
    .addTags(['swap', 'dex', params.chain])
    .addEvent('swap_initiated');

  try {
    // User signs transaction
    trace.addEvent('user_signing');
    const tx = await wallet.sendTransaction(swapTx);

    trace.addEvent('transaction_sent', { txHash: tx.hash });

    // Add transaction hint with input data for correlation
    trace.web3.evm.addTxHint(tx.hash, params.chain, {
      input: swapTx.data,
      details: 'Swap transaction'
    });

    // Wait for confirmation
    const receipt = await tx.wait();

    trace.addEvent('transaction_confirmed', {
      blockNumber: receipt.blockNumber,
      gasUsed: receipt.gasUsed.toString()
    });

  } catch (error) {
    trace.addEvent('swap_failed', { error: error.message });
  }
}

​
Using sendTransaction

For a more integrated approach, use sendTransaction() which automatically captures tx hints and errors: 
import { Client, Web3Plugin } from '@miradorlabs/web-sdk';

const client = new Client('your-api-key', {
  plugins: [Web3Plugin({ provider: window.ethereum })]
});

async function executeSwap(params: SwapParams) {
  const trace = client.trace({ name: 'TokenSwap' })
    .addAttributes({
      inputToken: params.inputToken,
      outputToken: params.outputToken,
      inputAmount: params.amount,
    })
    .addTags(['swap', 'dex']);

  try {
    // sendTransaction handles tx hints, events, and error capture
    const txHash = await trace.web3.evm.sendTransaction({
      from: params.userAddress,
      to: params.contractAddress,
      data: params.calldata,
      chainId: 1
    });

    trace.addEvent('transaction_confirmed');
  } catch (error) {
    // Error is already captured in the trace as tx:error
    console.error('Swap failed:', error.message);
  }
}

​
Method Signatures

​
web3.evm.addTxHint

trace.web3.evm.addTxHint(
  txHash: string,
  chain: ChainName,
  options?: string | TxHintOptions
): Trace
ParameterTypeRequiredDescription
txHashstringYesThe transaction hash
chainChainNameYesThe blockchain network
optionsstring | TxHintOptionsNoDescription string or structured options

​
web3.evm.addTx

trace.web3.evm.addTx(tx: TransactionLike, chain?: ChainName): Trace
ParameterTypeRequiredDescription
txTransactionLikeYesTransaction object (hash, data/input, chainId)
chainChainNameNoOverride chain (auto-detected if omitted)

​
web3.evm.addTxInputData

trace.web3.evm.addTxInputData(inputData: string): Trace
ParameterTypeRequiredDescription
inputDatastringYesHex-encoded transaction input data (calldata)

​
web3.evm.sendTransaction

trace.web3.evm.sendTransaction(
  tx: TransactionRequest
): Promise<string>
ParameterTypeRequiredDescription
txTransactionRequestYesTransaction parameters

​
Best Practices

​
Add Hints as Soon as You Have the Hash

Don’t wait for confirmation to add the hint: 
const tx = await wallet.sendTransaction(txData);

// Add hint immediately after sending
trace.web3.evm.addTxHint(tx.hash, 'ethereum');

// Then wait for confirmation
await tx.wait();

​
Include Descriptive Details

When dealing with multiple transactions, details help identify each one: 
trace.web3.evm.addTxHint(approveTx, 'ethereum', 'Token approval');
trace.web3.evm.addTxHint(swapTx, 'ethereum', 'Swap execution');

​
Match Chain to Transaction

Always use the correct chain for the transaction: 
// Correct
trace.web3.evm.addTxHint(polygonTxHash, 'polygon');

// Incorrect - wrong chain
trace.web3.evm.addTxHint(polygonTxHash, 'ethereum');

​
Next Steps

EIP-1193 Provider

Auto-capture transactions with MiradorProvider

Traces

Learn about trace lifecycle and flushing

Transaction Tracking Example

See a complete implementation