vetagent

VetAgent

A pre-trade safety check for AI agents. Before an agent buys, holds, or recommends a token, it calls VetAgent and gets an actionable verdict — low / medium / high / unknown — plus the specific signals behind it, instead of a wall of numbers to interpret.

Remote MCP endpoint: https://vetagent.dev/mcp · Landing page: https://vetagent.dev Using it, or think it got a token wrong? [email protected] — or open an issue.

// assess_token_risk("0x…", chain_hint="ethereum")
{
  "risk_level": "medium",
  "risk_score": 36,
  "confidence": "high",
  "signals": [
    {"severity": "ok",   "name": "Liquidity is adequate",     "category": "liquidity"},
    {"severity": "ok",   "name": "Buys and sells normally",   "category": "honeypot"},
    {"severity": "warn", "name": "Contract is closed source", "category": "contract"}
  ],
  "recommendation": "Medium risk. Real signals fired but none are fatal. Review liquidity, holder distribution and contract permissions before deciding."
}

---

Install

Nothing to install. It is a remote server: no package, no container, no API key, no signup. Add one URL.

Claude Code:

claude mcp add --transport http vetagent https://vetagent.dev/mcp

Cline, Cursor, Claude Desktop, or any other MCP client — add to the MCP config:

{
  "mcpServers": {
    "vetagent": {
      "type": "http",
      "url": "https://vetagent.dev/mcp"
    }
  }
}

Confirm it worked — three tools should come back:

curl -s -X POST https://vetagent.dev/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Not using MCP? The same engine answers over plain HTTP: GET https://vetagent.dev/assess/<address>

See llms-install.md for the version written for an agent doing the installing, and docs/AGENT-INTEGRATION.md for how to use the output once connected.

---

unknown is not low

This is the single most important thing to know about the output.

VetAgent is fail-closed. When a check cannot run — an upstream is down, a buy/sell simulation fails, no liquidity data comes back — it returns unknown and lists exactly what was missing in evidence.data_gaps. It never substitutes an optimistic middle value, and it never sizes a position for you.

confidence measures how complete the input data was, not how safe the token is.

A risk tool that honestly says "I don't know" is useful. One that guesses is not.

---

Tools

Tool	What it does
assess_token_risk(address, chain_hint?, verbose?)	Full risk profile: liquidity depth, pair age and same-ticker impersonation on all eight chains; sellability simulation, taxes, contract permissions and upstream aggregate verdicts on Ethereum, BSC and Base; mint/freeze authority and Token-2022 extensions on Solana. No holder concentration on any chain yet
get_token_liquidity(address, chain_hint?)	Liquidity snapshot for the primary pair, with an explicit status so "upstream failed" is distinguishable from "no pools exist"
find_new_hot_pools(chain?, limit?)	Newest / hottest pools on a chain. Discovery only — not a safety endorsement

Pass chain_hint whenever you know it. Ethereum forks such as PulseChain inherit contract addresses, so the same address exists on multiple chains with wildly different prices; the hint removes that ambiguity. (Without it, VetAgent prefers canonical chains — see _CHAIN_RANK in src/risk.py.)

Full agent-facing contract: docs/AGENT-INTEGRATION.md.

---

Accuracy benchmark

Most token-risk tools publish a feature list. We publish our error rates and the method behind them — including the parts that do not work yet — against labels produced by data sources the engine does not read.

What is measured today: a 1.9% false positive rate on 162 healthy tokens, a 13.0% false-block rate (20 of 154 liquid healthy tokens rated medium or high, which an agent will also refuse), a 20.7% unknown rate, and 21.2% of GoPlus-tagged centralised tokens rated high -- almost all abandoned pools holding cents, not USDT, which is rated low.

What is not measured yet: recall you could rely on. Sampling has turned up 30 dead tokens in 576, because every public source ranks by liquidity and rugged pools fall off the listing entirely, and the adversarial cohort is 17 contracts. Recall on those two small cohorts is published in bench/results.md beside a contract-signals-only column, because most of what they catch is an empty pool rather than a hostile contract. A population-level detection rate waits until the daily snapshot archive matures enough to supply a real cohort. An earlier version of this section claimed "measured recall", which the benchmark file itself contradicted.

→ bench/results.md — current numbers, method, and known limits.

Why it is built this way:

• Independent labels. If the benchmark labelled tokens using honeypot.is — which the engine reads — it would only measure whether VetAgent can relay honeypot.is. Labels come from realized market outcome (price/volume history) and from GoPlus, which is deliberately held out of the engine.
• A runtime assertion, not a promise. The benchmark records every endpoint each side touched and fails the run if the two sets intersect. A circular benchmark is worse than none, so it is made structurally impossible rather than documented.
• An ablation column. A token that already collapsed has ~zero liquidity today, so flagging it is close to tautological. Results are therefore reported twice: with all signals, and with only contract signals kept (liquidity, lifecycle, pool-age and impersonation signals removed). The gap is what the engine actually contributes beyond the obvious.
• unknown rate reported alongside recall. A tool that answers unknown to everything has perfect recall and zero value.

The benchmark uses the pinned logical clock 2026-09-21T02:00:00Z. Use an isolated working copy and a matching local cache for reproduction:

python bench/run_benchmark.py --replay

Replay makes no network requests. A missing answer returns exit 4, lists missing URLs, and leaves existing result files unchanged. A complete replay can write bench/results.json and bench/results.md. The cache is not tracked or published with this repository; a fresh clone is not guaranteed to reproduce the published figures.

Plain run mode can fetch missing answers and write dated cache entries. An intentional refresh uses python bench/run_benchmark.py --fill missing-urls.txt with a reviewed explicit HTTPS URL list; it deduplicates the list and skips usable recorded entries. Run a separate --replay afterwards. A pinned logical clock is not a historical measurement of upstream state: new answers can change the results.

---

Tests

python tests/test_risk.py               # engine regressions, offline, real upstream snapshots
python tests/test_mcp.py                # MCP protocol conformance
python tests/test_upstream_contract.py  # live: every path risk.py reads, against a measured baseline

Every case in tests/ is pinned to a defect that actually reached production.

The contract test earns its keep: VetAgent's worst bug was reading simulationResult.isHoneypot when honeypot.is puts that flag in honeypotResult. The key did not exist, the lookup returned None, it was read as False, and the honeypot check silently passed every token it was ever asked about. No mocked test could have caught that — only one that calls the real API and asserts the shape.

Rule for this repo: a commit that claims to fix something ships with a test that was red before it.

---

Architecture

Cloudflare Python Worker, no heavy dependencies.

src/
  entry.py        HTTP routing (entry class must be named Default)
  risk.py         risk engine — assess / liquidity / new_pools
  mcp_server.py   hand-written streamable-http MCP endpoint (JSON-RPC 2.0)
  landing.html    landing page
bench/            accuracy benchmark (independent labels + ablation)
tests/            regression, protocol, and upstream-contract suites
docs/             agent integration guide, handoff, MCP registry manifest

The MCP endpoint is hand-written rather than using the official mcp package: that package pulls in pydantic's C extensions, which do not install on Cloudflare Python Workers. Plain JSON-RPC turned out to be smaller and fully client-compatible.

Data sources

Source	Used for
DexScreener	pairs, price, liquidity, volume, pair age
GeckoTerminal	liquidity fallback, new/trending pools
honeypot.is	buy/sell simulation, taxes, aggregate risk, contract openness -- Ethereum, BSC and Base only
RugCheck	Solana rug score, mint/freeze authority, Token-2022 extensions. No holder concentration: the report has carried no holders since 2026-09-19

GoPlus is not used by the engine — it is reserved as the benchmark's held-out oracle. Adding it to the engine requires giving the benchmark a new independent labeller first, or the accuracy numbers stop meaning anything.

Where things are written down

Four documents, one job each. If something is in two of them, one of them is wrong.

Document	Answers
README.md (this file)	What is this, how do I call it
docs/DECISIONS.md	Why is it built this way, and what enforces each rule
docs/STRATEGY.md	Who pays, what the moat is, when to shut it down

Why a change was made lives in the commit message, which is immutable and attached to the diff. Why a line of code looks odd lives in a comment next to that line. Neither gets copied into a document, because a copy rots without anyone noticing.

Scope

VetAgent reports observable on-chain risk. It is not financial advice, it does not size positions, and it cannot see off-chain risk — team behaviour, social engineering, or a rug executed through governance. Treat low as "no fatal signal found in the checks that ran", never as "safe to buy".

License

MIT — see LICENSE.