Evaluate Transactions

Use evaluateTransaction() to simulate transactions, validate inputs, assess risk, and preview balance changes before execution.

evaluateTransaction() simulates and/or validates a transaction before signing. Use it to show users expected balance changes, detect risky transactions, or validate inputs before committing.

Usage

import { WalletChain } from "@tatumio/wallet-sdk";

const evaluation = await client.evaluateTransaction({
  query: { chainId: WalletChain.ETHEREUM_MAINNET },
  body: {
    network: "ethereum",
    transaction: {
      toAddress: "0xRecipient",
      value: "10000000000000000", // 0.01 ETH in wei
    },
    operationType: "all", // "validation" | "simulation" | "all"
  },
});

Operation Types

`operationType`	What it does
`"simulation"`	Simulates execution, returns expected balance changes
`"validation"`	Validates inputs (address format, sufficient balance, etc.)
`"all"`	Runs both simulation and validation (default)

Token Transfers

For ERC-20 or other token transfers, include the token field:

const evaluation = await client.evaluateTransaction({
  query: { chainId: WalletChain.ETHEREUM_MAINNET },
  body: {
    network: "ethereum",
    transaction: {
      toAddress: "0xRecipient",
      value: "0",
      token: {
        address: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
        decimals: 6,
        symbol: "USDC",
      },
    },
  },
});

Contract Interactions

For contract calls, include data (calldata):

const evaluation = await client.evaluateTransaction({
  query: { chainId: WalletChain.ETHEREUM_MAINNET },
  body: {
    network: "ethereum",
    transaction: {
      toAddress: "0xContractAddress",
      value: "0",
      data: "0xa9059cbb...", // encoded function call
    },
  },
});

Response

interface EvaluateTransactionResponse {
  evaluation?: {
    balanceChanges?: Array<{
      token?: {
        address: string;
        decimals: number;
        symbol: string;
      };
      amount?: string;   // human-readable amount
      type?: "IN" | "OUT";
    }>;
    riskScore?: number;     // 0–100, higher = riskier
    classification?: string; // e.g. "transfer", "swap", "contract_interaction"
  };
  unsignedTx?: {
    data?: string;
    recentBlockhash?: string; // Solana
  };
}

Risk Score Guard

const evaluation = await client.evaluateTransaction({
  query: { chainId: WalletChain.ETHEREUM_MAINNET },
  body: {
    network: "ethereum",
    transaction: { toAddress: destination, value: amountWei },
    operationType: "all",
  },
});

const risk = evaluation.evaluation?.riskScore ?? 0;
if (risk > 70) {
  throw new Error(`Transaction flagged as high risk (score: ${risk})`);
}

// Display balance changes to user
for (const change of evaluation.evaluation?.balanceChanges ?? []) {
  console.log(`${change.type}: ${change.amount} ${change.token?.symbol ?? "ETH"}`);
}

Network Names

The network field in the request body uses plain network names, not CAIP-2:

Chain	`network` value
Ethereum	`"ethereum"`
Polygon	`"polygon"`
Solana	`"solana"`
Arbitrum	`"arbitrum"`
Base	`"base"`
Optimism	`"optimism"`
Avalanche	`"avalanche"`