# Transaction Simulation API

See exactly what a transaction will do—*before* it’s signed. Our API runs a full on‑chain simulation and returns clear, USD‑denominated balance changes, so users of custodial platform such as [Cobo](https://www.cobo.com/) and [Fireblocks](https://www.fireblocks.com/) can approve or reject transfers with confidence.

**Why it matters**

* **Pre‑sign insights** – Know the outcome of any transaction in advance.
* **Seamless integration** – A lightweight REST endpoint that drops straight into your existing workflow.
* **Actionable data** – Balance deltas presented in familiar USD terms.

**Supported chains**\
Ethereum · BNB Smart Chain · Base · Optimism · Polygon · Story

**Get started**\
[Fill out the form](https://blocksec.com/expert-contact) to receive your API key and start simulating in minutes.

## Balance Change

## Raw Transaction Simulation

> Simulate raw transaction and get balance changes

```json
{"openapi":"3.0.3","info":{"title":"Transaction Simulation API","version":"1.0.2"},"servers":[{"url":"https://api.blocksec.com/simulation/v1"}],"paths":{"/raw/balancechange":{"post":{"summary":"Raw Transaction Simulation","description":"Simulate raw transaction and get balance changes","parameters":[{"name":"API-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RawTransactionRequest"}}}},"responses":{"200":{"description":"Simulation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationResponse"}}}}}}}},"components":{"schemas":{"RawTransactionRequest":{"type":"object","required":["blockNumber","transaction"],"properties":{"blockNumber":{"type":"integer","format":"uint64","description":"The block number on which the transaction simulation is based. If this value is 0, transaction simulation will be based on the latest block."},"transaction":{"type":"string","description":"Raw transaction hex string"}}},"SimulationResponse":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","format":"int32","enum":[0,1,2,3,4,5,6,7,8],"description":"Status codes:\n- 0: Success\n- 1: Unexpected error (contact phalcon_support@blocksec.com)\n- 2: Invalid request body format\n- 3: Invalid raw transaction\n- 4: Unsupported chain ID\n- 5: Chain-gateway error (contact phalcon_support@blocksec.com)\n- 6: RPC node error (contact phalcon_support@blocksec.com)\n- 7: Invalid chain ID\n- 8: The check of transaction simulation failed\n"},"message":{"type":"string","description":"Human-readable description of the status code"},"data":{"$ref":"#/components/schemas/TransactionData"}}},"TransactionData":{"type":"object","required":["status","blockNumber","txnHash","sender","receiver","timestamp","callData","gasLimit","gasPrice","gasUsed","baseFee","transactionFee","nonce","value","errorInfo","balanceChanges","viewLink"],"properties":{"status":{"type":"boolean","description":"Transaction execution status (true/false)"},"blockNumber":{"type":"integer","format":"uint64","description":"Block number"},"txnHash":{"type":"string","description":"Transaction hash"},"sender":{"type":"string","description":"Transaction initiator address"},"receiver":{"type":"string","description":"Transaction recipient address"},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp"},"callData":{"type":"string","description":"Transaction calldata in hex format"},"gasLimit":{"type":"integer","format":"uint64","description":"Maximum gas allowed for transaction"},"gasPrice":{"type":"string","pattern":"^\\d+$","description":"Gas price in wei (as integer string)"},"gasUsed":{"type":"integer","format":"uint64","description":"Actual gas used in the transaction"},"baseFee":{"type":"string","pattern":"^\\d+$","description":"Base fee for EIP-1559 transactions in wei (as integer string)"},"transactionFee":{"type":"string","pattern":"^\\d+$","description":"Total transaction fee in wei (as integer string)"},"nonce":{"type":"integer","format":"uint64","description":"Sender's nonce (equal to number of transactions sent by sender)"},"value":{"type":"string","pattern":"^\\d+$","description":"Transaction value in wei (as integer string)"},"errorInfo":{"type":"string","description":"Error information when status is false"},"balanceChanges":{"type":"array","items":{"$ref":"#/components/schemas/BalanceChange"},"description":"List of account balance changes"},"viewLink":{"type":"string","description":"Phalcon Explorer view link for the transaction simulation"}}},"BalanceChange":{"type":"object","required":["account","assets"],"properties":{"account":{"type":"string","description":"Account address (asset holder)"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"},"description":"List of asset changes"}}},"Asset":{"type":"object","required":["address","tokenId","rawAmount","amount","iconUrl","isERC1155","isERC721","sign","value"],"properties":{"address":{"type":"string","description":"Token contract address"},"tokenId":{"type":"string","description":"Token ID for ERC721/ERC1155 (empty string for ERC20)"},"rawAmount":{"type":"string","pattern":"^\\d+$","description":"Raw amount (unprocessed by decimals) as integer string"},"amount":{"type":"string","description":"Formatted amount (rawAmount / 10^decimals), empty if decimals missing"},"iconUrl":{"type":"string","description":"URL for token icon (empty if unavailable)"},"isERC1155":{"type":"boolean","description":"Indicates ERC1155 token"},"isERC721":{"type":"boolean","description":"Indicates ERC721 token"},"sign":{"type":"boolean","description":"Indicates sign of rawAmount/amount (positive/negative)"},"value":{"type":"string","description":"USD value of asset in decimal format.\nEmpty if missing token price or decimals information.\nExamples: \n- \"22.94604\" (with USD value)\n- \"\" (no pricing data)\n"}}}}}}
```

## Custom Transaction Simulation

> Simulate custom transaction parameters and get balance changes

```json
{"openapi":"3.0.3","info":{"title":"Transaction Simulation API","version":"1.0.2"},"servers":[{"url":"https://api.blocksec.com/simulation/v1"}],"paths":{"/custom/balancechange":{"post":{"summary":"Custom Transaction Simulation","description":"Simulate custom transaction parameters and get balance changes","parameters":[{"name":"API-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomTransactionRequest"}}}},"responses":{"200":{"description":"Simulation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationResponse"}}}}}}}},"components":{"schemas":{"CustomTransactionRequest":{"type":"object","required":["chainId","transaction"],"properties":{"chainId":{"type":"integer","format":"uint64","description":"Chain ID for the transaction"},"blockNumber":{"type":"integer","format":"uint64","description":"The block number on which the transaction simulation is based. If this value is 0, transaction simulation will be based on the latest block."},"transaction":{"type":"object","required":["sender","receiver","gasLimit","gasPrice","value","input"],"properties":{"sender":{"type":"string","description":"Transaction sender address"},"receiver":{"type":"string","description":"Transaction recipient address"},"gasLimit":{"type":"integer","format":"uint64","description":"Maximum gas allowed for transaction.  If this value is zero, then the simulation will be based on the gasLimit returned by eth_estimateGas."},"gasPrice":{"type":"string","pattern":"^\\d+$","description":"Gas price in wei (as integer string). If this value is zero, then the simulation will be based on the gasPrice returned by eth_gasPrice."},"value":{"type":"string","pattern":"^\\d+$","description":"Transaction value in wei (as integer string)"},"input":{"type":"string","description":"Transaction calldata in hex format"}}}}},"SimulationResponse":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","format":"int32","enum":[0,1,2,3,4,5,6,7,8],"description":"Status codes:\n- 0: Success\n- 1: Unexpected error (contact phalcon_support@blocksec.com)\n- 2: Invalid request body format\n- 3: Invalid raw transaction\n- 4: Unsupported chain ID\n- 5: Chain-gateway error (contact phalcon_support@blocksec.com)\n- 6: RPC node error (contact phalcon_support@blocksec.com)\n- 7: Invalid chain ID\n- 8: The check of transaction simulation failed\n"},"message":{"type":"string","description":"Human-readable description of the status code"},"data":{"$ref":"#/components/schemas/TransactionData"}}},"TransactionData":{"type":"object","required":["status","blockNumber","txnHash","sender","receiver","timestamp","callData","gasLimit","gasPrice","gasUsed","baseFee","transactionFee","nonce","value","errorInfo","balanceChanges","viewLink"],"properties":{"status":{"type":"boolean","description":"Transaction execution status (true/false)"},"blockNumber":{"type":"integer","format":"uint64","description":"Block number"},"txnHash":{"type":"string","description":"Transaction hash"},"sender":{"type":"string","description":"Transaction initiator address"},"receiver":{"type":"string","description":"Transaction recipient address"},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp"},"callData":{"type":"string","description":"Transaction calldata in hex format"},"gasLimit":{"type":"integer","format":"uint64","description":"Maximum gas allowed for transaction"},"gasPrice":{"type":"string","pattern":"^\\d+$","description":"Gas price in wei (as integer string)"},"gasUsed":{"type":"integer","format":"uint64","description":"Actual gas used in the transaction"},"baseFee":{"type":"string","pattern":"^\\d+$","description":"Base fee for EIP-1559 transactions in wei (as integer string)"},"transactionFee":{"type":"string","pattern":"^\\d+$","description":"Total transaction fee in wei (as integer string)"},"nonce":{"type":"integer","format":"uint64","description":"Sender's nonce (equal to number of transactions sent by sender)"},"value":{"type":"string","pattern":"^\\d+$","description":"Transaction value in wei (as integer string)"},"errorInfo":{"type":"string","description":"Error information when status is false"},"balanceChanges":{"type":"array","items":{"$ref":"#/components/schemas/BalanceChange"},"description":"List of account balance changes"},"viewLink":{"type":"string","description":"Phalcon Explorer view link for the transaction simulation"}}},"BalanceChange":{"type":"object","required":["account","assets"],"properties":{"account":{"type":"string","description":"Account address (asset holder)"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"},"description":"List of asset changes"}}},"Asset":{"type":"object","required":["address","tokenId","rawAmount","amount","iconUrl","isERC1155","isERC721","sign","value"],"properties":{"address":{"type":"string","description":"Token contract address"},"tokenId":{"type":"string","description":"Token ID for ERC721/ERC1155 (empty string for ERC20)"},"rawAmount":{"type":"string","pattern":"^\\d+$","description":"Raw amount (unprocessed by decimals) as integer string"},"amount":{"type":"string","description":"Formatted amount (rawAmount / 10^decimals), empty if decimals missing"},"iconUrl":{"type":"string","description":"URL for token icon (empty if unavailable)"},"isERC1155":{"type":"boolean","description":"Indicates ERC1155 token"},"isERC721":{"type":"boolean","description":"Indicates ERC721 token"},"sign":{"type":"boolean","description":"Indicates sign of rawAmount/amount (positive/negative)"},"value":{"type":"string","description":"USD value of asset in decimal format.\nEmpty if missing token price or decimals information.\nExamples: \n- \"22.94604\" (with USD value)\n- \"\" (no pricing data)\n"}}}}}}
```

## Trace

## Raw Transaction Simulation

> Simulate raw transaction and return execution trace

```json
{"openapi":"3.0.3","info":{"title":"Transaction Simulation API","version":"1.0.2"},"servers":[{"url":"https://api.blocksec.com/simulation/v1"}],"paths":{"/raw/trace":{"post":{"summary":"Raw Transaction Simulation","description":"Simulate raw transaction and return execution trace","parameters":[{"name":"API-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RawTransactionRequest"}}}},"responses":{"200":{"description":"Simulation result with trace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationTraceResponse"}}}}}}}},"components":{"schemas":{"RawTransactionRequest":{"type":"object","required":["blockNumber","transaction"],"properties":{"blockNumber":{"type":"integer","format":"uint64","description":"The block number on which the transaction simulation is based. If this value is 0, transaction simulation will be based on the latest block."},"transaction":{"type":"string","description":"Raw transaction hex string"}}},"SimulationTraceResponse":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/TransactionTraceData"}}},"TransactionTraceData":{"allOf":[{"$ref":"#/components/schemas/TransactionData"},{"type":"object","properties":{"trace":{"$ref":"#/components/schemas/Call"}},"required":["trace"]}]},"TransactionData":{"type":"object","required":["status","blockNumber","txnHash","sender","receiver","timestamp","callData","gasLimit","gasPrice","gasUsed","baseFee","transactionFee","nonce","value","errorInfo","balanceChanges","viewLink"],"properties":{"status":{"type":"boolean","description":"Transaction execution status (true/false)"},"blockNumber":{"type":"integer","format":"uint64","description":"Block number"},"txnHash":{"type":"string","description":"Transaction hash"},"sender":{"type":"string","description":"Transaction initiator address"},"receiver":{"type":"string","description":"Transaction recipient address"},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp"},"callData":{"type":"string","description":"Transaction calldata in hex format"},"gasLimit":{"type":"integer","format":"uint64","description":"Maximum gas allowed for transaction"},"gasPrice":{"type":"string","pattern":"^\\d+$","description":"Gas price in wei (as integer string)"},"gasUsed":{"type":"integer","format":"uint64","description":"Actual gas used in the transaction"},"baseFee":{"type":"string","pattern":"^\\d+$","description":"Base fee for EIP-1559 transactions in wei (as integer string)"},"transactionFee":{"type":"string","pattern":"^\\d+$","description":"Total transaction fee in wei (as integer string)"},"nonce":{"type":"integer","format":"uint64","description":"Sender's nonce (equal to number of transactions sent by sender)"},"value":{"type":"string","pattern":"^\\d+$","description":"Transaction value in wei (as integer string)"},"errorInfo":{"type":"string","description":"Error information when status is false"},"balanceChanges":{"type":"array","items":{"$ref":"#/components/schemas/BalanceChange"},"description":"List of account balance changes"},"viewLink":{"type":"string","description":"Phalcon Explorer view link for the transaction simulation"}}},"BalanceChange":{"type":"object","required":["account","assets"],"properties":{"account":{"type":"string","description":"Account address (asset holder)"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"},"description":"List of asset changes"}}},"Asset":{"type":"object","required":["address","tokenId","rawAmount","amount","iconUrl","isERC1155","isERC721","sign","value"],"properties":{"address":{"type":"string","description":"Token contract address"},"tokenId":{"type":"string","description":"Token ID for ERC721/ERC1155 (empty string for ERC20)"},"rawAmount":{"type":"string","pattern":"^\\d+$","description":"Raw amount (unprocessed by decimals) as integer string"},"amount":{"type":"string","description":"Formatted amount (rawAmount / 10^decimals), empty if decimals missing"},"iconUrl":{"type":"string","description":"URL for token icon (empty if unavailable)"},"isERC1155":{"type":"boolean","description":"Indicates ERC1155 token"},"isERC721":{"type":"boolean","description":"Indicates ERC721 token"},"sign":{"type":"boolean","description":"Indicates sign of rawAmount/amount (positive/negative)"},"value":{"type":"string","description":"USD value of asset in decimal format.\nEmpty if missing token price or decimals information.\nExamples: \n- \"22.94604\" (with USD value)\n- \"\" (no pricing data)\n"}}},"Call":{"type":"object","description":"Represents a single EVM execution step, including nested calls and logs.","properties":{"id":{"type":"integer","description":"Represents the execution order of the transaction."},"status":{"type":"boolean","description":"Execution status of the call (true if successful, false otherwise)."},"error":{"type":"string","description":"Error message when the call failed (empty if successful)."},"type":{"type":"string","description":"Type of call (e.g., CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2)."},"from":{"type":"string","description":"Address of the caller (sender of this call)."},"to":{"type":"string","description":"Address of the callee (recipient of this call)."},"value":{"type":"string","description":"ETH value (in wei) transferred in this call."},"input":{"type":"string","description":"Input calldata (hex-encoded) provided to this call."},"output":{"type":"string","description":"Return data (hex-encoded) produced by this call."},"gasLimit":{"type":"integer","format":"uint64","description":"Gas provided for this call."},"gasUsed":{"type":"integer","format":"uint64","description":"Actual gas consumed by this call."},"calls":{"type":"array","description":"Nested sub-calls triggered during this call.","items":{"$ref":"#/components/schemas/Call"}},"logs":{"type":"array","description":"Logs emitted during this call.","items":{"$ref":"#/components/schemas/Log"}}}},"Log":{"type":"object","description":"Represents an Ethereum log event emitted during execution.","properties":{"id":{"type":"integer","description":"Represents the execution order of the transaction."},"address":{"type":"string","description":"Address of the contract that emitted the log."},"topics":{"type":"array","items":{"type":"string"},"description":"Indexed event topics (up to 4), hex-encoded."},"data":{"type":"string","description":"Non-indexed event data payload (hex-encoded)."}}}}}}
```

## Custom Transaction Simulation

> Simulate custom transaction parameters and return execution trace

```json
{"openapi":"3.0.3","info":{"title":"Transaction Simulation API","version":"1.0.2"},"servers":[{"url":"https://api.blocksec.com/simulation/v1"}],"paths":{"/custom/trace":{"post":{"summary":"Custom Transaction Simulation","description":"Simulate custom transaction parameters and return execution trace","parameters":[{"name":"API-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomTransactionRequest"}}}},"responses":{"200":{"description":"Simulation result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulationTraceResponse"}}}}}}}},"components":{"schemas":{"CustomTransactionRequest":{"type":"object","required":["chainId","transaction"],"properties":{"chainId":{"type":"integer","format":"uint64","description":"Chain ID for the transaction"},"blockNumber":{"type":"integer","format":"uint64","description":"The block number on which the transaction simulation is based. If this value is 0, transaction simulation will be based on the latest block."},"transaction":{"type":"object","required":["sender","receiver","gasLimit","gasPrice","value","input"],"properties":{"sender":{"type":"string","description":"Transaction sender address"},"receiver":{"type":"string","description":"Transaction recipient address"},"gasLimit":{"type":"integer","format":"uint64","description":"Maximum gas allowed for transaction.  If this value is zero, then the simulation will be based on the gasLimit returned by eth_estimateGas."},"gasPrice":{"type":"string","pattern":"^\\d+$","description":"Gas price in wei (as integer string). If this value is zero, then the simulation will be based on the gasPrice returned by eth_gasPrice."},"value":{"type":"string","pattern":"^\\d+$","description":"Transaction value in wei (as integer string)"},"input":{"type":"string","description":"Transaction calldata in hex format"}}}}},"SimulationTraceResponse":{"type":"object","required":["code","message","data"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/TransactionTraceData"}}},"TransactionTraceData":{"allOf":[{"$ref":"#/components/schemas/TransactionData"},{"type":"object","properties":{"trace":{"$ref":"#/components/schemas/Call"}},"required":["trace"]}]},"TransactionData":{"type":"object","required":["status","blockNumber","txnHash","sender","receiver","timestamp","callData","gasLimit","gasPrice","gasUsed","baseFee","transactionFee","nonce","value","errorInfo","balanceChanges","viewLink"],"properties":{"status":{"type":"boolean","description":"Transaction execution status (true/false)"},"blockNumber":{"type":"integer","format":"uint64","description":"Block number"},"txnHash":{"type":"string","description":"Transaction hash"},"sender":{"type":"string","description":"Transaction initiator address"},"receiver":{"type":"string","description":"Transaction recipient address"},"timestamp":{"type":"string","format":"date-time","description":"Transaction timestamp"},"callData":{"type":"string","description":"Transaction calldata in hex format"},"gasLimit":{"type":"integer","format":"uint64","description":"Maximum gas allowed for transaction"},"gasPrice":{"type":"string","pattern":"^\\d+$","description":"Gas price in wei (as integer string)"},"gasUsed":{"type":"integer","format":"uint64","description":"Actual gas used in the transaction"},"baseFee":{"type":"string","pattern":"^\\d+$","description":"Base fee for EIP-1559 transactions in wei (as integer string)"},"transactionFee":{"type":"string","pattern":"^\\d+$","description":"Total transaction fee in wei (as integer string)"},"nonce":{"type":"integer","format":"uint64","description":"Sender's nonce (equal to number of transactions sent by sender)"},"value":{"type":"string","pattern":"^\\d+$","description":"Transaction value in wei (as integer string)"},"errorInfo":{"type":"string","description":"Error information when status is false"},"balanceChanges":{"type":"array","items":{"$ref":"#/components/schemas/BalanceChange"},"description":"List of account balance changes"},"viewLink":{"type":"string","description":"Phalcon Explorer view link for the transaction simulation"}}},"BalanceChange":{"type":"object","required":["account","assets"],"properties":{"account":{"type":"string","description":"Account address (asset holder)"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/Asset"},"description":"List of asset changes"}}},"Asset":{"type":"object","required":["address","tokenId","rawAmount","amount","iconUrl","isERC1155","isERC721","sign","value"],"properties":{"address":{"type":"string","description":"Token contract address"},"tokenId":{"type":"string","description":"Token ID for ERC721/ERC1155 (empty string for ERC20)"},"rawAmount":{"type":"string","pattern":"^\\d+$","description":"Raw amount (unprocessed by decimals) as integer string"},"amount":{"type":"string","description":"Formatted amount (rawAmount / 10^decimals), empty if decimals missing"},"iconUrl":{"type":"string","description":"URL for token icon (empty if unavailable)"},"isERC1155":{"type":"boolean","description":"Indicates ERC1155 token"},"isERC721":{"type":"boolean","description":"Indicates ERC721 token"},"sign":{"type":"boolean","description":"Indicates sign of rawAmount/amount (positive/negative)"},"value":{"type":"string","description":"USD value of asset in decimal format.\nEmpty if missing token price or decimals information.\nExamples: \n- \"22.94604\" (with USD value)\n- \"\" (no pricing data)\n"}}},"Call":{"type":"object","description":"Represents a single EVM execution step, including nested calls and logs.","properties":{"id":{"type":"integer","description":"Represents the execution order of the transaction."},"status":{"type":"boolean","description":"Execution status of the call (true if successful, false otherwise)."},"error":{"type":"string","description":"Error message when the call failed (empty if successful)."},"type":{"type":"string","description":"Type of call (e.g., CALL, DELEGATECALL, STATICCALL, CREATE, CREATE2)."},"from":{"type":"string","description":"Address of the caller (sender of this call)."},"to":{"type":"string","description":"Address of the callee (recipient of this call)."},"value":{"type":"string","description":"ETH value (in wei) transferred in this call."},"input":{"type":"string","description":"Input calldata (hex-encoded) provided to this call."},"output":{"type":"string","description":"Return data (hex-encoded) produced by this call."},"gasLimit":{"type":"integer","format":"uint64","description":"Gas provided for this call."},"gasUsed":{"type":"integer","format":"uint64","description":"Actual gas consumed by this call."},"calls":{"type":"array","description":"Nested sub-calls triggered during this call.","items":{"$ref":"#/components/schemas/Call"}},"logs":{"type":"array","description":"Logs emitted during this call.","items":{"$ref":"#/components/schemas/Log"}}}},"Log":{"type":"object","description":"Represents an Ethereum log event emitted during execution.","properties":{"id":{"type":"integer","description":"Represents the execution order of the transaction."},"address":{"type":"string","description":"Address of the contract that emitted the log."},"topics":{"type":"array","items":{"type":"string"},"description":"Indexed event topics (up to 4), hex-encoded."},"data":{"type":"string","description":"Non-indexed event data payload (hex-encoded)."}}}}}}
```