Transaction Simulation API

Understand a transactoin before signing it

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 and Fireblocks 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

Get started Fill out the form to receive your API key and start simulating in minutes.

Balance Change

Raw Transaction Simulation

post

Simulate raw transaction and get balance changes

Header parameters

API-KeystringRequired

Body

application/json

blockNumberinteger · uint64Required

The block number on which the transaction simulation is based. If this value is 0, transaction simulation will be based on the latest block.

transactionstringRequired

Raw transaction hex string

Example: 0xf8a91f85017ad70c7582881994c02aaa39b223fe8d0a0e5c4f27ead9083c756cc280b844a9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000005af3107a400025a0bbfc1f56c70c58f623a36639f9dd01db632af5bdc1106c16906f6c13b17765cea07a34be3f43332eddbcb9ac8a3b1e261eda25c007283a645d68a8380b19e6602f

Responses

200

Simulation result

application/json

post

/raw/balancechange

HTTPcURLJavaScriptPython

POST /simulation/v1/raw/balancechange HTTP/1.1
Host: api.blocksec.com
API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 385

{
  "blockNumber": 22467376,
  "transaction": "0xf8a91f85017ad70c7582881994c02aaa39b223fe8d0a0e5c4f27ead9083c756cc280b844a9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000005af3107a400025a0bbfc1f56c70c58f623a36639f9dd01db632af5bdc1106c16906f6c13b17765cea07a34be3f43332eddbcb9ac8a3b1e261eda25c007283a645d68a8380b19e6602f"
}

200

Simulation result

{
  "code": 0,
  "message": "success",
  "data": {
    "status": true,
    "blockNumber": 22467376,
    "txnHash": "0x5466e564db157b73cbd8dd1d688631a3afcf99a35c372009d8c298441fa8d9e0",
    "sender": "0x989e7947a9d9210eec3a41dcf5f536bb1d7726f6",
    "receiver": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "timestamp": "2025-05-12T13:03:23Z",
    "callData": "0xa9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000005af3107a4000",
    "gasLimit": 34841,
    "gasPrice": "6355881077",
    "gasUsed": 34482,
    "baseFee": "6029791982",
    "transactionFee": "219163491297114",
    "nonce": 31,
    "value": "0",
    "errorInfo": "",
    "viewLink": "https://app.blocksec.com/explorer/tx/eth/0x5466e564db157b73cbd8dd1d688631a3afcf99a35c372009d8c298441fa8d9e0?event=simulator",
    "balanceChanges": [
      {
        "account": "0x989e7947a9d9210eec3a41dcf5f536bb1d7726f6",
        "assets": [
          {
            "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "tokenId": "",
            "rawAmount": "100000000000000",
            "amount": "0.0001",
            "value": "0.255386",
            "iconUrl": "https://assets.blocksec.com/icon/f1cb2d02c471d545bbc7722daf3277fd852d98e63d118771af7047bd8256c516.png",
            "isERC721": false,
            "isERC1155": false,
            "sign": false
          }
        ]
      },
      {
        "account": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
        "assets": [
          {
            "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "tokenId": "",
            "rawAmount": "100000000000000",
            "amount": "0.0001",
            "value": "0.255386",
            "iconUrl": "https://assets.blocksec.com/icon/f1cb2d02c471d545bbc7722daf3277fd852d98e63d118771af7047bd8256c516.png",
            "isERC721": false,
            "isERC1155": false,
            "sign": true
          }
        ]
      }
    ]
  }
}

Custom Transaction Simulation

post

Simulate custom transaction parameters and get balance changes

Header parameters

API-KeystringRequired

Body

application/json

chainIdinteger · uint64Required

Chain ID for the transaction

blockNumberinteger · uint64Optional

The block number on which the transaction simulation is based. If this value is 0, transaction simulation will be based on the latest block.

Responses

200

Simulation result

application/json

post

/custom/balancechange

HTTPcURLJavaScriptPython

POST /simulation/v1/custom/balancechange HTTP/1.1
Host: api.blocksec.com
API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 240

{
  "chainId": 1,
  "blockNumber": 0,
  "transaction": {
    "sender": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "receiver": "0x761A8482CE9EBa5baCBc20CDd869D4AA00275F8f",
    "gasLimit": 21000,
    "gasPrice": "20634341671000",
    "value": "9000000000000000",
    "input": "0x"
  }
}

200

Simulation result

{
  "code": 0,
  "message": "",
  "data": {
    "status": true,
    "blockNumber": 22467282,
    "txnHash": "0x80407f7f2c695c82847bdbdecac4070274523bcbc0b9fa3493afb06ee7709813",
    "sender": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
    "receiver": "0x761a8482ce9eba5bacbc20cdd869d4aa00275f8f",
    "timestamp": "2025-05-12T12:44:35Z",
    "callData": "0x",
    "gasLimit": 21000,
    "gasPrice": "20634341671000",
    "gasUsed": 21000,
    "baseFee": "7094316180",
    "transactionFee": "433321175091000000",
    "nonce": 1555,
    "value": "9000000000000000",
    "errorInfo": "",
    "viewLink": "https://app.blocksec.com/explorer/tx/eth/0x80407f7f2c695c82847bdbdecac4070274523bcbc0b9fa3493afb06ee7709813?event=simulator",
    "balanceChanges": [
      {
        "account": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
        "assets": [
          {
            "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
            "tokenId": "",
            "rawAmount": "9000000000000000",
            "amount": "0.009",
            "value": "22.94604",
            "iconUrl": "https://assets.blocksec.com/image/1663669189317-3.png",
            "isERC721": false,
            "isERC1155": false,
            "sign": false
          }
        ]
      },
      {
        "account": "0x761a8482ce9eba5bacbc20cdd869d4aa00275f8f",
        "assets": [
          {
            "address": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
            "tokenId": "",
            "rawAmount": "9000000000000000",
            "amount": "0.009",
            "value": "22.94604",
            "iconUrl": "https://assets.blocksec.com/image/1663669189317-3.png",
            "isERC721": false,
            "isERC1155": false,
            "sign": true
          }
        ]
      }
    ]
  }
}

Trace

Raw Transaction Simulation

post

Simulate raw transaction and return execution trace

Header parameters

API-KeystringRequired

Body

application/json

blockNumberinteger · uint64Required

The block number on which the transaction simulation is based. If this value is 0, transaction simulation will be based on the latest block.

transactionstringRequired

Raw transaction hex string

Example: 0xf8a91f85017ad70c7582881994c02aaa39b223fe8d0a0e5c4f27ead9083c756cc280b844a9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000005af3107a400025a0bbfc1f56c70c58f623a36639f9dd01db632af5bdc1106c16906f6c13b17765cea07a34be3f43332eddbcb9ac8a3b1e261eda25c007283a645d68a8380b19e6602f

Responses

200

Simulation result with trace

application/json

post

/raw/trace

HTTPcURLJavaScriptPython

POST /simulation/v1/raw/trace HTTP/1.1
Host: api.blocksec.com
API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 385

{
  "blockNumber": 22467376,
  "transaction": "0xf8a91f85017ad70c7582881994c02aaa39b223fe8d0a0e5c4f27ead9083c756cc280b844a9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000005af3107a400025a0bbfc1f56c70c58f623a36639f9dd01db632af5bdc1106c16906f6c13b17765cea07a34be3f43332eddbcb9ac8a3b1e261eda25c007283a645d68a8380b19e6602f"
}

200

Simulation result with trace

{
  "code": 0,
  "message": "success",
  "data": {
    "status": true,
    "blockNumber": 22467376,
    "txnHash": "0x5466e564db157b73cbd8dd1d688631a3afcf99a35c372009d8c298441fa8d9e0",
    "sender": "0x989e7947a9d9210eec3a41dcf5f536bb1d7726f6",
    "receiver": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "timestamp": "2025-05-12T13:03:23Z",
    "callData": "0xa9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000005af3107a4000",
    "gasLimit": 34841,
    "gasPrice": "6355881077",
    "gasUsed": 34482,
    "baseFee": "6029791982",
    "transactionFee": "219163491297114",
    "nonce": 31,
    "value": "0",
    "errorInfo": "",
    "viewLink": "https://app.blocksec.com/explorer/tx/eth/0x5466e564db157b73cbd8dd1d688631a3afcf99a35c372009d8c298441fa8d9e0?event=simulator",
    "balanceChanges": [
      {
        "account": "0x989e7947a9d9210eec3a41dcf5f536bb1d7726f6",
        "assets": [
          {
            "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "tokenId": "",
            "rawAmount": "100000000000000",
            "amount": "0.0001",
            "value": "0.255386",
            "iconUrl": "https://assets.blocksec.com/icon/f1cb2d02c471d545bbc7722daf3277fd852d98e63d118771af7047bd8256c516.png",
            "isERC721": false,
            "isERC1155": false,
            "sign": false
          }
        ]
      },
      {
        "account": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
        "assets": [
          {
            "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "tokenId": "",
            "rawAmount": "100000000000000",
            "amount": "0.0001",
            "value": "0.255386",
            "iconUrl": "https://assets.blocksec.com/icon/f1cb2d02c471d545bbc7722daf3277fd852d98e63d118771af7047bd8256c516.png",
            "isERC721": false,
            "isERC1155": false,
            "sign": true
          }
        ]
      }
    ],
    "trace": {
      "id": 0,
      "status": true,
      "error": "",
      "type": "CALL",
      "from": "0x989e7947a9d9210eec3a41dcf5f536bb1d7726f6",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "value": "0",
      "input": "0xa9059cbb000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa9604500000000000000000000000000000000000000000000000000005af3107a4000",
      "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "gasLimit": 34841,
      "gasUsed": 34482,
      "calls": [],
      "logs": [
        {
          "id": 1,
          "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "topics": [
            "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
            "0x000000000000000000000000989e7947a9d9210eec3a41dcf5f536bb1d7726f6",
            "0x000000000000000000000000d8da6bf26964af9d7eed9e03e53415d37aa96045"
          ],
          "data": "0x00000000000000000000000000000000000000000000000000005af3107a4000"
        }
      ]
    }
  }
}

Custom Transaction Simulation

post

Simulate custom transaction parameters and return execution trace

Header parameters

API-KeystringRequired

Body

application/json

chainIdinteger · uint64Required

Chain ID for the transaction

blockNumberinteger · uint64Optional

The block number on which the transaction simulation is based. If this value is 0, transaction simulation will be based on the latest block.

Responses

200

Simulation result

application/json

post

/custom/trace

HTTPcURLJavaScriptPython

POST /simulation/v1/custom/trace HTTP/1.1
Host: api.blocksec.com
API-Key: text
Content-Type: application/json
Accept: */*
Content-Length: 357

{
  "chainId": 1,
  "blockNumber": 0,
  "transaction": {
    "sender": "0x954DC257783e94C47d84F061f06B211639722fEf",
    "receiver": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "gasLimit": 46422,
    "gasPrice": "4983799558",
    "value": "0",
    "input": "0x095ea7b3000000000000000000000000881d40237659c251811cec9c364ef91dc08d300c000000000000000000000000000000000000000000000000002386f26fc10000"
  }
}

200

Simulation result

{
  "code": 0,
  "message": "",
  "data": {
    "status": true,
    "blockNumber": 23390043,
    "txnHash": "0xa396b5cb4508481afc5f27c731892ffe0269a252cb81485301e23bc02f2704b2",
    "sender": "0x954dc257783e94c47d84f061f06b211639722fef",
    "receiver": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
    "timestamp": "2025-09-18T12:44:35Z",
    "callData": "0x095ea7b3000000000000000000000000881d40237659c251811cec9c364ef91dc08d300c000000000000000000000000000000000000000000000000002386f26fc10000",
    "gasLimit": 46422,
    "gasPrice": "4983799558",
    "gasUsed": 46040,
    "baseFee": "3133777897",
    "transactionFee": "229454131650320",
    "nonce": 25,
    "value": "0",
    "errorInfo": "",
    "viewLink": "https://app.blocksec.com/explorer/tx/eth/0x6dd98e2eabf7f395b57678901a4dddaa25026c0e935109284e2bcf1ee2b44d0e?event=simulator",
    "balanceChanges": [],
    "trace": {
      "id": 0,
      "status": true,
      "error": "",
      "type": "CALL",
      "from": "0x954dc257783e94c47d84f061f06b211639722fef",
      "to": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
      "value": "0",
      "input": "0x095ea7b3000000000000000000000000881d40237659c251811cec9c364ef91dc08d300c000000000000000000000000000000000000000000000000002386f26fc10000",
      "output": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "gasLimit": 46422,
      "gasUsed": 46040,
      "calls": [],
      "logs": [
        {
          "id": 1,
          "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "topics": [
            "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
            "0x000000000000000000000000954dc257783e94c47d84f061f06b211639722fef",
            "0x000000000000000000000000881d40237659c251811cec9c364ef91dc08d300c"
          ],
          "data": "0x000000000000000000000000000000000000000000000000002386f26fc10000"
        }
      ]
    }
  }
}