> ## 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.
# EVM Simulation
> Simulate any EVM token interaction and get a full risk report before the transaction is signed
## 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
```json theme={null}
{
"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
```json theme={null}
{
"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
```bash cURL theme={null}
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
}'
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://api.txshield.xyz/api/simulate/execute-simulation',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer txs_your_api_key_here'
},
body: JSON.stringify({
targetContractAddress: "0x3e391e5cb8ea766c93134faf486e6393158032c2",
chainId: 1
})
}
);
const data = await response.json();
// Quick risk check pattern
if (!data.success) {
console.error('Request failed:', data.errorReason);
return;
}
const { simulateResult, byteCodeResult, transactionHistoryResult } = data.checks;
if (byteCodeResult.trustStatus === 'Critical Risk') {
console.warn('BLOCK THIS TRADE:', byteCodeResult.humanWarning);
}
if (simulateResult.isHoneypot || simulateResult.isReentrancy) {
console.warn('Simulation flagged risk');
}
```
```python Python theme={null}
import requests
res = requests.post(
"https://api.txshield.xyz/api/simulate/execute-simulation",
headers={
"Content-Type": "application/json",
"Authorization": "Bearer txs_your_api_key_here"
},
json={
"targetContractAddress": "0x3e391e5cb8ea766c93134faf486e6393158032c2",
"chainId": 1
}
)
data = res.json()
bytecode = data["checks"]["byteCodeResult"]
if bytecode["trustStatus"] == "Critical Risk":
print("BLOCK:", bytecode["humanWarning"])
```
***
## 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 |
***
Run a dedicated honeypot check with time-travel analysis.
How to generate and use your API key.