Transaction Hints

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

Chain	Value	Chain ID
Ethereum	`'ethereum'`	1
Optimism	`'optimism'`	10
BSC	`'bsc'`	56
Polygon	`'polygon'`	137
Base	`'base'`	8453
Arbitrum	`'arbitrum'`	42161
HyperEVM	`'hyperevm'`	999

import type { ChainName } from '@miradorlabs/web-sdk';

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

Tracking a transaction on Solana or Canton? Both live outside the Chain enum (no numeric chain ID). Use web3.solana.addTxHint(signature) or web3.canton.addTxHint(updateId) instead — no chain argument required.

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

Parameter	Type	Required	Description
`txHash`	`string`	Yes	The transaction hash
`chain`	`ChainName`	Yes	The blockchain network
`options`	`string \| TxHintOptions`	No	Description string or structured options

web3.evm.addTx

trace.web3.evm.addTx(tx: TransactionLike, chain?: ChainName): Trace

Parameter	Type	Required	Description
`tx`	`TransactionLike`	Yes	Transaction object (hash, data/input, chainId)
`chain`	`ChainName`	No	Override chain (auto-detected if omitted)

web3.evm.addTxInputData

trace.web3.evm.addTxInputData(inputData: string): Trace

Parameter	Type	Required	Description
`inputData`	`string`	Yes	Hex-encoded transaction input data (calldata)

web3.evm.sendTransaction

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

Parameter	Type	Required	Description
`tx`	`TransactionRequest`	Yes	Transaction 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

Solana Transactions

Correlate Solana transactions via signature

EIP-1193 Provider

Auto-capture transactions with MiradorProvider

Traces

Learn about trace lifecycle and flushing

Transaction Tracking Example

See a complete implementation

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Overview

Adding Transaction Hints

With Details

With Input Data

From a Transaction Object

Supported Chains

Multiple Transaction Hints

Complete Example

Using `sendTransaction`

Method Signatures

web3.evm.addTxHint

web3.evm.addTx

web3.evm.addTxInputData

web3.evm.sendTransaction

Best Practices

Add Hints as Soon as You Have the Hash

Include Descriptive Details

Match Chain to Transaction

Next Steps

Solana Transactions

EIP-1193 Provider

Traces

Transaction Tracking Example

​Overview

​Adding Transaction Hints

​With Details

​With Input Data

​From a Transaction Object

​Supported Chains

​Multiple Transaction Hints

​Complete Example

​Using sendTransaction

​Method Signatures

​web3.evm.addTxHint

​web3.evm.addTx

​web3.evm.addTxInputData

​web3.evm.sendTransaction

​Best Practices

​Add Hints as Soon as You Have the Hash

​Include Descriptive Details

​Match Chain to Transaction

​Next Steps

Solana Transactions

EIP-1193 Provider

Traces

Transaction Tracking Example

Overview

Adding Transaction Hints

With Details

With Input Data

From a Transaction Object

Supported Chains

Multiple Transaction Hints

Complete Example

Using `sendTransaction`

Method Signatures

web3.evm.addTxHint

web3.evm.addTx

web3.evm.addTxInputData

web3.evm.sendTransaction

Best Practices

Add Hints as Soon as You Have the Hash

Include Descriptive Details

Match Chain to Transaction

Next Steps