horizon-pulse

Horizon Pulse

按次付费的加密市场 pulse、signals、funding、yield 排名、portfolio 风险、gas，以及公开 URL fetch → 清理后的文本、通用 http 代理和 extract → 为 AI Agent 提取结构化字段；通过 x402 协议在 Base mainnet 和 Solana mainnet 上实现变现（USDC、exact，两者价格相同）。

此仓库是一个可部署的 Next.js App Router 服务（例如部署到 Vercel），可推送到：

https://github.com/horizon-pulse/horizon-pulse.git

公共主机

角色	URL
规范主机	https://horizonpulse.dev
备用（Vercel）	https://horizon-pulse-seven.vercel.app

在 Agent 文档、OpenAPI 和客户端中优先使用 horizonpulse.dev。*.vercel.app URL 仍可作为有效备用地址。

项目简介

• Agent 可调用实时付费 HTTP 端点（加密路由已冻结；/api/fetch + /api/http + /api/extract + /api/x402-check + /api/bazaar-check + /api/market/search + /api/market/quote + /api/screenshot + /api/search + /api/pdf 等非加密功能已上线——见下文）。
• 未付费请求会收到带有 x402 v2 要求的 HTTP 402：规范传输方式为 PAYMENT-REQUIRED 标头，每个网络各有一个 accepts 条目：Base（CAIP-2 eip155:8453、Base USDC、下文所述 treasury）和 Solana（CAIP-2 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp、USDC mint、下文所述 Solana payTo）。参见 docs/solana-rail.md。
• 使用 x402 v2 PAYMENT-SIGNATURE 标头重试。facilitator（Base 上的 Coinbase CDP、Solana 上的 PayAI）会验证并结算，随后路由返回实时数据。
• 不使用占位价格或虚假 APY：现货数据来自 Coinbase Exchange（CoinGecko 备用）；信号数据来自 CoinGecko OHLC（Coinbase candles 备用）；永续合约资金费率来自 OKX（Binance/Bybit 在 Vercel 上经常受地域限制）；收益池数据来自 DefiLlama；投资组合数据来自公共 RPC balanceOf（仅真实余额）；gas 数据来自 eth_feeHistory / eth_gasPrice（仅真实费用）；/api/fetch 会尽力从所请求的公开 URL 返回清理后的文本（防 SSRF，限制大小和耗时）；/api/http 是原始通用代理（过滤标头，文本|base64 正文，防 SSRF），定价为 $0.01，用于提升调用量；/api/extract 会尽力从 URL 或 HTML 返回结构化页面字段（防 SSRF，限制大小和耗时），定价为 $0.015。
• 绝不捏造指标；绝不宣传会返回 404 的路由；绝不引用缓存余额——/status 会读取 payTo 上的实时 USDC balanceOf。如实说明：当前 payTo 为临时 Coinbase 托管地址（并非 Safe/多签）。

目录状态（首次结算后）

事实	值
已上线付费路由	30：见下表（29 个多网络路由 + 仅限 Base、经验证的 $1 简报）
首次结算	/api/pulse $0.005 — 交易 0xedbd1a51…
加密策略	已冻结 — 六个加密路由：价格不变
Fetch	非加密功能已上线：纯文本（$0.02）
Http	非加密功能已上线：通用代理（用量价格 $0.01）
Extract	非加密功能已上线：结构化 HTML（$0.015）

即将推出／占位／返回 404 的路由不会列在 /、/status 或此 README 中。

Agent 使用方法（x402 v2）

1. 对付费路由发送不带付款信息的 GET 请求 → HTTP 402。
2. 读取 PAYMENT-REQUIRED（v2）并选择一个 accepts 条目。确认 network（Base 为 eip155:8453，Solana 为 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp）、该网络上的 USDC、精确的原子单位 amount，以及该网络对应的 payTo。
3. 签名后使用 PAYMENT-SIGNATURE（v2 首选；不要依赖旧版 X-PAYMENT 作为结算方式）重试相同的 GET 请求。
4. 成功后：facilitator 会在你付款所用的网络上完成结算；响应正文是该路由返回的实时 JSON。

可选：对付费路由发送 OPTIONS 请求，可获取发现信息和相同的 PAYMENT-REQUIRED 挑战，且不会扣费。

Agent 集成

• 技能文件： /skill.md，纯 Markdown 格式，Agent 可按步骤完整执行（由 lib/agent-skill.ts 根据 public/openapi.json 生成）。
• 指南： /agents：支付流程、技能和 MCP 设置。
• 本地 MCP 服务： mcp/，使用 stdio，每个实时路由都作为工具提供；使用你配置的买家钱包支付 x402 挑战，并设有单次调用和单个会话的上限（不配置密钥时仅提供报价）。未发布到 npm；请从此仓库安装。
• 托管 MCP： POST https://horizonpulse.dev/mcp（可流式传输的 HTTP），供能够自行支付 x402 的 MCP 客户端使用。通过 MCP 进行的支付仅支持 Base 上的 USDC；付费 HTTP 路由支持 Base、Solana、Polygon 和 XRPL。

金库（payTo）

字段	值
payTo	0x5b32c973596078a967562ca652761404f19be0e9
Basename	horizonpulsebase.base.eth（解析为上方的 payTo；仅为标签，402 中携带的是十六进制地址）
托管方式	临时使用 Coinbase 托管的 Base 地址（由所有者控制）。不是 Safe 或多签地址。
升级路径	准备就绪后可迁移到非托管 Safe / 多签地址，目录和价格保持不变。
USDC（Base）	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
网络	base（CAIP-2 eip155:8453）
支付协调器	https://api.cdp.coinbase.com/platform/v2/x402
Solana payTo	BjY98A6dS3GGLZdz2zHy8wK7XAwnQgNhCc66mfmBTRPz（由运营方控制；固定在 lib/solana-config.ts 中；支付款项会记入其 USDC 代币账户）
USDC（Solana）	EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
Solana 网络	CAIP-2 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp（仅限 exact）
Solana 支付协调器	PayAI https://facilitator.payai.network

请勿使用已停用的地址 0xe16A1b12404cB2EbC6e783beCA6E2A9253c3dC7E。

PAY_TO 可通过环境变量覆盖，但默认值为上方的地址。Agent 应将当前的 payTo 视为有效的结算目的地；之后托管方式可能变更，但路由价格不会改变。

端点

付费（30 条路由：29 条多网络路由 + 仅限 Base 的 $1 验证简报；列表与 /.well-known/x402 相同）：

路由	价格	身份验证
GET /api/pulse	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/signals	$0.005 USDC（5000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/yield	$0.02 USDC（20000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/portfolio	$0.04 USDC（40000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/gas	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/funding	$0.003 USDC（3000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/fetch	$0.02 USDC（20000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET / POST /api/http	$0.01 USDC（10000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET / POST /api/extract	$0.015 USDC（15000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/x402-check	$0.01 USDC（10000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/x402-check/deep	$0.03 USDC（30000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/bazaar-check	$0.01 USDC（10000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/market/search	$0.005 USDC（5000 atomic），价格未经测试	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/market/quote	$0.005 USDC（5000 atomic），价格未经测试	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/tx-status	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/tokenized-stock	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/watch	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/balance	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/tx-guard	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET / POST /api/grocery/normalize	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET / POST /api/grocery/ingredient	$0.005 USDC（5000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/chain/head	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/token/meta	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/name/resolve	$0.002 USDC（2000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET / POST /api/batch	$0.01 USDC（10000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/discourse/split	$0.03 USDC（30000 atomic），价格未经测试	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/screenshot	$0.02 USDC（20000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/search	$0.03 USDC（30000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/pdf	$0.02 USDC（20000 atomic）	x402 v2（Base、Solana、Polygon、XRPL）
GET /api/research/report/brief?q=…	$1 USDC（1000000 atomic）：至少有 2 项主张得到两份来源确认，来源定义见合约（两个独立节点，或两份独立规范文档）；否则不收费（合约，条款）	x402 v2（仅限 Base USDC）

免费（非付费 API）：

路由	身份验证
GET /status	公共 HTML — 在 payTo 上实时查询 USDC balanceOf（获取失败时如实返回 RPC 错误）
GET /	落地页 — 实时付费目录 + Agent 使用指南

GET /api/pulse

BTC / ETH / SOL 的真实现货价格（Coinbase Exchange，CoinGecko 备用），包含各资产的动量，以及整体动量 / 情绪 / 方向（up/down/flat，即对平均 24 小时变动的中性描述；由 signal 重命名而来，详见 CHANGELOG.md）。

• runtime = 'nodejs'
• 发现方式：Bazaar 扩展 + 付款要求中的 outputSchema.input.discoverable: true

GET /api/signals

基于 CoinGecko OHLC 收盘价计算的 RSI(14)、MACD(12,26,9)、布林带，以及 OKX 资金费率。包含 methodology 字段。

• runtime = 'nodejs'
• 可供 Agent 发现

GET /api/yield

来自 DefiLlama 公共收益 API（https://yields.llama.fi/pools）的 DeFi 收益池排名。

• 硬性筛选：TVL ≥ $10M；排除 APY 非有限值以及 DefiLlama 标记为 outlier 的池
• 优先项：保留稳定币和/或单资产（exposure === "single"）池
• 排名透明：按 preferenceTier 降序（2 = 稳定币+单资产，1 = 任一符合），再按 APY 降序，最后按 TVL 降序
• 每个响应均包含 methodology 对象（错误响应正文中也包含）
• 价格：$0.02 USDC（20000 原子单位）
• runtime = 'nodejs'，dynamic = 'force-dynamic'
• 未付款的 GET → 402 + PAYMENT-REQUIRED（v2，eip155:8453）· payTo 0x5b32c973596078a967562ca652761404f19be0e9

GET /api/portfolio

一个 EVM 地址的链上投资组合快照（必填参数：?address=0x…）。

• 网络：Base + Ethereum 主网（公共 RPC；可选 BASE_RPC_URL / ETH_RPC_URL，并支持故障切换）
• 代币：原生 ETH；两条链上的 USDC、WETH、DAI；Ethereum 上的 WBTC；Base 上的 cbBTC（如实替代——Base 上没有 BitGo WBTC）
• 通过 Coinbase 公共汇率标记 USD 价格（其余情况或 Coinbase 故障时使用 CoinGecko）；仅显示真实余额——若 RPC 失败，该网络会在 networks[] / warnings 中标记为失败
• 基于规则的集中度评分（0–100）和规则发现项（最大资产权重与 35%/50% 阈值的比较、稳定币占比与 15%/85% 阈值的比较、最大链占比与 85% 阈值的比较、原生 ETH Gas 余额偏低；以纯文本发现项的形式返回在 suggestions 数组中，不包含指令），并在 methodology 中公开透明公式
• 价格：$0.04 USDC（40000 原子单位）
• runtime = 'nodejs'，dynamic = 'force-dynamic'
• 未付款的 GET → 402 + PAYMENT-REQUIRED（v2，eip155:8453）· payTo 0x5b32c973596078a967562ca652761404f19be0e9

GET /api/gas

来自公共 RPC 的 Base 和 Ethereum 实时 Gas 快照。

• 优先使用 eth_feeHistory（最近 20 个区块，奖励百分位数为 10/50/90）：baseFeeGwei、priorityFeeGwei（p50）、suggestedMaxFeeGwei（= 2×baseFee + priority）
• feeHistory 不可用时，回退到 eth_gasPrice
• 透明的 timingHint：根据 feeHistory 时间窗口内最新已确认 baseFee 的百分位排名得出 cheap / normal / expensive（<33 / 33–67 / >67）；在 methodology 中说明——并非预测
• 可选的 ETH USD 价格（Coinbase Exchange，CoinGecko 备用），用于估算简单的 21k Gas 转账成本（simpleTransfer.costUsd）
• 价格：$0.01 USDC（10000 原子单位）
• runtime = 'nodejs'，dynamic = 'force-dynamic'
• 未付款的 GET → 402 + PAYMENT-REQUIRED（v2，eip155:8453）· payTo 0x5b32c973596078a967562ca652761404f19be0e9

GET /api/funding

来自 OKX 的 BTC / ETH / SOL 实时永续合约资金费率（与 /api/signals 使用相同数据源；适配 Vercel——不是 Binance/Bybit）。

• 复用 lib/okx.ts（fetchAllFunding）
• 每个响应（包括错误响应）均提供透明的 methodology
• 可选的拥挤度提示，仅依据资金费率的正负和幅度（规则：quiet / mild / elevated / extreme；方向为 longs/shorts/neutral）——并非预测
• 如实说明：仅使用真实 OKX 数据
• 价格：$0.01 USDC（10000 原子单位）——面向 Agent 的低价轮询产品
• runtime = 'nodejs'，dynamic = 'force-dynamic'
• 未付款的 GET → 402 + PAYMENT-REQUIRED（v2，eip155:8453）· payTo 0x5b32c973596078a967562ca652761404f19be0e9

GET /api/fetch

抓取一个公开的 http(s) URL（必填：?url=https://…），并尽可能返回清理后的文本/Markdown。

• 防 SSRF：阻止 localhost、私有、链路本地和元数据 IP；每次重定向都会重新检查
• 限制：原始响应体约 200KB，超时 8s，最多重定向 3 次
• 首选 Content-Type：text/html、text/plain、application/json、text/markdown
• 清理尽力而为（移除脚本/样式/页面界面元素、折叠空白），并非完整的可读性引擎
• 价格：$0.02 USDC（20000 个最小单位）
• runtime = 'nodejs'，dynamic = 'force-dynamic'
• 未付款的 GET → 402 + PAYMENT-REQUIRED（v2，eip155:8453） · payTo 0x5b32c973596078a967562ca652761404f19be0e9

GET / POST /api/http

通用的Agent HTTP 代理——使用可选的方法/标头/请求体调用公开的 http(s) URL；返回上游的 status、经过筛选的 headers 和 body（text 或 base64），以及 contentType 和 elapsedMs。

• **价格选择：**面向大流量定价为 $0.01 USDC（10000 个最小单位）。/api/fetch 仍为 $0.02（专用的清理文本接口）。原始代理流量优先使用 /api/http。
• 输入：url（必填）；method（默认为 GET；GET|POST|HEAD|PUT|PATCH|DELETE）；可选的允许列表中的 headers（不允许 Cookie/逐跳标头）；POST/PUT/PATCH 可选的 body（有大小限制）
• GET 查询：?url=&method=&headers=<json>；POST JSON 请求体可全面控制，包括上游请求体
• 防 SSRF（与 /api/fetch 共用防护）：阻止私有/链路本地/元数据地址；仅允许 http/https；重定向时重新检查
• 限制：响应体约 384KB，请求体 64KB，超时 12s，最多重定向 3 次
• 结果准确：跳转成功时，上游 4xx/5xx 会通过 status 返回；代理失败则使用准确的错误代码
• runtime = 'nodejs'，dynamic = 'force-dynamic'
• 未付款的 GET/POST → 402 + PAYMENT-REQUIRED（v2，eip155:8453） · payTo 0x5b32c973596078a967562ca652761404f19be0e9
• Bazaar 发现机制公布 GET；POST 的付费方式相同

GET / POST /api/extract

URL 或 HTML → 面向 Agent 的结构化页面字段（标题、描述、规范链接、语言、链接、图片、标题层级、json-ld、文本样本）。

• 价格选择： $0.015 USDC（15000 个最小单位）——介于 /api/http（$0.01）和 /api/fetch（$0.02）之间。使用相同的 payTo 和 Base USDC 栈。
• 输入：url（若提供 html 则可选）和/或 html（有大小限制）。抓取 url 时，优先使用与 fetch/http 相同的防 SSRF assertSafePublicUrl。
• GET 查询：?url=&fields=<url-encoded json>；POST JSON { url?, html?, fields? }，用于提交 html 内容
• 可选的 fields：最多 20 个带名称的 CSS 选择器，例如 {"title":"h1","links":{"selector":"a.story","attr":"href","all":true,"limit":5}}。attr 可以是 text（默认值）、html 或任何属性（href/src 会解析为绝对 URL）。未匹配的字段会返回 null，并在 fieldErrors[name] 中记录错误（no_match、bad_selector、attr_missing、time_budget、document_too_deep、eval_failed）。若没有字段匹配：返回 422 no_fields_matched，不收费。选择器预算硬性限制为 2s；每个选择器最多使用一次 :has()；嵌套层级超过 256 层的页面不会处理字段。选择器结果确定，不使用 AI。
• 轻量级正则解析（不使用 cheerio）。不返回空字段。并非完整的浏览器 DOM。
• 限制：HTML 约 200KB，超时 8s，最多重定向 3 次（与 /api/fetch 处于相同范围）
• 不使用 Cookie jar。会阻止私有/localhost/链路本地/元数据地址。
• runtime = 'nodejs'，dynamic = 'force-dynamic'
• 未付款的 GET/POST → 402 + PAYMENT-REQUIRED（v2，eip155:8453） · payTo 0x5b32c973596078a967562ca652761404f19be0e9
• Bazaar 发现机制公布 GET；POST 的付费方式相同

GET /status

公开页面，显示 Base 上 payTo 地址的实时 USDC 余额（通过公共 RPC / BASE_RPC_URL balanceOf），以及实时付费目录和 Agent 使用指南。

• RPC 失败时，页面会显示真实的错误——不会回退到缓存余额。托管说明：目前暂由 Coinbase 托管 payTo（不是 Safe/多签）；之后再升级。
• 首笔结算记录为 /api/pulse $0.005（0xedbd1a51…）；六个加密货币路由已冻结；/api/fetch + /api/http + /api/extract 则有意保持运行。

本地开发

需要 Node.js 20+（已在 20.19 上测试）。

cd horizon-pulse
cp .env.example .env.local
# fill CDP_API_KEY_ID + CDP_API_KEY_SECRET for verify/settle
npm install
npm run dev

npm run build && npm start

环境变量（Vercel / 生产环境）

从 .env.example 复制：

变量	必需	说明
X402_NETWORK	建议	base
PAY_TO	可选	默认为 0x5b32c973596078a967562ca652761404f19be0e9
CDP_API_KEY_ID	用于结算	Coinbase Developer Platform
CDP_API_KEY_SECRET	用于结算	PKCS8 PEM（请妥善保管；切勿提交）
BASE_RPC_URL	可选	覆盖 /status + /api/portfolio + /api/gas 的默认 Base RPC
ETH_RPC_URL	可选	覆盖 /api/portfolio + /api/gas 的默认 Ethereum RPC

如果没有 CDP 密钥：

• 未付费的 GET 和 OPTIONS 仍会返回正确的 402 / 发现信息，其中包含 v2 PAYMENT-REQUIRED（payTo、eip155:8453、USDC 金额）——发现信息不需要 CDP。
• 包含 PAYMENT-SIGNATURE（或旧版 X-PAYMENT）的请求会收到 503，直到在 Vercel 上设置 CDP_API_KEY_ID + CDP_API_KEY_SECRET（结算路径）。
• 不要预期缺少 CDP 时实时 GET 会返回 500；这是先前的错误，现已修复：只有在存在付款信息和 CDP 凭据时才会启用 withX402。

技术栈

• Next.js 16（App Router）+ TypeScript
• @x402/next + @x402/core + @x402/evm + @x402/extensions
• 用于 CDP facilitator 身份验证标头的 @coinbase/x402
• viem：用于 Base 上的金库 USDC balanceOf、投资组合余额，以及 Base + Ethereum 上的 gas feeHistory

部署说明

1. 创建 GitHub 仓库 / 远程仓库 https://github.com/horizon-pulse/horizon-pulse.git。
2. 设置 Vercel 环境变量（见上文）。如果界面仅支持单行，建议将 PEM 密钥写成包含 \n 转义符的单行。
3. 从 main 部署。确保函数使用 Node.js 运行时（路由已设置 export const runtime = 'nodejs'）。
4. 冒烟测试：curl -i https://horizonpulse.dev/api/pulse（或 /api/yield、/api/portfolio、/api/gas、/api/funding、/api/fetch?url=https://example.com、/api/http?url=https://example.com、/api/extract?url=https://example.com）应返回 402，付款要求中指向新的 payTo。
5. 确认 /status 显示金库地址 0x5b32…e0e9 的余额。

推送（在此工作区中）

此脚手架不会替你推送（无凭据）。请在已完成 GitHub 身份验证的机器上执行：

cd /workspace/horizon-pulse
git init
git add .
git commit -m "feat: Horizon Pulse x402 API with new Base treasury"
git branch -M main
git remote add origin https://github.com/horizon-pulse/horizon-pulse.git
git push -u origin main

如果远程仓库已有提交历史：

git remote add origin https://github.com/horizon-pulse/horizon-pulse.git
git fetch origin
git pull origin main --rebase   # or merge, as appropriate
git push -u origin main

参考 Agent（examples/）

脚本中列出的实时付费路由支持未付费 402 发现信息；如果设置了 SMOKE_PRIVATE_KEY，还可选用单个付费路由：

cd horizon-pulse
node examples/reference-agent.mjs
# optional paid:
SMOKE_PRIVATE_KEY=0x... SMOKE_ROUTE=/api/pulse node examples/reference-agent.mjs

参见 examples/README.md。使用此软件包中的 @x402/core + @x402/evm。切勿提交密钥。

付费冒烟测试（/api/pulse）

针对生产环境（或 SMOKE_BASE_URL）进行端到端检查：未付费 402 → 使用本地密钥签署 EIP-3009 / x402 → 付费 200 + 链上 USDC 转入 payTo。

cd horizon-pulse
npm install   # if needed; uses existing @x402/* + viem
SMOKE_PRIVATE_KEY=0x... node scripts/smoke-pulse.mjs
# or: npm run smoke:pulse

可选：

SMOKE_BASE_URL=https://horizonpulse.dev
# backup: https://horizon-pulse-seven.vercel.app
BASE_RPC_URL=https://mainnet.base.org

**切勿在聊天、提交或截图中粘贴私钥。**仅在本地 shell 中导出私钥（例如 Mac mini）。如果未设置 SMOKE_PRIVATE_KEY，脚本会显示用法帮助后退出（安全的试运行）。

许可证

私有 / 由 horizon-pulse 组织指定。