Documentation Index Fetch the complete documentation index at: https://docs.txshield.xyz/llms.txt
Use this file to discover all available pages before exploring further.
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, reentrancyBytecode Analysis — static analysis for kill switches, proxies, and malicious patternsTransaction 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-simulationRequest Content-Type: application/json Authorization: Bearer txs_your_api_key_here
Body { "targetContractAddress" : "0x3e391e5cb8ea766c93134faf486e6393158032c2" , "chainId" : 1 }
Parameters Field Type Required Description targetContractAddressstring✅ The token or contract address to analyze chainIdnumber✅ The chain to run the simulation on. See supported chain IDs below
Supported Chain IDs Chain chainId Ethereum 1BNB Smart Chain 56Base 8453Arbitrum 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 successbooleanWhether the overall request succeeded checksobjectContainer for all three analysis results
checks.simulateResultField Type Description successbooleanWhether the simulation itself executed successfully ethDeltastringChange in ETH balance after the transaction. Negative = ETH spent tokenDeltastringChange in token balance in raw units (wei-scale). Negative = tokens spent isProfitbooleanWhether the user ends up with more value than they started with allowanceChangedbooleanWhether the transaction modifies a token allowance allowanceDeltastringThe change in allowance. "Unlimited" is a red flag estimatedTaxstringEstimated buy/sell tax as a percentage string gasUsedstringGas consumed by the simulated transaction isReentrancybooleanWhether reentrancy patterns were detected in execution isHoneypotbooleanWhether the simulation detected honeypot behaviour errorReasonstringPopulated when success is false. Human-readable failure reason simulatedAtstringISO timestamp of when the simulation was run watchedTokensstringComma-separated list of major token addresses monitored during simulation watchedTokensDeltasstringCorresponding balance deltas for each watched token simulation.callsarrayFull call trace of the simulated transaction simulation.logsarrayEvent logs emitted during the simulation
checks.byteCodeResultField Type Description isContractbooleanWhether the address is a contract or an EOA trustStatusstringOverall trust verdict. One of: Safe, Low Risk, Medium Risk, High Risk, Critical Risk humanWarningstringPlain-English summary of the most severe finding riskFlagsarrayList of individual risk findings riskFlags[].threatLevelstringHIGH, MEDIUM, or LOWriskFlags[].titlestringShort name of the detected risk riskFlags[].descriptionstringWhat this risk means for the user
checks.transactionHistoryResultField Type Description successbooleanWhether the history lookup succeeded activityPulsestringHuman-readable activity summary: Very Active, Active, Low Activity, Dead / No Activity messagestringPlain-English explanation of the activity status recentTransfersarrayRecent 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 400targetContractAddress is requiredMissing address in body 400chainId is requiredMissing chainId in body 401Missing Authorization headerNo API key provided 403Invalid API keyKey not found or revoked 429Analysis rate limit hitExceeded 10 req/min 500Simulation failedInternal error or RPC failure
Honeypot Detection Run a dedicated honeypot check with time-travel analysis.
Authentication How to generate and use your API key.
