Lumi Trades: x402 seller checks and test-buys

lumi-trades-mcp

用于 Lumi Trades 的 MCP 服务（stdio）：Lumi Check，在你的 Agent 向 x402 卖家付款前，免费进行带签名的允许／警告／拦截检查，并由 Lumi 在 XRPL、Base 和 Stellar 上实际付费测试购买作为依据。此外，还提供每日机构与政策简报、加密货币市场数据，以及作为独立产品线的Lumi Trades 市场读数，覆盖 50 种币（仅供教育参考，不构成建议）。适用于 Claude Desktop、Cursor、Claude Code、Cline、Windsurf 及任何其他 MCP 客户端。 付费工具通过 x402 按次付费，使用你自己的钱包：Base 上的 USDC（免 gas），或 XRP Ledger 上的 XRP / RLUSD / USDC （该 API 也接受 Stellar 上的 USDC；此软件包仅支持通过 Base 或 XRP Ledger 付款）。 无需 API 密钥或账户：每次调用付费工具只需支付一笔小额款项，并在你的设备上本地签名。

仅供分析和教育参考。不构成财务建议，也不构成买入、卖出或持有的建议。读数是机械生成的动量／趋势摘要，并非预测。

Lumi Trades 市场读数（lumi_signal、lumi_lite、lumi_scan、lumi_levels、lumi_slate）：仅供参考，不构成投资建议。Lumi 不进行真实资金交易。

**无需安装即可浏览：**同一组工具也通过 https://api.lumitrades.io/mcp（Streamable HTTP）远程提供， 适用于支持远程 MCP 服务 URL 的客户端。远程连接器没有钱包，因此其付费工具会返回价格和付款方式； 如果你希望付费工具自动从自己的钱包扣款，请使用此软件包。

工具

通用（免费）

工具	付费？	价格（USD）	提供内容
lumi_catalog	免费	–	端点、实时价格、本服务的钱包及支出上限
lumi_samples	免费	route?	每款付费产品的截断标注样例，包含 USD 价格和完整 URL
lumi_coins	免费	–	列出全部 50 种币：每种币的趋势读数；仅为 13 种观察列表／主要币提供参考区间（XRP XLM HBAR XDC AXL ZBCN SHX BTC ETH DOGE ADA LINK SUI）
lumi_quote	免费	–	查询任意付费路径的 x402 报价，无需付款

Lumi Trades 卖家检查（x402）

工具	是否付费？	价格（USD）	可获取内容
lumi_verdict	$0.01	url payTo? amount?	付款前获取一个标签；数据和签名方式与 /v1/check 相同：checks_passed（近期检查已通过）/ check_first（先检查）/ checks_failed（近期检查未通过）/ no_data（数据不足），并提供日期、证据时间范围、样本数量、原因代码、证据和申诉链接。向 Lumi 付费绝不会改变结果
lumi_vendor_scores	免费	url? domain? payTo? vendor_id?	付款前查询任意 x402 卖家的信息：等级（已收录 / 已检查报价、置信度低 / 已测试购买）、最近一次免费的 402 报价检查、价格和 payTo 与其 Bazaar 列表的对比，以及链上测试购买证据。不传参数：显示 Lumi 精选的卖家评分
lumi_seller_monitoring	免费	enrollment_id?	卖家监控方案（每个端点每 30d：Watch $5、Watch Plus $12、Watch Pro $20；10 个以上端点可享 -20% 折扣，或预付 3 个期限可享 -10% 折扣，不可叠加；Audit 一次性收费 $99；免费 Watch 级别；Watch Plus 可免费试用 14 天）及注册步骤；传入 id 后，可查看该卖家的公开条目和徽章。付费绝不会改变评分
lumi_trust_feed	免费	–	信任数据源方案（免费密钥每月可查询 1,000 次、Feed $99/30d、Feed Pro $199/30d）及许可条款
lumi_check	免费	url? pay_to? amount_usd? network?	付款前对任意 x402 卖家进行 Lumi Check：根据原因给出允许 / 警告 / 拦截，并提供卖家评分及其实时报告链接。由 Lumi 签名并在本地验证。仅发送 URL 的源站和路径。失败时放行：若 2.5 s 内无法连接 Lumi，则发出警告
lumi_scan_seller	免费	url	获取 x402 卖家的 402 报价而无需付款，并根据本地限额提供模拟测试购买方案
lumi_report_receipt	免费	endpoint network tx_hash …	为已完成的购买签署收据。submit: true 是二级共享：默认关闭，需设置 LUMI_SHARE_RECEIPTS=1 或运行 lumi-scan sharing on。共享付款的链和交易 ID；这些信息公开记录在链上，且可关联到付款钱包。经过验证的收据仅用于获取公开徽章
lumi_trust_check	付费	$0.02	对即将付款的任意 x402 URL 进行付款前检查：检查 payTo/价格是否与列表及 Lumi 的观察结果一致。必须提供 url
lumi_vendor_report	付费	$0.02	Lumi 信任列表中某个 x402 卖家的完整观察历史：每次报价检查（90 天内）和付费测试购买（含 tx hash 及是否交付），延迟统计和趋势、正常运行时间百分比、Agent 报告、卖家回复及置信度标签。必须提供 vendor_id

市场数据

工具	是否付费？	价格（USD）	可获取内容
lumi_brief	付费	$0.02	今日市场简报（BTC、CoinMarketCap Fear & Greed、涨跌幅领先币种、关键价位、日元、事件、新闻；不含交易计划）。使用 format: "md" 可获取 markdown 格式
lumi_market	付费	$0.02	BTC、宏观背景和市场广度
lumi_macro_yen	付费	$0.01	USD/JPY、Nikkei、155 附近的套利交易风险及日本事件
lumi_sentiment	付费	$0.005	Fear & Greed、资金费率解读、OI、市场占有率、市场广度
lumi_events	付费	$0.005	有来源佐证的即将发生的宏观 / 加密货币事件和催化因素
lumi_funding	付费	$0.003	Lumi 在 OKX 上列出的所有币种的永续合约资金费率（按 8 小时标准化、年化，并附通俗解读）
lumi_fear_greed	付费	$0.003	CoinMarketCap Fear & Greed 当前值与昨日 / 上周 / 上月对比、年度高低点、30 天走势
lumi_events_48h	付费	$0.003	未来 48 小时内的日程（UTC + 美国中部时间）、事件重要性及来源
lumi_institutional_brief	付费	$0.10	每日机构与政策简报：梳理 BIS、IMF、美国财政部 / 监管机构、JPMorgan、SBI、Cross River、Securitize、R3 等与 XRP、XLM、XDC、QNT、AXL、HBAR 的关联（区分已确认关联与间接一致性关联，并附来源）。使用 format: "md" 可获取 markdown 格式。符合默认限额（0.30 USD / 0.25 XRP）
Lumi Trades 市场读数（仅供参考，不构成投资建议。Lumi 不会使用真实资金进行交易。）

工具	付费？	价格（USD）	可获取内容
lumi_signal	付费	$0.01	单个币种的动量/趋势倾向（正面/中性/负面）及评分（1h/4h/1d + 指标）
lumi_levels	付费	$0.01	单个币种的图表参考区域及说明
lumi_scan	付费	$0.02	全市场筛查：49 种大市值币种的动量/趋势倾向、评分、1h RSI、价格和 24h 涨跌幅，按评分从高到低排列
lumi_lite	付费	$0.004	单个币种的简要概览：标签、评分、1h/4h/1d 标签、价格、24h 涨跌幅
lumi_slate	付费	$0.02	当前关注列表的动量/趋势倾向（不含入场点、止损位、目标价或杠杆）

付款方式按优先顺序排列：1. Base 上的 USDC（免 Gas，EVM_PRIVATE_KEY），2. XRP Ledger（XRPL_SEED）： 按相同的美元价格使用 RLUSD 或 USDC 付款，或按实时 XRP/USD 汇率使用 XRP（每次调用时报价，并向上取整至 0.0001 XRP）。 价格根据每次 402 报价实时读取；表格仅供参考。只有在获取到数据时才会收费：如果数据缺失或过期，API 会拒绝报价 （503，"Not charged."），因此没有数据时绝不会完成付款。

安装

需要 Node 20+。已发布到 npm，包名为 lumi-trades-mcp，也已收录于 官方 MCP Registry，名称为 io.github.cypher-osiris/lumi-trades-mcp。

npx -y lumi-trades-mcp

Claude Desktop / Cursor / 任意 MCP 客户端（mcpServers JSON）

{
  "mcpServers": {
    "lumi-trades": {
      "command": "npx",
      "args": ["-y", "lumi-trades-mcp"],
      "env": {
        "EVM_PRIVATE_KEY": "0x...your Base agent wallet key (holds USDC, no ETH needed)...",
        "LUMI_MAX_USD_PER_CALL": "0.30",
        "LUMI_SESSION_BUDGET": "1"
      }
    }
  }
}

改用 XRP Ledger 付款：设置 "XRPL_SEED": "sEd..."（也可选择设置 "LUMI_PAY_ASSET": "RLUSD" 或 "USDC"，默认值为 XRP）来替代 EVM_PRIVATE_KEY。

从克隆的仓库运行：设置 "command": "node", "args": ["/absolute/path/to/lumi-api/mcp/src/index.js"]（在 mcp/ 中执行 npm install 后）。 Claude Code：claude mcp add lumi-trades -e EVM_PRIVATE_KEY=0x... -- npx -y lumi-trades-mcp（或使用 -e XRPL_SEED=sEd...）。

没有钱包也能使用免费工具；付费工具会返回价格报价，而不会收款。

在自己的代码中使用 Lumi Check（x402 / MCP hooks）

import { lumiCheckHooks } from "lumi-trades-mcp/src/check.js";
const { lumi, x402Hook, mcpHook } = await lumiCheckHooks();   // options: { failMode: "open"|"closed", timeoutMs, publicKeys }

x402Client.onBeforePaymentCreation(x402Hook);   // @x402 core: returns { abort: true, reason } on "block"
mcpClient.onPaymentRequired(mcpHook);           // @x402/mcp: returns { abort: true } on "block" (checked by payTo)
const v = await lumi.check({ url, payTo, amountUsd: 0.01 }); // { decision, reasons, score, link, verified }

默认行为：失败时放行（发生超时或无法验证答案时会给出 warn，并继续付款），超时时间为 2.5 s。设置 failMode: "closed" 可改为阻止操作。向 Lumi 付款不会改变任何卖家的评分、等级、排名或徽章。 适配器来自 npm 上的 lumi-check（Apache-2.0）；评分和验证仍由 Lumi 的服务端完成。

该工具包分享的内容：只有用户同意后才会分享。 lumi-scan CLI 会在首次检查后询问一次（"Share your results to help improve Lumi's public trust list? [Y/n]"）。MCP 服务无法提问，因此在此处分享默认关闭，并会向 stderr 写入一条提示；可通过 LUMI_CHECK_TELEMETRY=on 或 lumi-scan telemetry on 开启。Tier 1 仅在付费调用后分享匿名的交付结果： 卖家主机、是否成功交付、粗略的状态类别和随机的一次性令牌。不包含钱包、金额、交易哈希、查询字符串或稳定 ID。分享绝不会改变任何评分。Tier 2（默认关闭）会发送完整的签名回执。 每份回执都会分享付款所用的区块链和交易 ID（不含金额或钱包字段）；交易 ID 在链上公开，并可与付款钱包关联。 贡献者只会获得公开徽章，不会获得任何有货币价值的奖励。详见该工具包的 README。

配置（环境变量）

变量	默认值	含义
EVM_PRIVATE_KEY	–	你的 Base 钱包的 0x 私钥，用于通过 EIP-3009 授权以 USDC 付款（免 Gas：由支付中介支付 Gas）。仅保存在内存中；绝不记录日志、返回给模型或发送到任何地方（只发送签名）。请使用余额较低的专用 Agent 钱包。
XRPL_SEED	–	你的 XRPL 付款钱包的种子。仅保存在内存中；绝不记录日志、返回给模型或发送到任何地方（付款在本地签名，API 只接收已签名的数据块）。请使用余额较低的专用 Agent 钱包。
LUMI_PAY_ASSET	如果设置了 XRPL_SEED，则为 XRP；否则为 BASE_USDC	BASE_USDC（Base 上的 USDC），或 XRP Ledger（XRPL）上的 XRP、RLUSD、USDC（XRPL 稳定币需要信任线和余额）
LUMI_MAX_XRP_PER_CALL	0.25	拒绝任何高于此值的 XRP 报价
LUMI_MAX_USD_PER_CALL	0.30	拒绝任何高于此值的稳定币报价（Base 或 XRPL）。拒绝消息会注明此变量及所需的值
LUMI_SESSION_BUDGET	1	每个服务进程的最高总支出，以付款资产计
XRPL_NETWORK	xrpl:0	xrpl:0 为主网，xrpl:1 为测试网
LUMI_API_URL	https://api.lumitrades.io	API 基础 URL
LUMI_EXPECTED_PAY_TO	官方 API 上 Lumi 的钱包：rM8kmmnz5qPMg7V3r7SHYXgDGvm8PhzLvM（XRPL 主网）、0x5E617bac19912e6d212CB303ae84655E9E203532（Base）	拒绝向任何其他地址付款
LUMI_CHECK_API	LUMI_API_URL	lumi_check 的基础 URL
LUMI_KIT_HOME / LUMI_KIT_CONFIG	~/.lumi-scanner-kit/config.json	工具包配置（保存的分享选项、遥测和分享开关）
LUMI_CHECK_TELEMETRY	关闭（直到用户同意）	on 启用一级结果报告，off 禁用；优先于已保存的选项
LUMI_SHARE_RECEIPTS	关闭	1 启用二级收据提交
LUMI_CONTRIB_KEY_FILE	–	用于二级提交的贡献者密钥（lumi-scan keygen）
XRPL_WS_URL	wss://xrplcluster.com / wss://testnet.xrpl-labs.com	用于自动填充和签名的账本连接

安全性：签名前，服务会检查网络、方案、资产、收款方、单次调用上限和会话预算。任何一项不符都不会签名。每项付费结果都包含链上交易哈希。

测试

npm test                         # spend-cap / payee / settings unit tests + a mocked Base USDC payment through @x402/fetch
node scripts-e2e-testnet.mjs     # testnet only: real x402 payments through MCP against a local testnet API (see the file header)

测试网运行记录，2026 年 10 月 22 日（通过 MCP stdio，在 XRPL 测试网上使用 x402，全部为 tesSUCCESS）：lumi_sentiment 9137C1AE…、lumi_macro_yen 38DDADD0…、lumi_events EBD235D3…、lumi_trades 661D8180…、lumi_brief（markdown）16F1BEFA…。

许可证

MIT