getplexa

@getplexa/mcp — Plexa MCP 服务

一个 Model Context Protocol 服务，为任何 MCP 客户端 （Claude Desktop、Cursor 或你自己的 Agent）提供来自 Plexa 的两种经济安全工具—— 面向交易 Agent 的 x402 原生经济安全层，按次以 USDC 付费，无需账户：

工具	封装的接口	价格	返回内容
plexa_quote	POST /v1/quote	$0.02	在指定交易规模下的可执行成交价（而非中间价／现货价）、价格影响（bps）、可实现深度、逐腿路由、最坏情况滑点、置信度——数据来自 Base、Polygon 和 Arbitrum 上的规范链上报价器。
plexa_pretrade_check	POST /v1/pretrade/check	$0.05	两个层级。verdict：仅当某个已列明陷阱在该区块的链上状态中被证实时才返回 avoid（没有可供退出的池子 · 对手资产池低于你交易规模的 5%，且该资产池是卖出可获得金额的硬上限 · 代币自身的交易开关已关闭）；其他情况返回 clear。clear 表示没有可证实的陷阱，并不表示“安全”。risk_profile：代币年龄、持有人集中度、流动性深度（含 exitLiquidityUsd）、预言机可用性、转账限制——作为供你权衡的数据，而非评级。另外还会返回原因、置信度和可执行报价。（目前仅支持 Base。）

它是公共 API 的轻量客户端（https://api.getplexa.com）——会自动处理 402， 使用你的钱包在本地签署 USDC 授权，且不会接触你的密钥。流动性引擎 仍在 API 后端运行。

---

为什么需要它

通用钱包防护工具回答的是*“我能签署这笔交易吗？”*它无法回答自动化交易者真正需要的经济 问题：这笔兑换按我的交易规模实际会以什么价格成交？这个代币是不是陷阱（rug／蜜罐／流动性不足）？ Plexa 可以回答这两个问题。使用这个包，任何支持 MCP 的 Agent 只需调用一次工具即可获得答案。

---

安装

无需安装——通过 npx 将 MCP 客户端指向此包即可。它会按需获取并运行。

Claude Desktop

将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "plexa": {
      "command": "npx",
      "args": ["-y", "@getplexa/mcp"],
      "env": {
        "PLEXA_BASE_URL": "https://api.getplexa.com",
        "AGENT_WALLET_KEY": "0x<your funded wallet private key>",
        "CHAIN": "base"
      }
    }
  }
}

Cursor

将以下内容添加到 ~/.cursor/mcp.json（或通过 Settings → MCP → Add 添加）——使用与上文相同的 mcpServers 代码块。

重启客户端。你应该会看到可用的 plexa_quote 和 plexa_pretrade_check 工具。

---

配置

所有配置均通过环境变量完成（在 MCP 配置的 env 代码块中设置）：

变量	默认值	说明
PLEXA_BASE_URL	https://api.getplexa.com	公共 API。此 URL 真实有效，并非密钥。
AGENT_WALLET_KEY	(无)	付费必需。 已注资钱包的私钥——按次付费并在本地签名。Plexa 绝不会收到此密钥。未设置时，工具会返回明确的 402。
CHAIN	base	base | polygon | arbitrum（也支持别名 matic、arb、arbitrum-one 和 CAIP-2 标识 eip155:8453／137／42161；大小写会统一处理）。你的钱包在哪条链上注资；报价和付款默认使用该链。目前 plexa_pretrade_check 仅支持 Base——其他链会返回 422。

注资。 请在 CHAIN 上使用一个专用、低余额的钱包，存入少量 USDC 用于按次付费 （报价 $0.02，检查 $0.05）。钱包会为每个请求签署一份 EIP-3009 USDC 授权；只有付款在链上结算后，Plexa 才会返回 结果（先结算，后服务）。

你的密钥属于机密。如果 MCP 客户端提供机密存储功能，请优先使用。切勿将密钥提交到代码库。

x402 在 MCP 中的支付方式

MCP 没有内置支付功能。此服务充当 x402 客户端：它封装了 fetch，因此当 Plexa 回复 402 Payment Required 时，它会读取支付要求，使用你的钱包在本地签署 USDC 授权，然后重试。离开你设备的只有已签名的授权——绝不会泄露密钥。支付在 CHAIN 上完成，因此你只需在一条链上为一个钱包充值。

如果未设置 AGENT_WALLET_KEY，这些工具会如实返回 402 错误，说明需要有资金的钱包——绝不会捏造结果。

---

示例

配置完成后，只需自然地向你的 Agent 提问——它会调用这些工具：

“在 Base 上买入这个代币 0x… 之前，用 Plexa 检查一下，并为我获取一份可执行的 $500 报价。”

Agent 会调用 plexa_pretrade_check（结论 + 原因）和 plexa_quote（低于 $500 的可执行价格），自动支付 $0.05 + $0.02 的 USDC，并根据真实的链上经济数据作答。

返回内容

除 verdict / triggers / risk_profile / liquidityCoverage 外，每条交易前检查响应还包含六块上下文信息。实时采集，WETH，2026-08-20T14:46:29Z，Base 区块 50223921——每个区块携带的 note 字符串很长，此处将其截断，其余内容不变：

{
 "identity": {
  "name": "Wrapped Ether",
  "symbol": "WETH",
  "decimals": 18,
  "totalSupplyRaw": "239296586519181917702210",
  "totalSupply": 239296.58651918193
 },
 "valuation": {
  "fdvExecutableUsd": 543916397.6557496,
  "basis": "totalSupply(this chain) x executablePrice(at sizeUSD)"
 },
 "ownership": {
  "ownerAddress": null,
  "ownerRenounced": null,
  "isMintable": false,
  "creatorAddress": "0xe8a3ecea7d6a688ee903173024225357ddf29e93",
  "creatorBalance": 0.000289172466091074,
  "creatorSharePct": 1.208427041511075e-07
 },
 "dormancy": {
  "topHolderIdleDays": null,
  "lastTopHolderMoveBlock": null,
  "headBlock": null
 },
 "market": {
  "priceUsdSpot": 2277.76,
  "volume24hUsd": 551324354.8699999,
  "marketCapUsd": 542587444,
  "holderCount": 5223863
 },
 "sources": {
  "*": "measured",
  "risk_profile.concentration": "unavailable:holder-axis-produced-nothing",
  "flags.F_CONC": "unavailable:holder-axis-produced-nothing",
  "valuation": "derived:identity.totalSupply*quote.executablePrice",
  "dormancy": "unavailable:holder-axis-produced-no-block",
  "ownership.creatorAddress": "derived:sender-of-first-transfer",
  "ownership.isMintable": "derived:mint-selector-in-bytecode",
  "market": "vendor:dexscreener+goplus",
  "market.priceUsdSpot": "vendor:dexscreener",
  "market.volume24hUsd": "vendor:dexscreener",
  "market.marketCapUsd": "vendor:dexscreener",
  "market.holderCount": "vendor:goplus"
 }
}

🔴 sources 用于标明是谁提供了什么信息。 measured——我们在本次调用中从链上读取的数据。derived:<formula>——我们根据同一响应中的其他字段计算得出。vendor:<name>——其他来源提供并以其名义发布和签署的数据。unavailable:<reason>——没有可用值，并说明原因。最后这一点至关重要：如果缺失数值时也说明了缺失原因，就不会被误认为结果正常。

两个看起来重复、实则不同的数值：valuation.fdvExecutableUsd 是这条链上的供应量，按你的交易规模实际执行时的价格计算；market.marketCapUsd 是供应商提供的全球数据。对于跨链桥接代币，我们的数据确实会更小。

---

0.2.0 版本变更

一个字段的含义变了，而非结构。 risk_profile.liquidity.exitLiquidityUsd 过去表示直接池中的对手资产。自 2026-09-20 起，它表示卖出该仓位可获得的回款：服务会对答案所评估的同一仓位进行卖出报价，并报告最佳路径的收益（不会累加多条路径）。

旧数值现在位于： liquidityCoverage.exitPoolInventoryUsd——数值与以前相同，只是使用了独立字段名。liquidityCoverage.exitPotBasis 会说明主字段数值的类型：position-sale（实测回款）、second-hop（对手资产路径）或 pool-inventory（本次调用无法获取卖出报价，因此回退到 09-20 之前的含义）。

为何重要： 2026-09-20 在 SOGNI 上测得，库存为 $113,968，而卖出一个 $5,000 的仓位只能获得 $4,571。客户端若将旧数值与自身仓位规模进行比较，会高估相当于仓位规模 8.6% 的退出金额。如果你的代码使用 min(exitLiquidityUsd, size)，现在得到的就是诚实数值；如果依赖旧语义，请改读 exitPoolInventoryUsd。

此版本还包括：

• liquidityCoverage.exitLadderScope 和 liquidityCoverage.exitReachRoad 用于标明每个退出数值对应的路径，因此 exitLadderStatus: "unsellable" 不再会被误读为“此代币无法卖出”——它只描述 Uniswap v4 直接池，而退出金额可能是在其他地方通过 via <asset> 测得的。2026-09-22 在 Base 上测得：31 个 v4 池均为 unsellable，但该仓位通过另一个交易场所卖出了 $4,735.82。
• exitPoolInventoryUsd 不再是无条件的上限：运行 v4 卖出阶梯时，其中的 v4 份额就是该阶梯的可达金额，且不会计入双腿卖出中的第二段。
• 价格采用真实交易的 gas 限额进行测量，因为某些 Uniswap v4 钩子会根据调用方可用的 gas 设置费用。
• 本包中的契约字符串（价格、路径、阈值、判定用语以及上述两条说明）现在由 Plexa 服务源代码生成，因此不会与 API 产生偏差。

没有移除任何字段，也没有更改任何响应结构。次要版本号之所以递增，是因为一个已发布字段的含义发生了变化。

说明

• 仅限客户端。 通过 HTTPS 调用公开的 Plexa API。本包不包含任何服务内部实现。
• 如实报告失败。 非 2xx 响应或网络错误会变成明确的工具错误——绝不会返回看似正常的空结果。Agent 始终可以分辨失败与通过。
• 基于官方的 @modelcontextprotocol/sdk + x402 构建。

许可证

MIT — 详见 LICENSE。

有疑问？请联系：[email protected] · getplexa.com

链上信息数据和启发式经济信号，不构成财务建议。没有风险标记不代表安全。交易前请独立核实。