# rug-check 🚨

**On-chain rug-pull & honeypot risk screen for ERC-20 tokens — for AI agents and traders.**

Give it a token address and get a **SAFE / CAUTION / HIGH-RISK** verdict (0–100 score) in one call, built entirely from **live public-RPC reads** — no API key, no node, no signup.

[![MCP](https://img.shields.io/badge/MCP-server-blue)](https://modelcontextprotocol.io) [![x402](https://img.shields.io/badge/x402-pay--per--call-ff7a9c)](https://x402.org) [![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

> rug-check is an automated on-chain risk **screen**, not financial advice or a safety guarantee. It pattern-matches deployed bytecode and reads chain state; it cannot catch every scam (off-chain admin keys, novel honeypots) and may flag benign contracts. Always do your own research.

## Why it exists (the moat)

An AI coding/trading agent that "just reads the chain" does **not** know:

- **Which dangerous functions** the token's *deployed bytecode* exposes — `mint`, `blacklist`, `pause`, `setFees`, `setMaxTx` — the levers used to trap or dilute holders.
- Whether **ownership is renounced**, or an active owner can still call those powers after you buy.
- How **concentrated** supply is in the owner/deployer wallet (dump risk).
- Whether a **DEX liquidity pair** exists, how deep it is, and whether the **LP tokens are locked or burned** — the single thing that decides if the deployer can pull all liquidity (the literal "rug pull").

rug-check ABI-encodes and batches all of that, decodes the bytecode, scores it, and returns one verdict.

## What it checks

| Check | What it tells you |
|---|---|
| Owner powers | scans runtime bytecode for `mint` / `blacklist` / `pause` / `setFees` / `setMaxTx` |
| Ownership | renounced vs active owner (`owner()` / `getOwner()` → zero/dead = renounced) |
| Concentration | % of total supply held by the owner wallet |
| Liquidity | UniswapV2/Pancake pair reserves vs wrapped-native, depth, thin-liquidity flag |
| LP lock/burn | % of LP supply in burn address or known lockers (Pinksale, Unicrypt, Team.Finance…) |
| Proxy | EIP-1967 upgradeable-proxy detection (behaviour can change post-launch) |

Chains: **Ethereum, Base, BSC, Polygon, Arbitrum.**

## Use as an MCP server (free)

```json
{
  "mcpServers": {
    "rug-check": { "command": "npx", "args": ["-y", "rugshield-mcp"] }
  }
}
```

Tools:
- `rug_check_token` — `{ chain, address }` → full risk report.
- `rug_check_many` — up to 10 `{ chain, address }` → batch verdicts.

Or connect over HTTP at `POST /mcp`.

## Free HTTP API

```
GET /check?chain=base&address=0x4ed4e862860bed51a9570b96d89af5e1b0efefed
GET /check?chain=ethereum&address=0x6b175474e89094c44da98b954eedeac495271d0f
```

Rate-limited 30/h/IP.

## Pay-per-call (x402)

The `/pro/*` routes are gated by [x402](https://x402.org). Your agent pays **$0.25 USDC** per call automatically — no sign-up, no API key. Settles on-chain (Base) to the operator wallet.

```
GET /pro/check?chain=base&address=0x...
GET /pro/check_many?tokens=base:0x..,bsc:0x..
```

Discovery: `GET /openapi.json` (with `x-payment-info`) and `GET /.well-known/x402`.

## Develop

```
npm install
npm run build
npm run test:engine     # offline unit tests + live on-chain sanity checks
npm run dev:http        # local HTTP server on :8080 (payments OFF unless configured)
npm run dev:mcp         # stdio MCP server
```

MIT © rug-check