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 · Story · Story Aeneid Testnet

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

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

enableCodeOverwritebooleanOptional

Enable Safe-signature-bypass for the simulation. Defaults to false.

overwriteAddressesstring[]Optional

Addresses on which Safe-signature-bypass should be applied. Only used when enableCodeOverwrite is true. Duplicates are ignored. If omitted or empty, falls back to the top-level tx.to decoded from the raw transaction; for contract-creation transactions nothing is applied.

Responses

200

Simulation result

application/json

codeinteger · enumRequired

Status codes:

0: Success
1: Unexpected error (contact [email protected])
2: Invalid request body format
3: Invalid raw transaction
4: Unsupported chain ID
5: Chain-gateway error (contact [email protected])
6: RPC node error (contact [email protected])
7: Invalid chain ID
8: The check of transaction simulation failed

Possible values:

messagestringRequired

Human-readable description of the status code

post

/raw/balancechange

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

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.

enableCodeOverwritebooleanOptional

Enable Safe-signature-bypass for the simulation. Defaults to false.

overwriteAddressesstring[]Optional

Addresses on which Safe-signature-bypass should be applied. Only used when enableCodeOverwrite is true. Duplicates are ignored. If omitted or empty, falls back to transaction.receiver.

Responses

200

Simulation result

application/json

codeinteger · enumRequired

Status codes:

0: Success
1: Unexpected error (contact [email protected])
2: Invalid request body format
3: Invalid raw transaction
4: Unsupported chain ID
5: Chain-gateway error (contact [email protected])
6: RPC node error (contact [email protected])
7: Invalid chain ID
8: The check of transaction simulation failed

Possible values:

messagestringRequired

Human-readable description of the status code

post

/custom/balancechange

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

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

enableCodeOverwritebooleanOptional

Enable Safe-signature-bypass for the simulation. Defaults to false.

overwriteAddressesstring[]Optional

Responses

200

Simulation result with trace

application/json

codeinteger · int32Required

messagestringRequired

post

/raw/trace

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

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.

enableCodeOverwritebooleanOptional

Enable Safe-signature-bypass for the simulation. Defaults to false.

overwriteAddressesstring[]Optional

Addresses on which Safe-signature-bypass should be applied. Only used when enableCodeOverwrite is true. Duplicates are ignored. If omitted or empty, falls back to transaction.receiver.

Responses

200

Simulation result

application/json

codeinteger · int32Required

messagestringRequired

post

/custom/trace

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"
        }
      ]
    }
  }
}

PreviousAvoid Being a Phishing Victim NextOverview

Last updated 2 days ago

hashtagBalance Change

hashtagRaw Transaction Simulation

hashtagCustom Transaction Simulation

hashtagTrace

hashtagRaw Transaction Simulation

hashtagCustom Transaction Simulation

Balance Change

Raw Transaction Simulation

Custom Transaction Simulation

Trace

Raw Transaction Simulation

Custom Transaction Simulation