# EVM AutoSnipe

Monitor unlaunched EVM tokens and receive real-time signals when they become buyable. AutoSnipe watches the mempool and new blocks for liquidity events, simulates buyability, and pushes a signal to your Socket.IO connection the moment a token launches.

> **Socket.IO only:** AutoSnipe signals are delivered as server-emitted events on your Socket.IO connection. You must be connected via Socket.IO to receive them.

---

## Register Watch

Register a watch on a token to be notified when it becomes buyable.

**Endpoint:** `/evm/autosnipe/register`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | Chain identifier: `eth`, `base`, or `bsc` |
| `token` | string | Yes | Token contract address to watch |
| `ttlMs` | number | No | Watch duration in milliseconds. Min: 3,600,000 (1h), max: 172,800,000 (2d), default: 86,400,000 (24h) |

**Example:**

```typescript
socket.emit("/evm/autosnipe/register", {
  chain: "eth",
  token: "0x1234567890abcdef1234567890abcdef12345678",
  ttlMs: 86400000, // 24 hours
});
```

**Response:**

```json
{
  "success": true,
  "result": {
    "chain": "eth",
    "token": "0x1234567890abcdef1234567890abcdef12345678",
    "owner": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    "expiresAt": 1711065600
  }
}
```

Registration will be rejected if:

- The address is not a contract
- The token is already launched and buyable
- The token or its owner is on the ignored addresses list (stablecoins, WETH, known MEV bots, etc.)

---

## Remove Watch

Remove an active AutoSnipe watch.

**Endpoint:** `/evm/autosnipe/remove`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | Chain identifier |
| `token` | string | Yes | Token contract address |

**Example:**

```typescript
socket.emit("/evm/autosnipe/remove", {
  chain: "eth",
  token: "0x1234567890abcdef1234567890abcdef12345678",
});
```

**Response:**

```json
{
  "success": true,
  "result": {
    "chain": "eth",
    "token": "0x1234567890abcdef1234567890abcdef12345678"
  }
}
```

---

## List Watches

List all active AutoSnipe watches on a chain.

**Endpoint:** `/evm/autosnipe/list`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `chain` | string | Yes | Chain identifier |

**Example:**

```typescript
socket.emit("/evm/autosnipe/list", {
  chain: "eth",
});
```

**Response:**

```json
{
  "success": true,
  "result": [
    {
      "chain": "eth",
      "partnerId": "your-partner-id",
      "token": "0x1234567890abcdef1234567890abcdef12345678",
      "owner": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
      "expiresAt": 1711065600,
      "registeredAt": 1710979200
    }
  ]
}
```

---

## AutoSnipe Signal Event

When a watched token becomes buyable, you receive an `autoSnipeSignal` event on your Socket.IO connection. Watches are automatically removed after a signal fires.

```typescript
socket.on("autoSnipeSignal", (data) => {
  console.log(data);
});
```

**Event payload:**

```json
{
  "chain": "eth",
  "token": "0x1234567890abcdef1234567890abcdef12345678",
  "type": "block0",
  "blockNumber": "19500000",
  "taxes": {
    "buyTaxBps": 500,
    "sellTaxBps": 500
  },
  "limits": {
    "buyLowerLimit": null,
    "buyUpperLimit": "1000000000000000000",
    "sellLowerLimit": null,
    "sellUpperLimit": null
  },
  "triggeringTx": "0x02f8...",
  "timestamp": 1710979200
}
```

| Field | Type | Description |
| --- | --- | --- |
| `chain` | string | Chain where the token launched |
| `token` | string | Token contract address |
| `type` | string | `block0` (detected in mempool before mining) or `block1` (detected in mined block) |
| `blockNumber` | string | Block number at detection time |
| `taxes.buyTaxBps` | number \| null | Buy tax in basis points (null if unknown) |
| `taxes.sellTaxBps` | number \| null | Sell tax in basis points (null if unknown) |
| `limits.buyLowerLimit` | string \| null | Minimum buy amount in wei (null if none) |
| `limits.buyUpperLimit` | string \| null | Maximum buy amount in wei (null if none) |
| `limits.sellLowerLimit` | string \| null | Minimum sell amount in wei (null if none) |
| `limits.sellUpperLimit` | string \| null | Maximum sell amount in wei (null if none) |
| `triggeringTx` | string \| null | RLP-serialized transaction that triggered the launch (block0 only) |
| `timestamp` | number | Unix timestamp in seconds |

### Signal Types

- **`block0`** — The token was detected as buyable from a pending mempool transaction _before_ it was mined. This gives you the earliest possible signal. The `triggeringTx` field contains the serialized liquidity-adding transaction.
- **`block1`** — The token was detected as buyable in the first block after the liquidity transaction was mined. This is a fallback for cases where mempool detection was not possible.