EVM Simulation - TxShield API

Overview

The simulation endpoint is TxShield’s core. A single POST request runs three parallel checks against live chain state and returns a unified risk report:

Transaction Simulation — exact token and ETH deltas, tax, gas, reentrancy
Bytecode Analysis — static analysis for kill switches, proxies, and malicious patterns
Transaction History — activity pulse showing whether the token is alive or dead

Use this before presenting any swap or interaction to your user.

Endpoint

POST /api/simulate/execute-simulation

Request

Headers

Content-Type: application/json
Authorization: Bearer txs_your_api_key_here

Body

{
  "targetContractAddress": "0x3e391e5cb8ea766c93134faf486e6393158032c2",
  "chainId": 1
}

Parameters

Field	Type	Required	Description
`targetContractAddress`	`string`	✅	The token or contract address to analyze
`chainId`	`number`	✅	The chain to run the simulation on. See supported chain IDs below

Supported Chain IDs

Chain	chainId
Ethereum	`1`
BNB Smart Chain	`56`
Base	`8453`
Arbitrum	`42161`

Response

{
  "success": true,
  "checks": {
    "simulateResult": {
      "success": true,
      "ethDelta": "0",
      "tokenDelta": "-856779799660784235",
      "isProfit": true,
      "allowanceChanged": false,
      "allowanceDelta": "0",
      "errorReason": "",
      "returnData": "0x00000000000000000000000000000000...",
      "simulatedAt": "2026-03-29T05:49:59.625Z",
      "estimatedTax": "0",
      "gasUsed": "185464",
      "watchedTokens": "0xdAC17F958D2ee523a2206206994597C13D831ec7,...",
      "watchedTokensDeltas": "0,0,0,0",
      "isReentrancy": false,
      "isHoneypot": false,
      "simulation": {
        "calls": [
          {
            "type": "CALL",
            "from": "0x2d1468a9b827c6e1f5e91943dc3b0425d187993b",
            "to": "0x7a250d5630b4cf539739df2c5dacb4c659f2488d",
            "value": "0x5f5e100",
            "gas": "0xf4240",
            "gasUsed": "0x1dd80",
            "input": "0x7ff36ab5...",
            "output": "0x00000000..."
          }
        ],
        "logs": [
          {
            "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
            "data": "0x0000000000000000000000000000000000000000000000000000000005f5e100",
            "topics": [
              "0xe1fffcc4923d04b559f4d29a8bfc6cda04eb5b0d3c460751c2402c5c5cc9109c",
              "0x7a250d5630b4cf539739df2c5dacb4c659f2488d"
            ]
          }
        ]
      }
    },
    "byteCodeResult": {
      "isContract": true,
      "trustStatus": "Critical Risk",
      "humanWarning": "EXTREME DANGER: This contract contains a kill-switch or severely malicious logic.",
      "riskFlags": [
        {
          "threatLevel": "HIGH",
          "title": "Kill Switch Detected",
          "description": "The creator can delete this token at any time, instantly wiping its value."
        },
        {
          "threatLevel": "HIGH",
          "title": "Hidden Logic (Proxy)",
          "description": "The contract can execute code from other hidden contracts. Often used in scams to change rules after launch."
        },
        {
          "threatLevel": "MEDIUM",
          "title": "Dynamic Deployment",
          "description": "Can spawn new contracts on the fly."
        }
      ]
    },
    "transactionHistoryResult": {
      "success": true,
      "activityPulse": "Dead / No Activity",
      "message": "No recent token transfers found. If this is a new token, no one is trading it.",
      "recentTransfers": []
    }
  }
}

Response Fields Explained

Top Level

Field	Type	Description
`success`	`boolean`	Whether the overall request succeeded
`checks`	`object`	Container for all three analysis results

`checks.simulateResult`

Field	Type	Description
`success`	`boolean`	Whether the simulation itself executed successfully
`ethDelta`	`string`	Change in ETH balance after the transaction. Negative = ETH spent
`tokenDelta`	`string`	Change in token balance in raw units (wei-scale). Negative = tokens spent
`isProfit`	`boolean`	Whether the user ends up with more value than they started with
`allowanceChanged`	`boolean`	Whether the transaction modifies a token allowance
`allowanceDelta`	`string`	The change in allowance. `"Unlimited"` is a red flag
`estimatedTax`	`string`	Estimated buy/sell tax as a percentage string
`gasUsed`	`string`	Gas consumed by the simulated transaction
`isReentrancy`	`boolean`	Whether reentrancy patterns were detected in execution
`isHoneypot`	`boolean`	Whether the simulation detected honeypot behaviour
`errorReason`	`string`	Populated when `success` is false. Human-readable failure reason
`simulatedAt`	`string`	ISO timestamp of when the simulation was run
`watchedTokens`	`string`	Comma-separated list of major token addresses monitored during simulation
`watchedTokensDeltas`	`string`	Corresponding balance deltas for each watched token
`simulation.calls`	`array`	Full call trace of the simulated transaction
`simulation.logs`	`array`	Event logs emitted during the simulation

`checks.byteCodeResult`

Field	Type	Description
`isContract`	`boolean`	Whether the address is a contract or an EOA
`trustStatus`	`string`	Overall trust verdict. One of: `Safe`, `Low Risk`, `Medium Risk`, `High Risk`, `Critical Risk`
`humanWarning`	`string`	Plain-English summary of the most severe finding
`riskFlags`	`array`	List of individual risk findings
`riskFlags[].threatLevel`	`string`	`HIGH`, `MEDIUM`, or `LOW`
`riskFlags[].title`	`string`	Short name of the detected risk
`riskFlags[].description`	`string`	What this risk means for the user

`checks.transactionHistoryResult`

Field	Type	Description
`success`	`boolean`	Whether the history lookup succeeded
`activityPulse`	`string`	Human-readable activity summary: `Very Active`, `Active`, `Low Activity`, `Dead / No Activity`
`message`	`string`	Plain-English explanation of the activity status
`recentTransfers`	`array`	Recent transfer events for the token

Important: Read All Three Results

A token can simulate cleanly — isHoneypot: false, success: true — and still be dangerous. Always check byteCodeResult.trustStatus and byteCodeResult.riskFlags independently. A Kill Switch or Proxy pattern in the bytecode means the contract rules can change after you trade.

The example response above is a real case — simulation passed, but bytecode flagged a Kill Switch and Hidden Logic. A user trusting only isHoneypot would have traded into a Critical Risk contract.

Code Examples

curl -X POST https://api.txshield.xyz/api/simulate/execute-simulation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer txs_your_api_key_here" \
  -d '{
    "targetContractAddress": "0x3e391e5cb8ea766c93134faf486e6393158032c2",
    "chainId": 1
  }'

Error Responses

Status	Error	Meaning
`400`	`targetContractAddress is required`	Missing address in body
`400`	`chainId is required`	Missing chainId in body
`401`	`Missing Authorization header`	No API key provided
`403`	`Invalid API key`	Key not found or revoked
`429`	`Analysis rate limit hit`	Exceeded 10 req/min
`500`	`Simulation failed`	Internal error or RPC failure

Honeypot Detection

Run a dedicated honeypot check with time-travel analysis.

Authentication

How to generate and use your API key.

​Overview

​Endpoint

​Request

​Headers

​Body

​Parameters

​Supported Chain IDs

​Response

​Response Fields Explained

​Top Level

​checks.simulateResult

​checks.byteCodeResult

​checks.transactionHistoryResult

​Important: Read All Three Results

​Code Examples

​Error Responses

Honeypot Detection

Authentication

Overview

Endpoint

Request

Headers

Body

Parameters

Supported Chain IDs

Response

Response Fields Explained

Top Level

`checks.simulateResult`

`checks.byteCodeResult`

`checks.transactionHistoryResult`

Important: Read All Three Results

Code Examples

Error Responses