vetagent

VetAgent

为 AI Agent 提供交易前安全检查。 Agent 买入、持有或推荐代币之前，会调用 VetAgent 并获得可执行的判定——low / medium / high / unknown——以及背后的具体信号，而不是一堆需要自行解读的数字。

远程 MCP 端点：https://vetagent.dev/mcp · 着陆页：https://vetagent.dev 正在使用，或认为它误判了某个代币？请联系 [email protected]，或提交 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."
}

---

安装

无需安装。它是远程服务：无需软件包、容器、API 密钥或注册。只需添加一个 URL。

Claude Code：

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

Cline、Cursor、Claude Desktop 或任何其他 MCP 客户端——将其添加到 MCP 配置中：

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

确认配置成功——应该会显示三个工具：

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

不使用 MCP？同一引擎也支持通过纯 HTTP 获取结果： GET https://vetagent.dev/assess/<address>

请参阅 llms-install.md，了解面向执行安装的 Agent 的版本；关于连接后如何使用输出，请参阅 docs/AGENT-INTEGRATION.md。

---

unknown 不等于 low

这是关于输出最重要的一点。

VetAgent 采用故障关闭策略。当检查无法执行时——上游服务宕机、买入／卖出模拟失败或未返回流动性数据——它会返回 unknown，并在 evidence.data_gaps 中准确列出缺失内容。它绝不会用乐观的中间值替代，也绝不会替你确定仓位大小。

confidence 衡量的是输入数据的完整程度，而不是代币的安全性。

一个坦诚地说“我不知道”的风险工具很有用。靠猜测的工具则不然。

---

工具

工具	功能
assess_token_risk(address, chain_hint?, verbose?)	完整风险概况：所有八条链上的流动性深度、交易对年龄及同名代币冒充情况；Ethereum、BSC 和 Base 上的卖出能力模拟、税费、合约权限和上游综合判定；Solana 上的铸币／冻结权限及 Token-2022 扩展。目前尚未支持任何链上的持币者集中度检查
get_token_liquidity(address, chain_hint?)	主交易对的流动性快照，并提供明确的 status，以区分“上游失败”和“不存在资金池”
find_new_hot_pools(chain?, limit?)	某条链上最新／最热门的资金池。仅用于发现——不代表安全背书

已知时请务必传入 chain_hint。PulseChain 等 Ethereum 分叉链会沿用合约地址，因此同一个地址可能存在于多个价格差异巨大的链上；提供提示可消除这种歧义。（如果不提供，VetAgent 会优先选择主流链——参见 src/risk.py 中的 _CHAIN_RANK。）

面向 Agent 的完整约定：docs/AGENT-INTEGRATION.md。

---

准确性基准测试

大多数代币风险工具都会公布功能列表。我们公布错误率及其背后的方法——包括目前尚未奏效的部分——并以引擎不会读取的数据源生成的标签作为对照。

目前测量的指标：在 162 个健康代币中，误报率为 1.9%；错误拦截率为 13.0%（154 个流动性充足的健康代币中，有 20 个被评为中或高风险，Agent 也会拒绝这些代币）；未知率为 20.7%；GoPlus 标记为中心化的代币中，21.2% 被评为高风险——几乎全是已弃用的池子，里面只有几美分而非 USDT，因此被评为低风险。

尚未测量的指标：可依赖的召回率。抽样发现 576 个代币中有 30 个已失效，因为所有公开来源都按流动性排序，而被 Rug 的池子会直接从列表中消失；对抗性样本群包含 17 个合约。这两个小样本群的召回率已发布在 bench/results.md 中，并附有一列仅使用合约信号的结果，因为它们检测到的大多数问题都是池子为空，而非合约恶意。只有等每日快照存档足够成熟、能够提供真正的样本群后，才会公布总体层面的检测率。本节早期版本曾声称“已测量召回率”，但基准测试文件本身与这一说法相矛盾。

→ bench/results.md — 当前数据、方法及已知局限。

采用这种构建方式的原因：

• 独立标签。 如果基准测试使用引擎会读取的 honeypot.is 为代币打标签，那测到的就只是 VetAgent 能否转发 honeypot.is 的结果。标签来自实际市场表现（价格／交易量历史）以及刻意不纳入引擎的 GoPlus。
• 运行时断言，而非承诺。 基准测试会记录双方访问过的每个端点；如果两组端点有交集，就会让运行失败。循环基准测试还不如不做，因此我们从结构上杜绝这种情况，而非只在文档中说明。
• 消融对照列。 已经崩盘的代币如今流动性约为零，因此标记它们几乎是同义反复。因此，结果会报告两次：一次包含所有信号；一次仅保留合约信号（移除流动性、生命周期、池龄和冒充信号）。两者的差距体现了引擎在显而易见的因素之外实际贡献了什么。
• 同时报告 unknown 率和召回率。 一个对所有问题都回答 unknown 的工具，召回率完美，但毫无价值。

基准测试使用固定逻辑时钟 2026-09-21T02:00:00Z。要复现结果，请使用隔离的工作副本和匹配的本地缓存：

python bench/run_benchmark.py --replay

重放不会发起网络请求。缺少答案时会返回退出码 4，列出缺失的 URL，并保持现有结果文件不变。完整重放可以写入 bench/results.json 和 bench/results.md。缓存不会随此代码库跟踪或发布；不能保证全新克隆能复现已公布的数据。

普通运行模式可以获取缺失的答案并写入带日期的缓存条目。如需主动刷新，请使用经过审核的明确 HTTPS URL 列表运行 python bench/run_benchmark.py --fill missing-urls.txt；程序会对列表去重，并跳过已有的可用记录条目。之后请单独运行 --replay。固定逻辑时钟并不代表对上游状态的历史测量：新答案可能会改变结果。

---

测试

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

tests/ 中的每个用例都对应一个确实进入过生产环境的缺陷。

合约测试确实发挥了作用：VetAgent 最严重的缺陷，是在 honeypot.is 将该标记放在 honeypotResult 中时，却去读取 simulationResult.isHoneypot。这个键并不存在，查找结果为 None，随后被当作 False 读取，蜜罐检查因此悄无声息地放行了所有曾经被检查过的代币。任何模拟测试都无法发现这个问题——只有调用真实 API 并断言返回结构的测试才能发现。

**本代码库的规则：**声称修复问题的提交必须附带一个在修复前会失败的测试。

架构

Cloudflare Python Worker，无繁重依赖。

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

MCP 端点是手工编写的，而不是使用官方 mcp 包：该包会引入 pydantic 的 C 扩展，而这些扩展无法安装在 Cloudflare Python Workers 上。最终发现，纯 JSON-RPC 更轻量，并且与所有客户端完全兼容。

数据来源

来源	用途
DexScreener	交易对、价格、流动性、交易量、交易对年龄
GeckoTerminal	流动性备用数据、新建／热门池
honeypot.is	买入／卖出模拟、税费、综合风险、合约开放性——仅适用于 Ethereum、BSC 和 Base
RugCheck	Solana Rug 评分、铸币／冻结权限、Token-2022 扩展。无持有者集中度：自 2026-09-19 起，报告中不再包含持有者数据

引擎不会使用 GoPlus——它仅作为基准测试中保留的预言机。若要将其加入引擎，必须先为基准测试引入一个新的独立标注器，否则准确率数字就失去意义。

文档的分工

四份文档，各司其职。如果某项内容出现在两份文档中，其中一份就是错的。

文档	解答的问题
README.md（本文）	这是什么？如何调用？
docs/DECISIONS.md	为什么这样构建？每条规则由什么强制执行？
docs/STRATEGY.md	谁会付费？护城河是什么？何时应该停止？

更改原因记录在提交消息中，它不可更改，并与差异内容关联。代码行看起来奇怪的原因写在该行旁边的注释中。这两者都不会复制到文档中，因为副本会在无人察觉的情况下逐渐过时。

范围

VetAgent 报告可观测的链上风险。它不是财务建议，不会评估仓位规模，也无法识别链下风险——团队行为、社交工程，或通过治理执行的 Rug。将 low 理解为“运行的检查中未发现致命信号”，绝不能理解为“可以放心买入”。

许可证

MIT——请参阅 LICENSE。