内容
# hood-alerts
[](./LICENSE)
[](https://deploy.cloud.run?git_repo=https://github.com/nirholas/robinhood-chain-alert-bot)
[](https://deploy.workers.cloudflare.com/?url=https://github.com/nirholas/robinhood-chain-alert-bot)
[](https://vercel.com/new/clone?repository-url=https://github.com/nirholas/robinhood-chain-alert-bot)
**Robinhood Chain** （链 ID 4663）的警报层：Telegram 和 Discord 机器人，以及可选的 X（Twitter）自动发布，由一个共享的检测引擎支持，监控发布、毕业、鲸鱼交易、股票代币价格变动、链上溢价/折价套利、持有者里程碑和流动性拉动警告。免费层 + x402 USDG 高级服务。
## 检测内容
| 检测器 | 主题 | 来源 |
| --- | --- | --- |
| 新代币发布 | `launches` (`launches:noxa`, `launches:odyssey`) | NOXA（即时 Uniswap v3 池）和 The Odyssey（债券曲线） |
| 债券曲线毕业 | `graduations` | Odyssey 曲线填充并迁移到锁定的 Uniswap v3 池 |
| 鲸鱼交易 | `whales`，或每个代币 `token:0x…` | Odyssey 曲线交易和 Uniswap v3 交换，全链范围，阈值以美元计 |
| 股票代币价格变动 | `stock:SYMBOL` | Chainlink 喂价，滚动窗口，签名百分比变动 |
| 链上溢价/折价（套利信号） | `premiums`（高级层） | DEX 中间价 vs Chainlink 喂价，滞后阶梯在 1/2/3/5/10/20/50% |
| 持有者里程碑 | 每个代币 `token:0x…` | Blockscout `token_holders_count`，穿越 10 到 100,000 |
| 流动性拉动警告 | `rugs`（高级层），或每个代币 `token:0x…` | 跟踪池的报价侧（USDG/WETH）储备急剧下降 |
每个事件在到达订阅者之前都会根据指纹进行去重，通过高级/静默时间/摘要门控路由，并渲染为平台原生卡片（Telegram HTML，Discord 嵌入，紧凑的 X 发布，或结构化的控制台日志行），并带有返回链上资源管理器和 `three.ws/markets/robinhood` 的链接。
## 快速开始（自托管）
```sh
npm install
npm run dev # tsx 监视，如果没有设置机器人令牌，则仅控制台传输
```
在没有环境变量的情况下，引擎仍然运行：检测器连接到公共的 Robinhood Chain RPC，警报以结构化的 JSON 日志行打印（控制台传输），并且 `/healthz` 在 `:8080` 上启动。这是自托管的烟雾测试模式。复制 `.env.example` 到 `.env` 并填写 Telegram 和/或 Discord 机器人令牌以在这些平台上上线；参见 `.env.example` 获取每个变量、默认值和每个检测器阈值控制。
```sh
npm run build # tsc -> dist/
npm start # node dist/src/index.js
```
### 创建机器人
- **Telegram**：消息 [@BotFather](https://t.me/BotFather)，`/newbot`，将令牌粘贴到 `HOOD_ALERTS_TELEGRAM_TOKEN`。机器人在启动时注册其命令列表。
- **Discord**：在 [开发者门户](https://discord.com/developers/applications) 上创建应用程序，添加机器人，复制机器人令牌到 `HOOD_ALERTS_DISCORD_TOKEN`，将应用程序 ID 粘贴到 `HOOD_ALERTS_DISCORD_APP_ID`。斜杠命令在启动时注册（立即在 guild 中可见）。
### X（Twitter）
X 是一个仅广播的传输：没有传入机器人，因此您无法像使用 Telegram 或 Discord 一样发送 DM 并获得回复。`HOOD_ALERTS_X_TOPICS`（默认 `launches,graduations,whales`）在启动时通过 `watch`/`unwatch` 命令固定 auto-posts 内容，而是通过相同的主题解析器解析，机器人使用。选择 `HOOD_ALERTS_X_MODE` 中的两个模式之一；参见 `.env.example` 获取完整变量列表。
**`official`**：真正的 X API v2，`POST /2/tweets`，使用您自己的开发者应用的 OAuth1 用户上下文凭证签名。这是正常、符合 ToS 的路径，并且需要付费：X 在付费 API 层后发布内容。在依赖它之前，请检查 [developer.x.com/en/portal/products/buy](https://developer.x.com/en/portal/products/buy) 的当前定价；它已经改变过，并且可以再次改变。
设置：在 [开发者门户](https://developer.x.com/en/portal) 上创建应用，生成消费者密钥/秘密（`HOOD_ALERTS_X_API_KEY` / `HOOD_ALERTS_X_API_SECRET`），然后使用 **读取和写入** 权限生成访问令牌/秘密（`HOOD_ALERTS_X_ACCESS_TOKEN` /`HOOD_ALERTS_X_ACCESS_SECRET`）。所有四个都是必需的； hood-alerts 使用 Node 内置的 `crypto`（HMAC-SHA1 per RFC 5849）签署每个请求，不需要额外的依赖。
**`xactions`**：通过自托管的 [XActions](https://github.com/nirholas/XActions) 实例发布，而不是官方 API：浏览器自动化驱动您的 X 会话 cookie。免费，无需开发者账户，无需付费层。这是 **不是** 官方 API，并带有真正的 ToS 风险；如果 X 按其规定处理，请使用您准备好损失的账户。指向 `HOOD_ALERTS_XACTIONS_URL` 您的运行实例和 `HOOD_ALERTS_XACTIONS_TOKEN` 及其持有者令牌。发布是异步作业队列的：hood-alerts 将 2xx 从 `POST {url}/api/posting/tweet` 视为“已接受”，而不是“已交付”，并且同步日志交付未确认（真正的 xactions API 响应 `{ operationId, status: "queued" }`，不是推文 ID）。
两种模式都失败得很响亮：配置的模式丢失任何必需的凭证都会记录警告并禁用 X 传输（Telegram、Discord 和控制台传输保持运行）而不是崩溃进程。每个 X 发布都被压缩以适应 X 的 280 个字符限制：标题，单个最重要的行和第一个链接；只有文本部分被截断，从不 URL。摘要（要发布的警报太多）发布单个最显著的事件和 `(+N more)` 计数，并记录完整汇总的批处理，因此没有任何内容被静默删除，即使它被发布本身删除。
## 机器人命令
两个机器人共享一个命令路由器（`src/commands/commands.ts`），因此 UX 在原生斜杠命令与 `/command arg` 语法方面是相同的：
```
watch <what> [threshold]
launches 每个新代币（添加 noxa/odyssey 进行筛选）
graduations Odyssey 曲线迁移到 Uniswap v3
whales [usd] 交易 >= usd，全链范围（默认 5000）
premiums [pct] 股票代币 DEX 溢价/折价 vs Chainlink（高级层）
rugs [pct] 流动性拉动警告（高级层）
<TICKER> 股票代币：价格变动 + 溢价交叉（例如 TSLA）
<0x 地址> 一个 memecoin：鲸鱼交易，毕业，持有者，流动性
unwatch <what|all> 停止监视
list 您的订阅
threshold <what> <n> 更改订阅的阈值
digest on|off [min] 将警报批量处理成摘要（默认 60 分钟）
quiet <from> <to> UTC 静音时间（例如 quiet 22 7）；静音关闭
premium 高级状态 + 如何升级
help 此消息
```
在群聊或服务器中，`watch`、`unwatch`、`threshold`、`digest` 和 `quiet` 仅限于管理员；`list`、`premium` 和 `help` 对所有人开放。
## 免费 vs 高级
| | 免费 | 高级 |
| --- | --- | --- |
| 订阅 | 3 | 无限制 |
| 交付 | 每 60 秒最多一个即时警报；额外内容折叠成摘要 | 实时，仅受您设置的静默时间/摘要模式限制 |
| `premiums`（股票代币套利信号） | 不可用 | 包含 |
| `rugs`（流动性拉动警告） | 不可用 | 包含 |
| 价格 | 免费 | `HOOD_ALERTS_PREMIUM_PRICE_USDG`（默认 5）USDG for `HOOD_ALERTS_PREMIUM_DAYS`（默认 30）天 |
高级服务通过 **x402** 在 Robinhood Chain 上使用 [`hood402`](../hood402)（USDG，EIP-3009 `transferWithAuthorization`，链 4663）支付。机器人的 `premium` 命令返回一个 `POST /premium/activate?platform=...&chat=...` URL：第一个请求获得一个 402 挑战，附带付款说明，任何 x402 客户端（`hood402`，`x402-fetch`）都可以签署 USDG 授权，完成购买。权益永不激活，直到结算在链上完成，因此签名本身购买权益。
购买在实例设置 `HOOD402_PAY_TO` 和 `HOOD402_FACILITATOR_URL`（委托验证和结算，无此盒上的 gas 密钥）或 `HOOD402_SETTLER_KEY`（此实例广播结算本身）之前保持禁用。参见 `.env.example` 获取两种模式。
## HTTP API
运行机器人的同一个进程在 `PORT`（默认 8080）上提供一个小型 Hono 应用程序：
| 端点 | 方法 | 返回 |
| --- | --- | --- |
| `/` | GET | 服务元数据和端点列表 |
| `/healthz` | GET | 正常运行时间，最后一次检测器事件时间，每个事件类型的计数，高级购买是否启用 |
| `/premium/status?platform=telegram\|discord\|console\|x&chat=<id>` | GET | `{ tier: 'free' \| 'premium', expiresAt }` 对于该聊天 |
| `/premium/activate?platform=...&chat=...` | POST | x402 购买流程：402 挑战，然后 200 + 权益一旦支付结算 |
## 示例：直接读取警报引擎的纯逻辑
`src/engine/gate.ts` 和 `src/engine/topics.ts` 没有 I/O，可以安全地导入独立使用，例如在连接订阅之前预览阈值将如何控制：
```ts
import { gate } from './src/engine/gate.js'
import { resolveWatchTarget, parseTopic } from './src/engine/topics.js'
const target = resolveWatchTarget('whales') // { ok: true, topic: 'whales' }
if (target.ok) {
const topic = parseTopic(target.topic) // { kind: 'whales' }
const decision = gate(
{ premium: false, digest: false, quietStart: null, quietEnd: null, lastDeliveredAt: null, deliveredLastMinute: 0 },
Math.floor(Date.now() / 1000),
)
console.log(topic, decision) // { kind: 'whales' } { action: 'deliver' }
}
```
在目标后输入的阈值（`watch whales 10000`）由 `Commands.watch()` 解析，而不是由 `resolveWatchTarget` 本身解析。
该包今天不提供公共库入口点（`main`/`bin` 均指向 `src/index.ts` 中的 CLI 进程，该进程启动机器人和 HTTP 服务器，不导出任何内容）；从 `src/` 导入如上所示在本次检查中有效，但不是已发布的 API 合同。
## 配置
每个变量、其默认值以及它控制的内容：[`.env.example`](.env.example)。亮点：
- `HOOD_ALERTS_RPC_URL` — 自定义 RPC；默认为 viem 的公共 `robinhood` 链 RPC。
- `HOOD_ALERTS_DB` — SQLite 路径（订阅、权益、去重、交付日志）。`:memory:` 可用于测试。
- `HOOD_ALERTS_WHALE_FLOOR_USD` / `HOOD_ALERTS_WHALE_DEFAULT_USD` — 引擎侧发射地板与默认每订阅阈值。
- `HOOD_ALERTS_PRICE_WINDOW_S` / `HOOD_ALERTS_PRICE_DEFAULT_PCT` — Chainlink 滚动窗口移动检测器。
- `HOOD_ALERTS_PREMIUM_POLL_S` / `HOOD_ALERTS_PREMIUM_DEFAULT_PCT` — 股票代币套利轮询节奏和默认阶梯条目。
- `HOOD_ALERTS_RUG_DEFAULT_PCT` — 默认流动性拉动阈值（报价储备的百分比）。
## 开发
```sh
npm install
npm run typecheck # tsc --noEmit, strict + exactOptionalPropertyTypes
npm test # vitest：去重/速率限制门控，摘要批处理，主题解析和匹配，事件指纹/ TTL，警报卡片渲染，配置加载，命令路由器和订阅者/权益/交付存储库 — 所有离线，无需链或机器人凭证
npm run build # tsc -> dist/
```
`whale-classify` 和 `detectors` 套件针对 **真实捕获的主网事件流** 在 `tests/fixtures/`（真实 Uniswap v3 交换，Odyssey 债券曲线交易和 Chainlink 价格）。使用 `npm run capture-fixtures` 刷新它们，它会重新读取实时链 4663。
`npm run test:live` 和 `npm run probe` 在真实的 Robinhood Chain RPC 和控制台传输上运行实时检测器；它们需要真实的网络访问，不是上述离线单元套件的一部分。`npm run grant-premium` 直接在数据库中补偿或检查高级权益（在连接支付轨道之前很方便）。
### 本地兄弟包
`hood402`、`hoodkit` 和 `hoodchain` 作为 `file:` 依赖项被此工作区中的其他 Robinhood Chain 存储库（`../hood402`、`../hoodkit`、`../robinhood-chain-sdk`）使用，而不是其发布的 npm 版本，因此对其中任何一个的更改都将在下一次 `npm install` 时被拾取。`file:` 链接保留每个兄弟自己的 `viem` 副本，因此补丁级偏差（例如此处为 `2.55.2`，而 `hood402` 为 `2.55.1`）使 viem 的结构化 `Chain` / `WalletClient` 类型在两个副本中出现分歧。`src/premium/paywall.ts` 显式桥接该边界（将本地 viem 客户端强制转换为 `hood402` 的 `HoodBroadcaster` / `HoodConfirmer`），因此在补丁偏差下，构建仍然是绿色的；运行时对象是相同的正确的 viem 客户端。一旦兄弟节点位于 npm 上并且解析了一个单一的 `viem`，强制转换就是一个无操作。
## 部署
hood-alerts 是一个长期运行的进程（引擎 + HTTP 服务器 + 两个机器人），因此将其作为具有温暖实例的服务运行，而不是作业。`hoodchain`/`hoodkit`/`hood402` 是普通的已发布 npm 依赖项（参见 `package.json`）- Docker 构建不需要特殊的上下文，只需此目录：
```sh
docker build -t hood-alerts .
docker run -p 8080:8080 -v hood-alerts-data:/data hood-alerts
gcloud run deploy hood-alerts \
--source . \
--region us-central1 \
--min-instances=1 --no-cpu-throttling --port=8080 \
--set-env-vars=HOOD_ALERTS_TELEGRAM_TOKEN=…,HOOD_ALERTS_DISCORD_TOKEN=…,HOOD_ALERTS_DISCORD_APP_ID=…
```
上面的 **在 Google Cloud 上运行** 按钮为您完成了此操作。将数据存储在 `/data`（默认 `HOOD_ALERTS_DB` 路径）上，以便在重启后生存。容器回答 `GET /healthz`（确认：真正的链上池发现完成，服务器在启动后约 10 秒内开始提供服务）；`SIGTERM` 在退出前刷新待处理摘要。
## 文档站点（GitHub Pages、Cloudflare 或 Vercel）
`docs/` 是一个静态的、手动构建的站点（无框架，无构建步骤）：在本地打开 `docs/index.html`，或从任何静态主机提供服务。其着陆页直接从公共 RPC 客户端渲染一个 **实时** 溢价/折扣提要（实时 Chainlink 提要与实时 DEX 池，没有服务器）。
- **GitHub Pages**（默认，规范首页）：`Settings → Pages → Deploy from a branch → main → /docs` → <https://nirholas.github.io/robinhood-chain-alert-bot/>。
- **Cloudflare** / **Vercel**：点击上面的按钮 — `wrangler.json`/`vercel.json` 在存储库根目录中都指向 `docs/`，不需要构建命令。
## 架构说明
- **控制台传输不是备用方案，而是烟雾测试模式。** 在未配置机器人令牌的情况下，引擎仍然会摄取真实的链上事件，并将每个警报/摘要记录为结构化的 JSON；这是新的自托管证明管道在触摸 Telegram 或 Discord 之前的工作方式。
- **权益在结算前永远不会激活。** `PremiumPaywall.activate()` 调用 `hood402` 的验证-然后-结算流程，只有在链上转账成功后才写入权益行。
- **摘要缓冲按设计在内存中。** 重启最多会丢失一个待处理批次，永不丢失订阅（订阅和交付日志在 SQLite 中）；`AlertEngine.stop()` 在关闭之前刷新每个缓冲的摘要。
- **自动跟踪的池过期；已监视的池不会。** NOXA/Odyssey 启动或毕业开始在池上自动进行 24 小时的拉毯监视；用户 `watch 0x…` 保持该池的流动性监视器无限期运行。
## 存储库布局
```
src/index.ts CLI 入口：连接配置、数据库、引擎、检测器、传输、HTTP 服务器
src/config.ts 环境 -> 验证配置
src/server.ts Hono 应用程序：/，/healthz，/premium/status，/premium/activate
src/engine/ 事件类型、重复指纹、主题解析/匹配、摘要缓冲区、交付门控和实时检测器集
src/engine/detectors/ 纯信号检测器（价格变动、溢价阶梯、持有者里程碑、流动性拉动、鲸鱼分类）+ live.ts，将它们连接到 hoodchain/hoodkit 流
src/db/ better-sqlite3 存储库：订阅者、权益、交付
src/premium/paywall.ts hood402 x402 购买流程
src/transports/ Telegram（grammY）、Discord（discord.js）、X（OAuth1 API v2 或自托管 xactions）和控制台传输
src/commands/commands.ts 共享的平台中立命令路由器
src/format/cards.ts 警报 -> 平台中立卡片 -> 平台特定渲染
tests/ vitest 单元套件 + tests/fixtures（真实捕获的链上事件）+ tests/live（选择加入链上读取）
scripts/ capture-fixtures, live-probe, grant-premium（参见上面的开发）
docs/ 静态 GitHub Pages 站点，带有实时客户端溢价提要
Dockerfile 单容器构建（引擎 + 两个机器人），从 robinhood/ 构建
```
## 注意
- **股票代币。** 股票代币是有代币化的债务证券（发行人：Robinhood Assets (Jersey) Ltd），可能不会被提供、出售或交付给美国人（额外的限制：加拿大、英国、瑞士）。 hood-alerts 只显示从公共 Chainlink 喂价和 DEX 池派生的价格/溢价数据；它从不促进获取股票代币。
- 流动性拉动警报是早期警告，而不是欺诈的证据：始终在采取行动之前检查池。
- 不隶属于 Robinhood Markets, Inc.
## 许可证
MIT。参见 [LICENSE](./LICENSE).
由 [nirholas](https://x.com/nichxbt) · [three.ws](https://three.ws) 构建
连接信息
猜你喜欢
暂无推荐服务器