> ## Documentation Index > Fetch the complete documentation index at: https://docs.range.org/llms.txt > Use this file to discover all available pages before exploring further. # Simulate an EVM Transaction > Simulate an unsigned EVM transaction, including a Safe execTransaction before any signatures exist, to inspect balance changes, transfers, and approvals. ## OpenAPI ````yaml post /v2/simulate/evm openapi: 3.0.0 info: title: Range Risk API description: The Range Risk API for risk assessment of crypto addresses. version: 1.7.31 contact: {} servers: - url: https://api.range.org description: Range API Server security: - Authorization: [] tags: - name: Risk description: Get risk information about a crypto address. - name: Risk v2 description: >- Address risk assessment, workspace configuration, and signals catalogue (API v2). - name: Simulator description: Simulate a transaction on a network. paths: /v2/simulate/evm: post: tags: - Simulator summary: Simulate an EVM transaction, including an unsigned Safe multisig description: >- Traces an unsigned EVM transaction and returns projected balance deltas, token transfers, approvals, the revert reason when it fails, and attribution checks for every address involved. A reverted transaction is a **200** with `status: reverted`. The simulation succeeded; the transaction would not. The trace is pinned to the block in `meta.block_number`, so any result can be reproduced. ## Safe multisig transactions Point this at a Safe `execTransaction` and it simulates **before any signatures exist**, so the first signer is not the one taking the risk. Supported on all 7 networks: eth, arb1, base, oeth, pol, bnb, avax. The response then carries a `safe` block. It is **absent entirely**, rather than null or empty, whenever the target does not answer as a Safe. That covers an ordinary contract, and one that shares the `execTransaction` selector but does not expose Safe ownership. A contract that does answer gets a `safe` block even if it turns out not to be verifiable, with `error.kind` explaining why. | Field | Meaning | | -- | -- | | `address` | The Safe the transaction targets. | | `version` | Published Safe version, or `null`. Most real Safes report `null`, because their implementation is not a published deployment. It reflects the address the Safe names as its implementation, not proof of the code that ran, so treat it as a label rather than an attestation. | | `execution_status` | What became of the Safe transaction itself, which is **not** the outer `status`. A Safe with a non-zero `safeTxGas` catches its inner call's failure and returns normally, so the transaction succeeds while the Safe transaction did not. `not_executed` means the Safe rejected the signature and attempted nothing. `unknown` means the trace did not show the call the Safe should have made, and no claim is made either way. | | `signatures_assumed` | See below. The single most important field on this block. | | `threshold` | Owners required to sign, as it stands on chain. `null` when the Safe could not be read. | | `sender_is_owner` | `false` means this sender could never submit this transaction, whatever else the simulation shows. `null` means it could not be read, which is not the same as `false`. | | `batch_state` | Why `batch` holds what it holds. Only `decoded` carries an array. | | `error` | Present when signatures could not be assumed. | ### A successful simulation is not a submittable transaction When `signatures_assumed` is `true`, the request lacked enough Safe signatures and temporary, off-chain overrides were used to simulate valid threshold approval. The result is conditional and is not ready for submission. **Signature-dependent guard behaviour may differ when `signatures_assumed` is `true`.** A guard can inspect signature data, so a guard outcome observed while signatures were assumed is not evidence about the real transaction. Do not rely on it. ### Batches, entry by entry A MultiSend batch is decomposed into `batch`, one object per entry, with that entry's own transfers, approvals and balance deltas. This works **including when the batch fails**, which is the case that matters. A failing batch tells you at the top level only that something inside it failed. It does not say which entry, or why. The failing entry's own `error` is the only account of that. | `status` | Meaning | | -- | -- | | `success` | Ran and took effect. **The only status where the entry's effects applied.** | | `rolled_back` | Ran, but the Safe transaction did not apply, so nothing it did survives. The cause may be a later entry, a guard, or the transaction itself. It does not imply a failed sibling. | | `reverted` | This entry is the one that failed, and carries the decoded revert reason. | | `not_executed` | Never ran. Its `error` is a fixed explanatory note, not a failure of its own, and it may still fail once the reverting entry is fixed. | **The flat arrays and the entry arrays add up only when the Safe transaction applied.** When it did, `transfers` equals top-level effects plus every entry's effects concatenated. When it did not, the flat arrays carry only what actually happened, usually nothing, while each entry still identifies itself, its target and its status. Note that a **failed** transaction yields little per-entry effect detail. The node discards event logs for a transaction that reverts, so token transfers inside a failed batch cannot be recovered from the trace. What survives is each entry's identity, target, selector, status and reason, plus any native value movement. Entry targets still reach the screened address set. `batch` is `null` whenever `batch_state` is not `decoded`: `not_batched` (no MultiSend), `empty` (a MultiSend carrying no entries), `malformed` (an unparseable payload), or `unattributed` (a batch that could not be broken down safely). ### When signatures could not be assumed `signatures_assumed: false` with an `error.kind`. The ordinary trace and every other field still return. This is a degraded answer, never an error response. | `kind` | What to do | | -- | -- | | `sender_unusable` | The sender can never be a Safe owner. Simulate from a real address. | | `state_override_conflict` | Your `state_overrides` change the Safe itself. Move them off the Safe address, or accept the unsigned result. | | `safe_not_recognised` | The Safe could not be verified. Nothing to change; the plain trace still stands. | | `safe_uninitialised` | The Safe has never been set up: its threshold is zero and it has no owners, so nobody can sign for it. Run `setup` first. | `signatures_assumed` can also be `false` with **no** error. That means either the proposal already carried enough signatures and needed nothing from us, or the Safe rejected the signature during the trace. Either way the result describes the transaction exactly as you sent it. ## Screening is coverage, not a guarantee At most 50 addresses are screened. Above that the remainder is still listed, with `check_status: "unavailable"` and no sanctions result, and `meta.addresses_truncated` is `true`. Addresses are ordered so the parties to the transaction are screened before the contracts it merely touched. An address carrying `check_status: "unavailable"` has **not** been cleared. It has not been checked. operationId: simulate parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SimulateEvmRequestDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/SimulateEvmResponseDto' examples: safe_batch_success: summary: >- Unsigned Safe batch that would apply after valid threshold approval — signatures_assumed is true, so the result is conditional and not ready for submission value: network: eth status: success error: null gas_used: '0x1a2b3' created_contract: null balance_deltas: - account_address: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' asset_id: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' standard: erc20 amount_delta_raw: '-2500000' amount_delta_normalized: '-2.5' usd_value: '-2.50' asset: symbol: USDC decimals: 6 is_stablecoin: true icon_url: null - account_address: '0x000000000000000000000000000000000000dead' asset_id: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' standard: erc20 amount_delta_raw: '2500000' amount_delta_normalized: '2.5' usd_value: '2.50' asset: symbol: USDC decimals: 6 is_stablecoin: true icon_url: null transfers: - standard: erc20 from: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' to: '0x000000000000000000000000000000000000dead' asset_id: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' token_id: null amount_raw: '1500000' amount_normalized: '1.5' usd_value: '1.50' asset: symbol: USDC decimals: 6 is_stablecoin: true icon_url: null depth: 3 - standard: erc20 from: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' to: '0x000000000000000000000000000000000000dead' asset_id: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' token_id: null amount_raw: '1000000' amount_normalized: '1' usd_value: '1.00' asset: symbol: USDC decimals: 6 is_stablecoin: true icon_url: null depth: 3 approvals: [] addresses: - address: '0x000000000000000000000000000000000000dead' roles: - recipient malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok - address: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' roles: - target_contract - called_contract - sender - safe_proxy malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok - address: '0x1111111111111111111111111111111111111111' roles: - signer malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok - address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' roles: - called_contract - batch_target malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok - address: '0x43506849d7c04f9138d1a2050bbf3a0c054402dd' roles: - called_contract malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok safe: address: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' version: 1.4.1 execution_status: success signatures_assumed: true threshold: 2 sender_is_owner: false batch_state: decoded error: null batch: - index: 0 operation: 0 target: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' value: '0' selector: '0xa9059cbb' status: success error: null transfers: - standard: erc20 from: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' to: '0x000000000000000000000000000000000000dead' asset_id: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' token_id: null amount_raw: '1500000' amount_normalized: '1.5' usd_value: '1.50' asset: symbol: USDC decimals: 6 is_stablecoin: true icon_url: null depth: 3 approvals: [] balance_deltas: [] - index: 1 operation: 0 target: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' value: '0' selector: '0xa9059cbb' status: success error: null transfers: - standard: erc20 from: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' to: '0x000000000000000000000000000000000000dead' asset_id: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' token_id: null amount_raw: '1000000' amount_normalized: '1' usd_value: '1.00' asset: symbol: USDC decimals: 6 is_stablecoin: true icon_url: null depth: 3 approvals: [] balance_deltas: [] meta: rpc_ms: 412 enrich_ms: 88 total_ms: 511 frames: 9 logs: 2 unknown_logs: 0 addresses_truncated: false block_number: 25948202 safe_batch_failure: summary: >- Safe batch where a middle entry reverts — the top level says only that something inside failed, entry 1 carries the reason, entry 0 rolled back rather than succeeded, and the flat arrays are empty because nothing applied value: network: eth status: reverted error: kind: revert reason: GS013 selector: '0x08c379a0' gas_used: '0x123eb' created_contract: null balance_deltas: [] transfers: [] approvals: [] addresses: - address: '0x1111111111111111111111111111111111111111' roles: - signer malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok - address: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' roles: - target_contract - safe_proxy malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok - address: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' roles: - batch_target - called_contract malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok - address: '0x43506849d7c04f9138d1a2050bbf3a0c054402dd' roles: - called_contract malicious: false sanctioned: false token_blacklisted: false blacklisted_by: [] name: null entity: null category: null tags: [] role: null check_status: ok safe: address: '0xa75c21c5be284122a87a37a76cc6c4dd3e55a1d4' version: 1.4.1 execution_status: failed signatures_assumed: true threshold: 2 sender_is_owner: false batch_state: decoded error: null batch: - index: 0 operation: 0 target: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' value: '0' selector: '0xa9059cbb' status: rolled_back error: null transfers: [] approvals: [] balance_deltas: [] - index: 1 operation: 0 target: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' value: '0' selector: '0xa9059cbb' status: reverted error: kind: revert reason: 'ERC20: transfer amount exceeds balance' selector: '0x08c379a0' transfers: [] approvals: [] balance_deltas: [] - index: 2 operation: 0 target: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' value: '0' selector: '0xa9059cbb' status: not_executed error: kind: revert reason: >- An earlier entry stopped the batch before this one ran. selector: null transfers: [] approvals: [] balance_deltas: [] meta: rpc_ms: 137 enrich_ms: 1 total_ms: 140 frames: 7 logs: 0 unknown_logs: 0 addresses_truncated: false block_number: 25948202 components: schemas: SimulateEvmRequestDto: type: object properties: network: type: string enum: - eth - arb1 - base - oeth - pol - bnb - avax example: eth transaction: $ref: '#/components/schemas/EvmTransactionDto' state_overrides: type: object description: >- Per-address state overrides applied before the simulation, keyed by address. Forwarded to the node as-is. additionalProperties: true example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045': balance: '0xde0b6b3a7640000' required: - network - transaction SimulateEvmResponseDto: type: object properties: network: type: string example: eth status: type: string enum: - success - reverted error: nullable: true type: object allOf: - $ref: '#/components/schemas/EvmSimulationErrorDto' gas_used: type: string example: '0x5208' created_contract: type: string nullable: true balance_deltas: type: array items: $ref: '#/components/schemas/EvmBalanceDeltaDto' transfers: type: array items: $ref: '#/components/schemas/EvmTransferDto' approvals: type: array items: $ref: '#/components/schemas/EvmApprovalDto' addresses: description: >- Every address the simulation touched, ordered by screening priority rather than by where it appeared in the transaction. The parties to the transaction come first, then the Safe and the contracts a batch pointed at, then the contracts that were merely called. Position means nothing beyond that, so it should not be read as the order in which effects happened. type: array items: $ref: '#/components/schemas/EvmAddressCheckDto' safe: description: >- Present only when the calldata decoded as a Safe `execTransaction` and the Safe answered. For every other transaction this field is absent altogether, rather than null or an empty object. allOf: - $ref: '#/components/schemas/EvmSafeDto' batch: nullable: true description: >- One object per MultiSend entry, in payload order. Null whenever `safe.batch_state` is not `decoded`, and absent alongside `safe`. The arrays above carry applied effects only, so on a failed batch they are empty while each entry still reports what it attempted. type: array items: $ref: '#/components/schemas/EvmSafeBatchEntryDto' meta: $ref: '#/components/schemas/EvmSimulationMetaDto' required: - network - status - error - gas_used - created_contract - balance_deltas - transfers - approvals - addresses - meta EvmTransactionDto: type: object properties: from: type: string example: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' to: type: string description: Omit for contract creation. example: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48' value: type: string example: '0x0' data: type: string example: 0xa9059cbb… gas: type: string example: '0x5208' gas_price: type: string example: '0x3b9aca00' max_fee_per_gas: type: string example: '0x3b9aca00' max_priority_fee_per_gas: type: string example: '0x3b9aca00' nonce: type: string example: '0x1' required: - from EvmSimulationErrorDto: type: object properties: kind: type: string enum: - revert - out_of_gas - custom_error - unknown reason: type: string nullable: true example: 'ERC20: transfer amount exceeds balance' selector: type: string nullable: true example: '0x08c379a0' required: - kind - reason - selector EvmBalanceDeltaDto: type: object properties: account_address: type: string asset_id: type: string description: '`native`, `0x` or `0x:`.' standard: type: string enum: - native - erc20 - erc1155 amount_delta_raw: type: string description: Signed base-unit delta. example: '-1000000' amount_delta_normalized: type: string nullable: true example: '-1' usd_value: type: string nullable: true example: '-1.00' asset: nullable: true type: object allOf: - $ref: '#/components/schemas/EvmAssetDto' required: - account_address - asset_id - standard - amount_delta_raw - amount_delta_normalized - usd_value EvmTransferDto: type: object properties: standard: type: string enum: - native - erc20 - erc721 - erc1155 from: type: string to: type: string asset_id: type: string token_id: type: string nullable: true amount_raw: type: string amount_normalized: type: string nullable: true example: '1.5' usd_value: type: string nullable: true example: '1.50' asset: nullable: true type: object allOf: - $ref: '#/components/schemas/EvmAssetDto' depth: type: number description: Call depth the transfer happened at; 0 = top-level. required: - standard - from - to - asset_id - token_id - amount_raw - amount_normalized - usd_value - depth EvmApprovalDto: type: object properties: standard: type: string enum: - erc20 - erc721 - erc1155 owner: type: string spender: type: string asset_id: type: string token_id: type: string nullable: true amount_raw: type: string nullable: true amount_normalized: type: string nullable: true asset: nullable: true type: object allOf: - $ref: '#/components/schemas/EvmAssetDto' unlimited: type: boolean for_all: type: boolean revoked: type: boolean required: - standard - owner - spender - asset_id - token_id - amount_raw - amount_normalized - unlimited - for_all - revoked EvmAddressCheckDto: type: object properties: address: type: string roles: type: array items: type: string enum: - signer - target_contract - sender - recipient - owner - spender - operator - called_contract - created_contract - safe_proxy - batch_target malicious: type: boolean sanctioned: type: boolean token_blacklisted: type: boolean blacklisted_by: type: array items: type: string name: type: string nullable: true entity: type: string nullable: true category: type: string nullable: true tags: type: array items: type: string role: type: string nullable: true check_status: type: string enum: - ok - unavailable required: - address - roles - malicious - sanctioned - token_blacklisted - blacklisted_by - name - entity - category - tags - role - check_status EvmSafeDto: type: object properties: address: type: string example: '0x1c8b9b3bd2a1f4dbd0f8c1e4f0c2a3b4c5d6e7f8' version: type: string nullable: true description: >- The published Safe version, when the implementation this Safe points at is a recognised deployment. A fork or a privately deployed implementation reports null, which is the common case. This reflects the address the Safe names as its implementation, not proof of the code that ran. example: 1.4.1 execution_status: type: string enum: - success - failed - not_executed - unknown description: >- What became of the Safe transaction itself, which is not the same as the outer transaction status. A Safe can fail inside a transaction that otherwise succeeds. `not_executed` means the Safe rejected the signature and attempted nothing. `unknown` means the outcome was not established, and no claim is made either way. example: success signatures_assumed: type: boolean description: >- True when the request lacked enough Safe signatures and temporary, off-chain overrides were used to simulate valid threshold approval. The result is conditional and is not ready for submission. Signature-dependent guard behaviour may differ. threshold: type: number nullable: true description: >- How many owners must sign, as it stands on chain, before the simulation assumed anything. Null when the Safe could not be read. example: 3 sender_is_owner: type: boolean nullable: true description: >- Whether the sender is genuinely a Safe owner. False means this sender could never submit this transaction, whatever else the simulation shows. Null means it could not be read, which is not the same as false. batch_state: type: string enum: - not_batched - decoded - empty - malformed - unattributed description: >- Why `batch` holds what it holds. `decoded` is the only state that carries an array. The rest all leave it null, and say which case it is: `not_batched` for a plain Safe call, `empty` for a MultiSend carrying no entries, `malformed` for a payload that could not be parsed, and `unattributed` for a batch that could not be broken down safely. example: decoded error: nullable: true type: object allOf: - $ref: '#/components/schemas/EvmSafeErrorDto' required: - address - version - execution_status - signatures_assumed - threshold - sender_is_owner - batch_state - error EvmSafeBatchEntryDto: type: object properties: index: type: number description: Position of this entry in the MultiSend payload, starting at 0. example: 0 operation: type: number description: >- The operation this entry asked for, exactly as the payload wrote it. 0 is a call and 1 is a delegatecall. Any other value matches neither, so the entry reverts. example: 0 target: type: string example: '0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48' value: type: string description: Native currency this entry sends, in base units. example: '0' selector: type: string nullable: true example: '0xa9059cbb' status: type: string enum: - success - rolled_back - reverted - not_executed description: >- What became of this entry. `success` is the only status where its effects applied. `rolled_back` means it ran but the Safe transaction did not apply, so nothing it did survives; the cause may be a later entry, a guard, or the transaction itself, and it does not imply a failed sibling. `reverted` is the entry that failed, and it carries the decoded revert reason. `not_executed` means it never ran. example: success error: nullable: true type: object allOf: - $ref: '#/components/schemas/EvmSimulationErrorDto' transfers: type: array items: $ref: '#/components/schemas/EvmTransferDto' approvals: type: array items: $ref: '#/components/schemas/EvmApprovalDto' balance_deltas: type: array items: $ref: '#/components/schemas/EvmBalanceDeltaDto' required: - index - operation - target - value - selector - status - error - transfers - approvals - balance_deltas EvmSimulationMetaDto: type: object properties: rpc_ms: type: number enrich_ms: type: number total_ms: type: number frames: type: number logs: type: number unknown_logs: type: number addresses_truncated: type: boolean description: >- True when more addresses were involved than can be screened. The extra addresses are still listed, with check_status "unavailable" and no sanctions result. block_number: type: number nullable: true description: >- The block the simulation ran against, so you can tell how fresh the result is and reproduce it later. Null in the rare case where the height could not be read, which means the simulation ran against the chain tip as it stood at that moment. Everything else in the response is unaffected. example: 21000000 required: - rpc_ms - enrich_ms - total_ms - frames - logs - unknown_logs - addresses_truncated - block_number EvmAssetDto: type: object properties: symbol: type: string example: USDC decimals: type: number example: 6 is_stablecoin: type: boolean example: true icon_url: type: string nullable: true example: https://icons.range.org/assets/12.webp required: - symbol - decimals - is_stablecoin - icon_url EvmSafeErrorDto: type: object properties: kind: type: string enum: - sender_unusable - state_override_conflict - safe_not_recognised - safe_uninitialised description: >- Why signatures could not be assumed. `sender_unusable` means the sender can never be a Safe owner, so simulate from a real address. `state_override_conflict` means your state overrides change the Safe itself, so move them to another address. `safe_not_recognised` means the Safe could not be verified, and there is nothing to change. `safe_uninitialised` means the Safe has never been set up: its threshold is zero and it has no owners, so no signatures could ever authorise it. reason: type: string nullable: true example: Safe signatures could not be assumed for this transaction. required: - kind - reason securitySchemes: Authorization: type: apiKey in: header name: X-API-KEY description: Authorization method required to allow user to access the api endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.