# HoneyCheck

This tool detects honeypot tokens on decentralized exchanges (DEXes) by simulating the behavior of a trader participating in a Pump-and-Dump operation. It forks the blockchain state at a target block using [Anvil](https://book.getfoundry.sh/anvil/), simulates a buy followed by a sell, and evaluates whether both transactions execute successfully and whether the received assets are consistent with the exchange rates implied by the liquidity pool's pricing formula. A reversion of the sell swap, or a deviation from the expected outputs, indicates the presence of trade restriction logic in the token's smart contract.

## Supported Chains

| Chain | DEX | Native asset |
|---|---|---|
| `bsc` | PancakeSwap V2 | BNB |
| `eth` | Uniswap V2 | ETH |

## Requirements

- Python 3.8+
- [Foundry](https://book.getfoundry.sh/getting-started/installation) (provides the `anvil` command)
- An archive node RPC endpoint for the target chain (e.g. [QuickNode](https://www.quicknode.com/), [Alchemy](https://www.alchemy.com/))

Install Python dependencies:

```bash
pip install web3 eth-abi
```

## Usage

### Step 1 — Start Anvil

Before running the simulation, start Anvil forked at the target block:

```bash
anvil --fork-url <ARCHIVE_RPC_URL> --fork-block-number <BLOCK> --port 8545
```

Replace `<ARCHIVE_RPC_URL>` with your archive node endpoint and `<BLOCK>` with the block height at which you want to simulate the trades (typically the block corresponding to the start of the Pump-and-Dump event).

### Step 2 — Run the simulation

```
python3 honeypot_detector.py \
  --chain   <bsc|eth>         \
  --token   <TOKEN_ADDRESS>   \
  --pair    <PAIR_ADDRESS>    \
  --block   <BLOCK_NUMBER>    \
  [--amount-in <AMOUNT>]      \
  [--tau <BLOCKS>]            
```

#### Arguments

| Argument | Required | Default | Description |
|---|---|---|---|
| `--chain` | Yes | — | Chain to simulate on: `bsc` or `eth` |
| `--token` | Yes | — | Address of the token to simulate |
| `--pair` | Yes | — | Address of the liquidity pool (used for logging) |
| `--block` | Yes | — | Block height to fork the state at |
| `--amount-in` | No | `0.01` | Amount of native asset (in ETH/BNB) to use for the buy |
| `--tau` | No | `1` | Number of blocks to advance between buy and sell (see note below) |

> **Note on `--tau`**: Some honeypot tokens implement anti-simulation mechanisms that allow a sell only if executed immediately after the buy (within the same block or a few seconds). Setting `--tau 0` replicates the behavior of naive detection tools that execute buy and sell in rapid succession; increasing `--tau` replicates the conditions under which a real trader would operate, revealing these hidden restrictions.

### Output

The tool prints a JSON object with the following fields:

| Field | Description |
|---|---|
| `verdict` | `HONEYPOT` or `CLEAN` |
| `buy_tax` | Buy-side tax as a percentage: `(β_exp - β_act) / β_exp × 100` |
| `sell_tax` | Sell-side tax as a percentage: `(σ_exp - σ_act) / σ_exp × 100` |
| `buy_theoretical` | Expected token amount from the AMM formula (β_exp) |
| `beta_act` | Actual token amount received after the buy (β_act) |
| `sell_theoretical` | Expected native asset amount from the AMM formula (σ_exp) |
| `sigma_act` | Actual native asset amount received after the sell (σ_act) |
| `error` | Error code if the simulation could not complete (e.g. `sell_reverted`, `approve_reverted`, `no_tokens_received`) |

## Examples

**Sell reverted** — the token's smart contract blocks the sell swap outright:
```bash
python3 honeypot_detector.py \
  --token 0x7503746b7b8c0e0590c9d0f5b235a6b367b861a8 \
  --pair  0xF69824a4718e114b41680e017dbd1a87D374AF9f \
  --block 9971550 \
  --chain bsc
```

**Sell reverted only if `--tau > 1`** (> 6 seconds) — an anti-simulation mechanism allows the sell immediately after the buy, but reverts if any blocks have elapsed. Naive tools (which execute buy and sell in the same block) would classify this token as safe:
```bash
python3 honeypot_detector.py \
  --token 0x2434acc863ec2d7d9fb3dce90ad1f671c2c8e52e \
  --pair  0x1f6F9a8b38D931764619c2b3A2D6F1EEDC4C20A4 \
  --block 30274521 \
  --tau   1 \
  --chain bsc
```

**Approve reverted** — the token contract blocks the router approval, making it impossible to initiate a sell:
```bash
python3 honeypot_detector.py \
  --token 0x26fd47f9ef785d8a9cba354d6720e67e19aff9e5 \
  --pair  0xDF725072349CF13e8757A3fcfC0561471BAF8a55 \
  --block 33861734 \
  --chain bsc
```

**High taxes** — buy and sell succeed, but the taxes are high enough to make the trade unprofitable for any participant other than the deployer:
```bash
python3 honeypot_detector.py \
  --token 0xd3a555ba7142c2c11f5e2bd2114720c36e31ac81 \
  --pair  0x343847eBBEDb6099043Df33e885Dfac26427A5aF \
  --block 12338505 \
  --chain bsc
```

**100% buy tax** — no tokens are transferred to the buyer; the simulation halts immediately after the buy:
```bash
python3 honeypot_detector.py \
  --token 0x5e2cad0e0dce2fdda32ddd3ef3228000e935a562 \
  --pair  0xd28BAE7540209f9dd6929b931f17D165E6060478 \
  --block 26118656 \
  --chain bsc
```

**Ethereum honeypot** — same detection logic applied to an Ethereum token via Uniswap V2:
```bash
python3 honeypot_detector.py \
  --token 0xf677cd57869283cb721683de45f2122c299af8ea \
  --pair  0x11978D4F78F6E84E260EA99f1987297688aa117c \
  --block 19413505 \
  --chain eth
```