---
title: "Simulate a transaction with risk analysis"
method: POST
path: "/v4/data/security/transaction/simulate"
tags: ["Security API"]
---

# Simulate a transaction with risk analysis

`POST /v4/data/security/transaction/simulate`

## Request

- Base URL: `https://api.tatum.io`
- URL: `https://api.tatum.io/v4/data/security/transaction/simulate`
- Auth: API key in header `x-api-key`

/v4/data/security/transaction/simulate

**60000 credits per API call**

Simulate a transaction against live chain state before signing or broadcasting it. The simulation returns balance movements, execution steps, and a risk assessment covering drainer patterns, suspicious approvals, delegatecalls, MEV exposure, and other threat heuristics.

**Input modes** — provide either:

*   `from` (plus optional `to`, `value`, `data`, `nonce`, fees) — simulate an unsigned transaction, or
*   `rawTx` — replay a signed, already-mined transaction. The transaction is looked up on-chain, so it must exist; to replay it accurately pass `blockNumber` = the block before it was mined.

Requests with neither `from` nor `rawTx` return `400`.

**RPC** — `ethereum-mainnet`, `bsc-mainnet`, `polygon-mainnet`, and `base-mainnet` have built-in RPC support. For any other supported chain, pass your own `rpcUrl`.

**Other notes**

*   `blockNumber` and `gasLimit` are JSON numbers; `value`, `nonce`, and the fee fields are decimal or hex strings (values can exceed the safe JavaScript integer range).
*   `gasLimit` defaults to 30,000,000 — lower it on chains with a smaller block gas limit (e.g. Gnosis).
*   The risk summary (`score`, `level`, `title`, `steps`, `warnings`, `risks`) is returned at the top level of the response.

## Request body

- SecurityTxSimulateRequest
  - `chain` 'ethereum-mainnet' | 'bsc-mainnet' | 'polygon-mainnet' | 'optimism-mainnet' | 'arb-one-mainnet' | 'arb-nova-mainnet' | 'base-mainnet' | 'avax-mainnet' | 'celo-mainnet' | 'cro-mainnet' | 'gno-mainnet' | 'xdc-mainnet' | 'unichain-mainnet' | 'sonic-mainnet' | 'berachain-mainnet', required: Chain to simulate on.
  - `from` string: Sender address. Required unless `rawTx` is provided.
  - `rawTx` string: Signed transaction hex of an existing on-chain transaction; replaces `from`/`to`/`value`/`data`/`nonce`. The transaction is looked up on-chain, so it must reference a real mined transaction.
  - `to` string: Recipient address. Omit for contract creation.
  - `value` string: Value in wei, as a decimal or hex string. Defaults to `0`.
  - `data` string: Calldata hex.
  - `nonce` string: Transaction nonce as a decimal or hex string. Fetched from the chain when omitted.
  - `blockNumber` integer: Simulate against this block instead of the latest.
  - `gasLimit` integer: Gas limit. Defaults to 30,000,000 — lower it on chains whose block gas limit is smaller (e.g. Gnosis).
  - `maxFeePerGas` string: EIP-1559 max fee per gas, as a decimal or hex string.
  - `maxPriorityFeePerGas` string: EIP-1559 max priority fee per gas, as a decimal or hex string.
  - `rpcUrl` string: RPC endpoint to simulate against. Required only for chains without a built-in RPC (built-in: `ethereum-mainnet`, `bsc-mainnet`, `polygon-mainnet`, `base-mainnet`).
  - `format` 'json' | 'dot' | 'text': Response format. `dot` adds a Graphviz `dot` string of the transfer graph. Defaults to `json`.

## Response `200`

OK

- SecurityTxSimulateResponse: Simulation outcome with a flattened risk assessment.
  - `success` boolean: Whether the simulated transaction executed successfully.
  - `score` number: Overall risk score, 0–100. Higher means riskier.
  - `level` string: Risk level derived from the score.
  - `title` string: Human-readable summary of the simulated execution.
  - `steps` string[]: Human-readable execution steps.
  - `warnings` string[]: Human-readable warnings raised during simulation.
  - `risks` object[]: Every risk heuristic evaluated against the transaction.
    - `name` string
    - `weight` number: Contribution of this risk to the overall score.
    - `detected` boolean
    - `description` string
  - `gas_used` number: Gas used by the simulated transaction.
  - `balance_deltas` object[]: Balance movements per affected address.
    - `address` string
    - `native_delta` string: Native balance change in wei.
    - `erc20_deltas` object[]
    - `erc721_moves` object[]
  - `safety` object: Per-heuristic safety flags (e.g. `pure_outflow`, `suspicious_approvals`, `fresh_recipient_risk`, `mev_risk`, `flash_loan_detected`).

## Other responses

- `400`: Bad Request
- `401`: Unauthorized. Not valid or inactive subscription key present in the HTTP Header.
- `403`: Forbidden. The request is authenticated, but it is not possible to perform the operation due to logical error or invalid permissions.
- `500`: Internal server error. There was an error on the server during the processing of the request.

## Changes

- **2026-11-03** `1a87afa0f639`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/tatum/apis/blockchain-data/changes/v4/data/security/transaction/simulate/post.md)

---

[API](https://skmtc.dev/tatum/apis/blockchain-data.md) - [All operations](https://skmtc.dev/tatum/apis/blockchain-data/llms.txt) - [OpenAPI document](https://skmtc.dev/tatum/apis/blockchain-data/revisions/1a87afa0f639?raw)