DOCS v1.0

Introduction

DINOHUNTER is an AI security agent for Web3. It inspects smart contracts, transactions, websites and scripts for the patterns used by wallet drainers, phishing kits, honeypot tokens and rug pulls — and explains the result in plain language before you sign anything.

It is a full-stack app: a Node.js backend with four detection engines, a threat database and an optional Claude reasoning layer, plus a multi-page pixel-styled frontend.

DINOHUNTER reduces risk; it does not eliminate it. A CLEAN verdict means no known pattern matched — not that something is safe.

Quickstart

Requirements: Node.js 18+. The server has zero required dependencies.

bash
git clone <your-repo> dinohunter
cd dinohunter
npm start
# → http://localhost:3000

Enable AI reasoning with Claude (optional):

bash
npm install                     # installs @anthropic-ai/sdk
export ANTHROPIC_API_KEY=sk-ant-...
npm start

Then open /agent and paste something suspicious.

The Agent

The agent works like a chat app. Each message you send triggers one hunt:

  1. Classify — detects whether the input is an address, calldata, bytecode, URL, script or question.
  2. Plan & call tools — runs the matching tools: threat_db, rpc, bytecode, calldata, url, script.
  3. Score — aggregates findings into a 0–100 risk score and verdict.
  4. Reason — Claude (or the built-in rule narrator) writes a short verdict with next steps.

Every tool call is shown in the trace panel with timing, so you can see exactly what the agent did. Pick the network in the sidebar for address scans. Past hunts are kept in your browser's history list.

Input types

TypeLooks likeWhat happens
address0x + 40 hexBlocklist lookup, eth_getCode + balance via RPC, bytecode scan
calldata0x + 4-byte selector + 32-byte wordsDecodes the call (approve, setApprovalForAll, permit…), checks counterparties
bytecodeLong hex, usually starting 0x6080604…Disassembles opcodes and selectors offline
urlDomain or linkDomain reports + phishing heuristics. The URL is never fetched.
scriptJavaScript / HTML snippetStatic drainer-pattern scan
questionAnything elseSecurity Q&A

Detection engines

Bytecode engine

A real EVM disassembler that skips PUSH data, so opcode counts are accurate. It flags:

  • SELFDESTRUCT, CALLCODE — high risk
  • DELEGATECALL — or an EIP-1967 upgradeable proxy if the implementation slot is present
  • ORIGIN (tx.origin) — phishable auth / honeypot sell-blocking
  • EIP-1167 minimal proxies, CREATE2 deployers, tiny contracts
  • Privileged selectors: mint, pause, upgradeTo, transferOwnership
  • Honeypot heuristic: ERC-20 + owner levers + tx.origin checks

Calldata engine

Decodes the 4-byte selector and ABI words. Unlimited approve (MAX_UINT256), setApprovalForAll(…, true), permit and contract upgrades are rated high. Unknown selectors are medium — never sign blind.

URL engine

Checks HTTPS, punycode/homoglyphs, raw IPs, @ tricks, high-abuse TLDs, deep subdomains, brand impersonation (~30 Web3 brands), Levenshtein typosquats and lure keywords like claim, airdrop, verify. Official domains are allow-listed.

Script engine

Regex signatures for drainer kits: eth_sign, Permit2, Seaport orders, setApprovalForAll, MAX_UINT allowances, eval/atob obfuscation, seed-phrase harvesting, Telegram/Discord exfiltration, asset enumeration and hard-coded addresses.

Risk scoring

Each finding has a level with a weight. The score is the capped sum.

high
+38
medium
+20
low
+8
info
+0

A match in the threat feed is a confirmed indicator and forces the verdict to MALICIOUS (score ≥ 85).

ScoreVerdictMeaning
70–100MALICIOUSDo not interact.
40–69SUSPICIOUSStrong risk signals. Verify independently.
15–39CAUTIONRisky capabilities exist (e.g. upgradeable, mintable).
0–14CLEANNo known pattern matched.

Threat feed

The Threat Feed lists indexed indicators (addresses and domains). Anyone can report one; repeat reports increment its counter. The agent checks the feed on every address, calldata counterparty, URL and embedded script address.

The seeded entries shipped with the repo are synthetic sample data. Plug in your own intel source for production (see Self-hosting).

API reference

Base URL: http://localhost:3000. All bodies are JSON. No auth by default.

POST/api/agent/run

Run a full agent hunt. Rate-limited to 30/min per IP.

input
string, required — anything you want scanned
chain
ethereum | base | robinhood (default ethereum)
bash
curl -X POST http://localhost:3000/api/agent/run \
  -H "content-type: application/json" \
  -d '{"input":"http://opnsea-rewards.xyz/claim","chain":"ethereum"}'
json
{
  "type": "url",
  "verdict": "MALICIOUS",
  "score": 100,
  "findings": [
    { "level": "high", "title": "Typosquat of opensea", "detail": "...", "engine": "url" }
  ],
  "meta": { "host": "opnsea-rewards.xyz", "tld": "xyz", "official": false },
  "summary": "Verdict: MALICIOUS. Do not interact. ...",
  "steps": [ { "tool": "classifier", "label": "Classify input", "status": "ok", "ms": 0 } ],
  "ms": 3
}
POST/api/classify

Returns only the detected input type: {"type":"calldata"}.

GET/api/threats

Query params: q, category, chain, limit (max 500).

POST/api/threats/report
indicator
address or domain, required
category
drainer | phishing | honeypot | rugpull | seed-stealer | other
chain
optional
note
optional, ≤500 chars
GET/api/stats

Scan counters by verdict and type, number of threats and reports.

GET/api/health · /api/chains

Health, version, AI status; and the list of supported networks.

JavaScript example

js
const res = await fetch('/api/agent/run', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ input: calldata, chain: 'base' }),
});
const report = await res.json();
if (report.verdict === 'MALICIOUS') blockSigning(report.summary);

AI reasoning (Claude)

Detection is deterministic; the LLM only explains. When ANTHROPIC_API_KEY is set and @anthropic-ai/sdk is installed, the agent sends the input and the scanner JSON to Claude, which writes a short verdict with next steps. It is instructed never to invent findings.

  • Default model: claude-opus-5-5 (override with DINO_MODEL)
  • Server-side refusal fallback enabled (fallbacks: "default")
  • If the call fails or no key is set, the built-in rule narrator is used — the app never breaks.

Code lives in server/engine/llm.js.

Self-hosting

Environment variables

PORT
HTTP port (default 3000)
ANTHROPIC_API_KEY
Enables Claude reasoning
DINO_MODEL
Claude model id (default claude-opus-5-5)
RPC_ETHEREUM
Custom RPC; also RPC_BASE, RPC_ROBINHOOD

Data

The datastore is a JSON file: server/data/db.json, created from seed.json on first run. Delete it to reset. For production replace server/store.js with Postgres/Redis — the interface is five methods.

Vercel

The repo is Vercel-ready: vercel.json serves public/ as static pages with clean URLs (/about → about.html) and routes every /api/* call to the serverless function api/index.js, which reuses the same handler as the local server.

  1. Import the repo in Vercel. Framework preset: Other. Leave build/output settings empty — vercel.json sets them.
  2. Optional: add ANTHROPIC_API_KEY under Settings → Environment Variables.
  3. Deploy, then open /api/health to confirm the API is online.
On Vercel the filesystem is read-only, so scan stats and community reports are kept in /tmp per instance and reset on cold starts. For durable data, back server/store.js with a database (e.g. Postgres or Redis).

Docker

dockerfile
FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install --omit=dev || true
EXPOSE 3000
CMD ["node", "server/index.js"]

Architecture

tree
dinohunter/
├─ api/index.js           Vercel serverless entry (wraps server/app.js)
├─ vercel.json            static output, clean URLs, /api rewrites, headers
├─ server/
│  ├─ app.js              request handler: API routes, rate limit, security headers
│  ├─ index.js            local HTTP server (npm start)
│  ├─ store.js            JSON datastore (threats, reports, stats)
│  ├─ engine/
│  │  ├─ agent.js         classify → tools → score → reason
│  │  ├─ analyzers.js     bytecode / calldata / url / script engines + scoring
│  │  ├─ signatures.js    selectors, brands, TLDs, drainer regexes
│  │  └─ llm.js           optional Claude reasoning
│  └─ data/seed.json      sample threat intel
├─ public/
│  ├─ index.html          Home
│  ├─ agent.html          Agent app
│  ├─ threats.html        Threat feed
│  ├─ docs.html           Documentation
│  ├─ about.html          About
│  ├─ css/ js/ assets/
└─ scripts/gen-logo.js    builds the pixel dino SVG

Each menu item is its own page with its own script module; common.js injects the shared nav, footer and pixel logo.

Limitations

  • Static heuristics can be evaded by novel or heavily obfuscated malware.
  • Bytecode analysis does not simulate execution; pair with a transaction simulator for full coverage.
  • Public RPCs may be rate-limited; set your own RPC for reliability.
  • Off-chain EIP-712 payloads should be pasted as script/JSON for scanning.

FAQ

Does DINOHUNTER need my wallet?

No. It never connects to or asks for a wallet, seed phrase or private key. If anything claiming to be DINOHUNTER asks, it's a scam.

Does it visit the URLs I paste?

No. URLs are analysed lexically only, so scanning a drainer site can't trigger it.

Can I use it without an AI key?

Yes. All detection runs locally; the AI only writes the explanation.

Which chains are supported?

Ethereum, Base and Robinhood Chain for on-chain lookups. Calldata, bytecode, URL and script scans are chain-agnostic.