> ## Documentation Index
> Fetch the complete documentation index at: https://docs.illa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Simulation previews

> Use transaction simulation data to build confirmation UIs

Pending tool calls can include a `SimulationResult` that previews what should happen when the transaction executes.

## When simulation data is available

Check `simulated` and `simulation` on each pending tool:

```ts theme={null}
const result = await sdk.sendMessage(
  'Swap 1 ETH to USDC on Base',
  { userContext: { address: '0x1234...' } },
)

if (result.response.isError) {
  throw new Error(result.response.error.message)
}

for (const tool of result.response.data.pendingTools ?? []) {
  if (tool.simulated && tool.simulation) {
    showConfirmation(tool)
  } else {
    executeDirectly(tool)
  }
}
```

## Building a confirmation screen

### Asset changes

`assetChanges` lists the expected token balance changes:

```ts theme={null}
function renderAssetChanges(simulation: SimulationResult) {
  for (const change of simulation.assetChanges) {
    const sign = change.direction === 'out' ? '-' : '+'
    console.log(`${sign}${change.formattedAmount} ${change.tokenSymbol} ($${change.usdValue})`)
  }
}
```

Useful fields:

* `tokenSymbol`
* `tokenName`
* `formattedAmount`
* `rawAmount`
* `usdValue`
* `direction`
* `logoUrl`

### Gas estimate

```ts theme={null}
function renderGas(simulation: SimulationResult) {
  const gas = simulation.gasEstimate
  const symbol = simulation.nativeTokenSymbol ?? 'ETH'
  console.log(`Network fee: ${gas.gasCostNative} ${symbol} ($${gas.gasCostUsd})`)
}
```

### Failure prediction

```ts theme={null}
if (!simulation.willSucceed) {
  console.warn('This transaction is likely to fail.')
  if (simulation.errorExplanation) {
    console.warn('Reason:', simulation.errorExplanation)
  }
}
```

### Action type context

Use `actionType` to adapt the UI by operation type:

```ts theme={null}
switch (simulation.actionType) {
  case 'swap':
    renderSwapPreview(simulation)
    break
  case 'bridge':
    renderBridgePreview(simulation)
    break
  case 'transfer':
    renderTransferPreview(simulation)
    break
  default:
    renderGenericPreview(simulation)
}
```

### Cross-chain operations

For bridge-style previews, `sourceChainId` and `destChainId` identify the chains involved:

```ts theme={null}
if (simulation.actionType === 'bridge') {
  console.log(`From chain ${simulation.sourceChainId} to chain ${simulation.destChainId}`)
}
```

### Fallback metadata

When asset changes are unavailable, `actionMetadata` still gives you structured UI hints:

```ts theme={null}
if (simulation.assetChanges.length === 0 && simulation.actionMetadata) {
  const meta = simulation.actionMetadata
  console.log(`${meta.inputAmount} ${meta.inputToken} -> ${meta.outputAmount} ${meta.outputToken}`)
  if (meta.protocol) console.log(`via ${meta.protocol}`)
}
```

## Simulation is display-only

Simulation data should not drive execution logic. Always execute using `tool.input` as the source of truth.

## See also

* [Handling tool execution](/sdk/guides/handling-tool-execution)
* [Types and utilities](/sdk/api/types-and-utilities)