> ## 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 Honeypot Detection

> Multi-timestamp honeypot analysis that catches time-delayed tax traps, blacklists, and trading controls

## Overview

Most honeypot detectors only check a token at the current moment.
TxShield's honeypot endpoint runs **time-travel analysis** — simulating
the token's behavior across three future time windows to catch traps that
activate after launch.

A token can show 0% tax right now and 99% sell tax 24 hours later.
That's a time-delayed honeypot, and standard checks miss it entirely.

***

## Endpoint

**`POST`** `/api/honeypot/honeypot-checks`

***

## 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 contract address to analyze              |
| `chainId`               | `number` | ✅        | Chain to run the check on. See supported IDs below |

### Supported Chain IDs

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

***

## Response

```json theme={null}
{
  "success": true,
  "honeypotResponse": {
    "riskScore": 0,
    "buyTax": 0,
    "sellTax": 0,
    "isTimeHoneypot": false,
    "errorReason": "",
    "timeTravelResults": [
      {
        "label": "Immediate",
        "isBlackListDetected": false,
        "isMintable": false,
        "mintScore": 0,
        "mintReason": "",
        "isTradingControl": false,
        "buyTax": 0,
        "sellTax": 0,
        "riskScore": 0,
        "errorReason": ""
      },
      {
        "label": "24 Hours",
        "isBlackListDetected": false,
        "isMintable": false,
        "mintScore": 0,
        "mintReason": "",
        "isTradingControl": false,
        "buyTax": 0,
        "sellTax": 0,
        "riskScore": 0,
        "errorReason": ""
      },
      {
        "label": "7 Days",
        "isBlackListDetected": false,
        "isMintable": false,
        "mintScore": 0,
        "mintReason": "",
        "isTradingControl": false,
        "buyTax": 0,
        "sellTax": 0,
        "riskScore": 0,
        "errorReason": ""
      }
    ]
  }
}
```

***

## Response Fields Explained

### Top Level

| Field              | Type      | Description                              |
| ------------------ | --------- | ---------------------------------------- |
| `success`          | `boolean` | Whether the request succeeded            |
| `honeypotResponse` | `object`  | Container for all honeypot analysis data |

***

### `honeypotResponse`

| Field               | Type      | Description                                                        |
| ------------------- | --------- | ------------------------------------------------------------------ |
| `riskScore`         | `number`  | Overall risk score from `0` to `100`. Above `70` is high risk      |
| `buyTax`            | `number`  | Current buy tax percentage                                         |
| `sellTax`           | `number`  | Current sell tax percentage                                        |
| `isTimeHoneypot`    | `boolean` | `true` if tax or risk increases across time windows — the key flag |
| `errorReason`       | `string`  | Populated when analysis partially fails or detects a specific trap |
| `timeTravelResults` | `array`   | Analysis results across three simulated time windows               |

***

### `timeTravelResults[]` — Each Time Window

| Field                 | Type      | Description                                                    |
| --------------------- | --------- | -------------------------------------------------------------- |
| `label`               | `string`  | Time window: `"Immediate"`, `"24 Hours"`, or `"7 Days"`        |
| `buyTax`              | `number`  | Buy tax at this simulated time                                 |
| `sellTax`             | `number`  | Sell tax at this simulated time                                |
| `riskScore`           | `number`  | Risk score at this simulated time                              |
| `isBlackListDetected` | `boolean` | Whether blacklist functionality was detected at this window    |
| `isMintable`          | `boolean` | Whether the contract can mint new tokens at this window        |
| `mintScore`           | `number`  | Confidence score for mint risk. Higher = more dangerous        |
| `mintReason`          | `string`  | Explanation if mint risk is detected                           |
| `isTradingControl`    | `boolean` | Whether the owner can pause or restrict trading at this window |
| `errorReason`         | `string`  | Specific error or finding for this time window                 |

***

## How to Read the Results

### The Safe Token

```json theme={null}
{
  "riskScore": 0,
  "buyTax": 0,
  "sellTax": 0,
  "isTimeHoneypot": false,
  "timeTravelResults": [
    { "label": "Immediate", "buyTax": 0, "sellTax": 0, "riskScore": 0 },
    { "label": "24 Hours",  "buyTax": 0, "sellTax": 0, "riskScore": 0 },
    { "label": "7 Days",    "buyTax": 0, "sellTax": 0, "riskScore": 0 }
  ]
}
```

All three windows consistent. No flags. Safe to proceed.

***

### The Time-Delayed Honeypot

```json theme={null}
{
  "riskScore": 92,
  "buyTax": 3,
  "sellTax": 15,
  "isTimeHoneypot": true,
  "errorReason": "Tax spikes dramatically after 24 hours",
  "timeTravelResults": [
    { "label": "Immediate", "buyTax": 3,  "sellTax": 15, "riskScore": 45  },
    { "label": "24 Hours",  "buyTax": 3,  "sellTax": 99, "riskScore": 100 },
    { "label": "7 Days",    "buyTax": 3,  "sellTax": 99, "riskScore": 100 }
  ]
}
```

Looks tradeable right now. By 24 hours, sell tax hits 99% —
users are trapped. `isTimeHoneypot: true` is your block signal.

***

### The Blacklist Trap

```json theme={null}
{
  "riskScore": 75,
  "buyTax": 5,
  "sellTax": 5,
  "isTimeHoneypot": false,
  "timeTravelResults": [
    { "label": "Immediate", "isBlackListDetected": false, "riskScore": 20 },
    { "label": "24 Hours",  "isBlackListDetected": true,  "riskScore": 75 },
    { "label": "7 Days",    "isBlackListDetected": true,  "riskScore": 75 }
  ]
}
```

Tax looks fine. But blacklist activates at 24 hours —
owner can block any wallet from selling at any time.

***

## Risk Score Reference

| Score      | Verdict       | Recommended Action                   |
| ---------- | ------------- | ------------------------------------ |
| `0 – 20`   | Safe          | Proceed normally                     |
| `21 – 50`  | Low Risk      | Proceed with caution                 |
| `51 – 70`  | Medium Risk   | Warn user, show flags                |
| `71 – 90`  | High Risk     | Strong warning, require confirmation |
| `91 – 100` | Critical Risk | Block the transaction                |

<Note>
  Always check `isTimeHoneypot` alongside `riskScore`. A token can have a
  moderate score at the `"Immediate"` window but become Critical Risk by
  `"7 Days"`. The time-travel delta is the most important signal.
</Note>

***

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.txshield.xyz/api/honeypot/honeypot-checks \
    -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/honeypot/honeypot-checks',
    {
      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();
  const { honeypotResponse } = data;

  // Recommended block logic
  const shouldBlock =
    honeypotResponse.isTimeHoneypot ||
    honeypotResponse.riskScore > 70 ||
    honeypotResponse.timeTravelResults.some(
      (r) => r.isBlackListDetected || r.isTradingControl
    );

  if (shouldBlock) {
    console.warn('HIGH RISK TOKEN — block or warn user');
  }
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://api.txshield.xyz/api/honeypot/honeypot-checks",
      headers={
          "Content-Type": "application/json",
          "Authorization": "Bearer txs_your_api_key_here"
      },
      json={
          "targetContractAddress": "0x3e391e5cb8ea766c93134faf486e6393158032c2",
          "chainId": 1
      }
  )

  data = res.json()
  hp = data["honeypotResponse"]

  if hp["isTimeHoneypot"] or hp["riskScore"] > 70:
      print(f"BLOCK: riskScore={hp['riskScore']}, timeHoneypot={hp['isTimeHoneypot']}")
  ```
</CodeGroup>

***

## 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`  | `Honeypot check failed`             | Internal error or RPC failure |

***

<CardGroup cols={2}>
  <Card title="EVM Simulation" icon="flask" href="/evm-simulation-copied-1">
    Run a full simulation with bytecode analysis alongside honeypot detection.
  </Card>

  <Card title="Authentication" icon="lock" href="/authentication">
    How to generate and use your API key.
  </Card>
</CardGroup>