elfa-ai

Name: elfa-ai
Author: elfa-ai

github.com/elfa-ai其他1179 次安装1 周前更新

代码仓库

关于 elfa-ai

Elfa API Skill 帮助 Agent 调用 Elfa 的加密货币与股票市场数据及自动条件引擎 API。它涵盖社交情绪、市场事件、持仓和注意力排名，也支持构建持续监控并触发动作的条件查询。

主要功能

01查询热门代币、提及和叙事
02获取 AI 市场摘要与事件信息
03查看市场立场和注意力排名
04构建并管理自动条件查询
05通过 API key 或 x402 鉴权

适用场景

01追踪代币或关键词的社交提及
02分析加密货币与股票市场事件
03监控交易者开仓或注意力变化
04按价格或叙事条件触发告警

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/elfa-ai/skills --skill elfa-ai

安装后在 Claude Code 中输入/elfa-ai确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

swagger.json

scripts/

build-skill.sh

elfa_call.sh

详细介绍

原文在翻译后有更新，译文可能不是最新。

Elfa API 技能

此技能可帮助 Agent 使用 Elfa API——这是一个面向加密货币的社交舆情监测、市场背景信息层和自动化条件引擎。Elfa 从 Twitter/X、Telegram 和其他来源摄取实时数据，然后将情绪、叙事和关注度变化整理为可操作的交易洞察。Market Intelligence 端点涵盖测量（数量、互动、账号）和解读（聊天、摘要、叙事）。 API v3 将加密货币和股票领域的新闻与市场讨论转化为事件、仓位和排名。 Auto 子系统增加了托管式条件引擎和触发管线——描述需要关注的内容，Auto 会持续评估，并在条件满足时执行操作。

完整文档：docs.elfa.ai

保持更新——每周检查。 此技能按每周节奏更新，以跟进 Elfa API 和 Auto 的变化。依赖此技能前，请检查你手中的版本是否可能过时：如果上次获取或安装此技能已超过 7 天（或你不确定），请在采取行动前重新获取最新版本 —

技能包和更新日志： https://go.elfa.ai/claude-skills（以及 elfa-ai/skills 仓库）。

实时权威来源： docs.elfa.ai——如果此技能与文档不一致，以文档为准；请优先参考文档，并向用户指出不一致之处。

如果不确定某个具体端点、参数或价格，请在调用时核对 docs.elfa.ai，不要轻信可能过时的副本。

环境和凭据

Elfa 支持 API 密钥认证和 x402 无密钥支付。使用 x402 时无需 API 密钥。

变量	必填	用途
`ELFA_API_KEY`	否	使用 API 密钥进行身份验证的请求。在 https://go.elfa.ai/claude-skills 开通按量付费余额。
`ELFA_AGENT_SECRET`	否	用于 x402 Auto 的持久 Agent 身份密钥。使用 `openssl rand -hex 32` 生成一次，并在查询生命周期调用中重复使用。

请勿将此密钥用作 Webhook 签名密钥。 webhook.params.signingSecret 是 单独的每个 Webhook 专用密钥，用于验证 Elfa 发往你服务器的投递。参见 Webhook 签名验证。

x402 钱包签名由客户端通过 @x402/fetch 或 @x402/axios 处理。

何时使用此技能

用户询问加密货币领域的热门代币、叙事或合约地址
用户想查询特定股票代码或关键词的社交媒体提及
用户想查询 Twitter/X 账号的智能数据（智能关注者、互动）
用户想要AI 生成的市场摘要、宏观概览或代币分析——包括流式聊天输出
用户想了解加密货币或股票市场发生了什么以及价格如何反应、某项资产的多头或空头是谁、哪些人的判断值得信任，或哪些资产最受关注（API v3）
用户询问如何集成、调用或使用 Elfa API
用户想要 Elfa 端点的代码示例（curl、Python、JavaScript/TypeScript）
用户在加密货币或交易数据语境中提到“elfa”
用户想要设置自动提醒或监控，以跟踪价格、指标或叙事
用户想要构建基于条件的触发器（例如：“BTC 突破 100k 时提醒我”）
用户想要监控 X 关注关系图——谁关注了受监控账号、该账号开始关注了谁，或多个受监控账号是否都开始关注同一个账号
用户在加密货币语境中提到 Auto、EQL、条件引擎或触发管线
用户想要能够自动响应市场状况的 Agent 工作流
用户想使用自然语言通过 Builder Chat 构建查询

API Overview

Base URL: https://api.elfa.ai Version: v2, plus API v3 (/v3/) Docs: docs.elfa.ai

Two access modes

Elfa supports two independent ways to authenticate requests:

Mode	Endpoint prefix	Auth header	Best for
API key	`/v2/`, `/v3/`	`x-elfa-api-key: YOUR_KEY`	Humans & apps with a registered key
x402 (keyless)	`/x402/v2/`	`PAYMENT-SIGNATURE: <signed-payload>`	Agents & wallets — no signup needed

Both modes access the same v2 data. Otherwise the only difference is how you authenticate:

API key — register at https://go.elfa.ai/claude-skills. Start on pay-as-you-go: the free tier is being phased out, so new integrations should top up a PAYG balance rather than build against free credits.
x402 — pay per request with USDC on Base, Arbitrum, Polygon, Avalanche, or Solana. No registration, no API key. Currently in beta.

Endpoints at a glance

Data endpoints

All endpoints below work with both /v2/ (API key) and /x402/v2/ (keyless) prefixes, except key-status which is API key mode only.

Endpoint	Method	Description	Credits
`/v2/ping`	GET	Health check — no auth required (API key mode only)	Free
`/v2/key-status`	GET	API key usage & limits (API key only)	Free
`/v2/aggregations/trending-tokens`	GET	Trending tokens by mention count	1
`/v2/account/smart-stats`	GET	Smart follower & engagement stats — legacy, will be removed 28 Oct 2026	1
`/v2/data/top-mentions`	GET	Top mentions for a ticker symbol	1
`/v2/data/keyword-mentions`	GET	Search mentions by keywords or account	1
`/v2/data/event-summary`	GET	AI event summaries from keyword mentions	5
`/v2/data/trending-narratives`	GET	Trending narrative clusters (Grow+ / PAYG)	5
`/v2/data/token-news`	GET	Token-related news mentions (tweet source only)	1
`/v2/aggregations/trending-cas/twitter`	GET	Trending contract addresses (Twitter)	1
`/v2/aggregations/trending-cas/telegram`	GET	Trending contract addresses (Telegram)	1
`/v2/chat`	POST	AI chat, complete JSON response (Grow+ / PAYG)	Speed-based
`/v2/chat/stream`	POST	AI chat, incremental SSE stream (PAYG / Enterprise)	Speed-based

/v2/ping, /v2/key-status, and /v2/chat/stream are API-key mode only — they have no /x402/v2/ counterpart.

API v3 端点

API v3 可将加密货币和股票领域的新闻与市场热议转化为事件、持仓和排名。所有端点均使用 GET，并通过 x-elfa-api-key 进行身份验证（不使用 x402）。在 Pay-as-you-go 和 Grow 套餐中，v3 API 可免费使用至 2026 年 10 月 31 日，Enterprise 密钥也可以调用；Free 密钥只能调用 /v3/key-status。共享规则请参阅第 2d 步。

问题	端点	返回内容
这是哪个 id？	`/v3/entities`	其他所有端点都会使用的 id，可根据股票代码、名称、账号名、地址、CoinGecko id、FIGI 或 CIK 获取
发生了什么？	`/v3/events`	事件：发生了什么、涉及什么对象，以及价格如何反应。可按主题搜索
	`/v3/events/storylines`	持续数日跟踪的一项进展
	`/v3/events/arcs`	归为更大动向的一组故事线
注意力集中在哪里？	`/v3/market/crypto/mindshare`、`/v3/market/equity/mindshare`	按关注度占比排名的资产，包含 `hot`
	`/v3/market/crypto/trending-contracts`	按帖子中被粘贴次数排名的合约地址
市场群体倾向于哪个方向？	`/v3/market/crypto/call-book`、`/v3/market/equity/call-book`	按小时划分的整个市场看多／看空倾向
	`/v3/calls/positioning`	某项资产当前的未平仓多头和空头仓位
账号在做什么？	`/v3/calls`	每一篇建仓或调整仓位的帖子
	`/v3/calls/episodes`	每个仓位从开仓到平仓的情况，附带价格和作者的过往表现
哪些账号值得关注？	`/v3/people/accounts`	按影响力排名的账号，或通过 `metric` 按过往表现排名
我的密钥可以做什么？	`/v3/key-status`	套餐、额度、限制以及可查询的历史范围

Auto 端点（Condition Engine）

Auto 端点可通过 /v2/auto/（API 密钥）和 /x402/v2/auto/（无需密钥）使用。完整详情请参阅 Auto 文档。

身份验证列说明（下表）。 API key = 仅使用 x-elfa-api-key。

API 密钥模式（/v2/auto/*）：

查询生命周期：

端点	方法	描述	身份验证
`/v2/auto/chat`	POST	Builder Chat — AI 辅助构建查询（仅生成草稿）	API key
`/v2/auto/queries/validate`	POST	验证 EQL 并预览费用	API key
`/v2/auto/queries`	POST	创建并启用查询	API key
`/v2/auto/queries`	GET	列出查询	API key
`/v2/auto/queries/:queryId`	GET	轮询查询状态和执行情况（解析查询或草稿）	API key
`/v2/auto/queries/:queryId/cancel`	POST	取消 `active` 查询（若状态已终止，则返回 `409`）	API key
`/v2/auto/queries/:queryId`	DELETE	删除已终止的查询 — 仅当状态为 `triggered` / `expired` / `cancelled` / `failed` 时可用（否则返回 `409`；必须先取消活动查询）	API key
`/v2/auto/queries/stream`	GET	在一个连接上串流推送所有查询的通知（仅限 API 密钥 — 不支持 agent/x402）	API key
`/v2/auto/queries/:queryId/stream`	GET	通过 SSE 串流推送单个查询的通知	API key

查询草稿（可编辑，尚未启用）：

端点	方法	描述	身份验证
`/v2/auto/queries/drafts`	POST	创建或更新（upsert）查询草稿	API key
`/v2/auto/queries/drafts`	GET	列出可编辑的查询草稿	API key
`/v2/auto/queries/drafts/:draftId`	GET	获取指定草稿（旧版 — 建议使用 `GET /queries/{queryId}`）	API key
`/v2/auto/queries/drafts/:draftId`	DELETE	删除查询草稿	API key
`/v2/auto/queries/drafts/:draftId/validate`	POST	验证已保存的草稿	API key
`/v2/auto/queries/drafts/:draftId/convert`	POST	将草稿转换为已启用的查询	API key

大模型会话（用于 action.type: "llm" 查询）：

端点	方法	描述	认证
`/v2/auto/queries/:queryId/sessions`	GET	列出大模型会话	API key
`/v2/auto/queries/:queryId/sessions/:sessionId`	GET	获取完整的大模型会话详情	API key

执行记录（触发器触发记录）：

端点	方法	描述	认证
`/v2/auto/executions`	GET	列出执行记录	API key
`/v2/auto/executions/:executionId`	GET	获取单条执行记录	API key

其他：

端点	方法	描述	认证
`/v2/auto/validate-symbol/:exchange/:symbol`	GET	检查某个交易场所是否支持某个交易品种 — 对 `price` / `ta` 数据源进行预检查	API key

x402 模式（/x402/v2/auto/*） — 注意：部分路由使用 POST 而非 GET：

端点	方法	描述
`/x402/v2/auto/chat`	POST	构建器聊天
`/x402/v2/auto/queries/validate`	POST	验证 EQL 并预览费用
`/x402/v2/auto/queries`	POST	创建并激活查询
`/x402/v2/auto/queries/:queryId`	POST	轮询查询状态（POST，而非 GET）
`/x402/v2/auto/queries/:queryId/cancel`	POST	取消 `active` 查询
`/x402/v2/auto/queries/:queryId/stream`	GET	通过 SSE 流式传输通知
`/x402/v2/auto/queries/:queryId/sessions`	POST	列出大模型会话（POST，而非 GET）
`/x402/v2/auto/queries/:queryId/sessions/:sessionId`	POST	获取大模型会话详情（POST，而非 GET）

关于 x402 Auto 范围的说明。 草稿、执行记录和用于终止查询的 DELETE 端点仅支持 API key 模式。x402 Auto 覆盖核心监控生命周期（聊天、验证、创建、轮询、取消、流式传输、会话）。账户级流式端点 GET /v2/auto/queries/stream 不对 x402 开放 — x402（以及 Agent 身份）只能使用单个查询的流式端点。

Auto 不再接受订单操作。 新查询和草稿不能在顶层或 llm 回调中使用 market_order 或 limit_order — Auto 会以 EQL_INVALID_ACTION 拒绝这些操作。现有已存储的交易查询仍可读取、取消和删除。请通过 webhook、notify 或 telegram_bot 操作，将后续执行交由你自己的运行器处理。

有关完整的参数详情，请参阅 Elfa API 文档。

机器可读来源（优先于抓取文档页面）

需要准确的端点元数据时，请加载以下来源，而不是逐页浏览文档：

来源	URL	用途
端点清单	`https://docs.elfa.ai/agent/endpoints.manifest.json`	方法/路径、文档路由、必需的标头、付费要求、请求/响应示例
文档映射	`https://docs.elfa.ai/llms.txt`	规范页面映射 + 机器可读链接。对于不请求 HTML 的客户端，普通的 `GET https://docs.elfa.ai/` 会返回相同的索引，格式为 `text/plain`
完整文档文本	`https://docs.elfa.ai/llms-full.txt`	仅在需要更深入的页面上下文时使用
OpenAPI 规范	随附于 `references/swagger.json`	准确的架构、参数和默认值。忽略 `/v3` 上逐操作列出的费用；费用说明请参阅 API v3 端点
最新技能	`https://raw.githubusercontent.com/elfa-ai/skills/main/skills/elfa-ai/SKILL.md`	无法安装时，重新获取此技能

清单 URL 是稳定的——早期版本使用了会轮换的 assets/files/endpoints.manifest-*.json 路径；请使用上方的 /agent/ 路径。

使用 npx skills add elfa-ai/skills 安装或更新技能。

如果你在无法执行命令的客户端（例如 Claude Desktop）中使用，可以通过 MCP 服务将 API 作为工具提供：连接托管服务 https://mcp.elfa.ai/mcp 并使用 Elfa 登录，或使用 API 密钥运行 npx -y @elfa-ai/mcp。请参阅 docs.elfa.ai/tools/mcp。如果可以运行命令，请优先使用此技能——在使用之前，它不会占用上下文。

如果你使用 TypeScript 或 Python 编写代码，而不是手动调用 API，官方 SDK（@elfa-ai/sdk、elfa-sdk）会封装相同的接口，并提供类型化响应、重试和 SSE 流式传输。请参阅 docs.elfa.ai/tools/sdks。

如何使用此技能

第 1 步：确定模式

确认用户想要进行实时调用、获取代码/集成帮助，还是设置自动监控。

如果用户提出“显示热门代币”“SOL 的市场情绪如何”“获取 ETH 的热门提及”等请求 → 用户需要实时数据。继续执行第 2a 步。如果不清楚该使用哪个端点，或请求需要多次调用，请参阅第 2c 步。
如果用户询问某项资产发生了什么、某个故事如何发展、谁在做多或做空、哪些人的判断值得信任，或哪些股票正受到关注 → 使用 API v3。请参阅第 2d 步。
如果用户提出“如何调用热门代币端点”“给我一个 curl 示例”“帮我集成 Elfa”等请求 → 用户需要代码片段。跳到第 4 步。
如果用户提到 x402、keyless、按请求付费或基于钱包的访问 → 用户需要 x402 模式。实时调用请参阅第 2b 步，代码片段请参阅第 4 步。
如果用户提到 Auto、警报、触发器、监控、条件、“在……时提醒我”、“如果……就通知我”、EQL 或 Builder Chat → 用户需要 Auto。继续执行第 3 步。

第 2a 步：进行实时 API 调用（API 密钥模式）

使用 bash_tool 通过 curl 调用 Elfa API。

获取 API 密钥：

检查是否已设置 ELFA_API_KEY 环境变量。这是首选方式。
如果未设置环境变量，请停止并提示用户。 提供以下两种选项：

如需进行实时调用，有两种方式：

选项 A — 按量付费的 API 密钥（推荐）： 在 https://go.elfa.ai/claude-skills 注册并充值 PAYG 余额 — 每个 credit $0.0145，最低充值 $20，支持银行卡或 USDC。然后将密钥设为 ELFA_API_KEY 环境变量（不要直接粘贴到聊天中）。免费套餐正在逐步取消，因此请从 PAYG 开始，而不是使用免费额度。

选项 B — x402 无密钥支付： 使用 USDC 在 Base、Arbitrum、 Polygon、Avalanche 或 Solana 上按请求付费 — 无需注册。请参阅 x402 文档了解设置方法。

未设置密钥或 x402 前，请勿尝试进行任何需要身份验证的 API 调用。请等待用户操作。
凭据安全：
- 始终从 ELFA_API_KEY 环境变量读取 API 密钥，绝不要要求用户将密钥粘贴到对话中。
- 切勿在输出中记录或泄露完整 API 密钥 — 显示 curl 命令时应对密钥进行掩码处理。
- 绝不要回显或打印环境变量： 不要运行 echo $ELFA_API_KEY、env | grep ELFA、 printenv 或其他会在记录中泄露凭据的类似命令。
- 如果用户确实在聊天中粘贴了密钥，请提醒他们轮换密钥，并改为将其设为环境变量。

套餐、额度和速率限制：

优先按量付费：PAYG 使用 API 密钥时每个 credit $0.0145，速率为 60 RPM，费用从预付 credit 余额中扣除（最低充值 $20，支持银行卡或 USDC）；x402 每个 credit $0.0145，速率为 1,000 RPM，无需账户。每个 credit 价格相同 — 根据集成方式选择。免费套餐正在逐步取消，因此任何新集成都建议使用 PAYG（或 x402）。

已使用 PAYG 的账户在 2026 年 9 月 28 日 16:00 UTC （9 月 29 日 00:00 SGT）前仍可享受每个 credit $0.009 的价格。x402 没有账户，因此该价格会同时适用于每位付款者。

订阅套餐：

	免费（逐步取消）	Grow	Enterprise
月付	$0	$870	定制
年付（优惠 15%）	$0	$8,874（$739.50/月）	定制
每月 credits	1,000	120,000	定制
超额用量	—	$0.00725 / credit	定制
速率限制	60 RPM	120 RPM	定制
Agent Chat	—	✓	✓
Agent Automation	—	✓（最多 100 个活跃计划）	✓

在 2026 年 10 月前开通的 Grow 订阅保留原有价格（$290/月，或按年计费 $2,958/年）、每月 40,000 个 credits，以及每个超额 credit $0.009 的价格。

各级套餐解锁的功能：

免费（逐步取消）— 核心社交数据：热门代币、智能统计、热门提及、关键词提及、事件摘要、代币新闻、热门合约地址（Twitter + Telegram）
Grow — 包含免费套餐的所有功能，另有代币关注度份额、按情绪加权的提及、 热门叙事和 Elfa Intelligence（Agent Chat 和 Agent Automation）
Enterprise — 包含 Grow 的所有功能，另有自定义 credit 和速率限制、流式 AI Chat （Ask Elfa、POST /v2/chat/stream）、专属支持、自定义集成和优先支持

受套餐限制的端点汇总：

端点	要求
`/v2/data/trending-narratives`	Grow+ 或 PAYG
`/v2/chat`	Grow+ 或 PAYG
`/v2/chat/stream`	仅限 PAYG 或 Enterprise
`/v3/*`，`/v3/key-status` 除外	PAYG、Grow 或 Enterprise

Grow 套餐的每月 credits 用尽后，请求仍可继续处理并按超额用量计费，除非在控制面板中关闭超额用量或设置支出上限；免费套餐则会拒绝请求，直到下个月额度重置。超过速率限制会返回 429（请遵循 Retry-After）。如果用户在受限端点遇到授权错误，可以改用 PAYG、升级套餐，或改用 x402（仅限 v2）。完整详情请见 https://go.elfa.ai/claude-skills。

发起调用：

curl -s -H "x-elfa-api-key: $ELFA_API_KEY" "https://api.elfa.ai/v2/aggregations/trending-tokens?timeWindow=24h&pageSize=10"

第 2b 步：进行实时 API 调用（x402 无密钥模式）

x402 让任何钱包都能通过 Base、Arbitrum、Polygon、Avalanche 或 Solana 使用 USDC 按请求付费，无需 API 密钥，也无需注册。这非常适合 Agent、机器人和程序化访问。

x402 的工作原理：

向任意端点的 /x402/v2/ 版本发送请求（不带认证标头）。
服务端返回包含付款要求的 HTTP 402 响应。
钱包对 USDC 转账授权进行签名（无需支付 Gas 费）。
在 PAYMENT-SIGNATURE 标头中附上已签名的付款信息，重新发送请求。
服务端验证付款、返回响应，并在链上完成结算。

x402 签名与安全性：

签名完全在客户端进行，使用 @x402/fetch 或 @x402/axios 库。Agent 不会处理、存储或传输私钥。
用户的钱包私钥仅由 x402 库在本地使用，用于对 EIP-712 类型化数据签名，授权针对特定请求支付特定数量的 USDC。
切勿在对话中要求用户分享钱包私钥或助记词。
生成 x402 代码示例时，请使用 "0xYOUR_PRIVATE_KEY" 作为占位符，并建议用户从环境变量（例如 process.env.PRIVATE_KEY）加载私钥。

x402 详情：

网络： 服务端会在 402 响应中提供所有受支持的网络；客户端会在其已注册的网络中选择第一个进行签名。请注册你持有 USDC 的网络。
方案： exact（每个请求固定价格）；聊天端点在 Base 上还支持 batch-settlement（预付通道，按用量计费）；资产为原生 Circle USDC（6 位小数）。 batch-settlement 无需代币授权：存款通过已签名的 USDC 授权完成。该方案仅在 Base 上提供；包括 Solana 在内的其他所有网络都仅支持 exact。
错误： 请先根据 HTTP 状态码进行分支判断，再将响应正文作为细化信息读取。大多数拒绝请求的响应格式为 { code, message, errorId, requestId }，但 x402 接口也可能返回不含 code 的简短格式 { error }。即使是简短格式，requestId 也会出现在 x-request-id 响应标头中。对于 Auto 端点，EQL 校验失败会返回 { valid, errors, warnings }（create 返回状态码 422，validate 返回状态码 200，此时必须读取 valid）；执行引擎引发的错误则会原样传递。402 是付款握手，不是计费错误。请参阅错误响应。
状态： 目前处于 Beta 阶段。

网络	链 ID	USDC 地址	支付协调器
Base	`eip155:8453`	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`	payai.network
Arbitrum	`eip155:42161`	`0xaf88d065e77c8cC2239327C5EDb3A432268e5831`	payai.network
Polygon	`eip155:137`	`0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359`	payai.network
Avalanche	`eip155:43114`	`0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E`	payai.network
Solana	`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`	`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`	payai.network

EVM 签名无需支付 Gas 费。在 Solana 上，支付协调器会支付交易手续费。

x402 定价（数据端点）：

套餐	积分	USDC 费用	端点
标准	1	$0.0145	trending-tokens、smart-stats、keyword-mentions、token-news、top-mentions、trending-cas
扩展	5	$0.0725	event-summary、trending-narratives

数据端点仅支持 exact。/x402/v2/chat 按速度计费，并提供两种方案——使用 exact 按固定价格付费，或从预付的 batch-settlement 通道扣费，按本轮实际用量计费，最高不超过限额：

速度	`exact`（固定价格）	`batch-settlement`（最高扣费）
`fast`	$1	$2
`expert`（默认）	$2	$6
`batch-settlement`：首次调用会向通道存入 USDC（至少 $6，即在 `expert` 上限下可进行一轮调用）；后续调用使用已签名的凭证付款，无需新的链上交易。此方式仅适用于 Base，且只有在 402 列出该方式时才能使用。通道闲置 3 天后，未使用的存款会退回钱包；也可以在链上提取（请求提交后 1 小时完成）。

使用 curl 发起 x402 调用（手动流程）：

# Step 1: Send request without payment — get 402 with payment requirements
curl -s https://api.elfa.ai/x402/v2/aggregations/trending-tokens?timeWindow=24h

# Step 2: After signing the payment payload with your wallet, resend with payment header
curl -s -H "PAYMENT-SIGNATURE: <base64-encoded-payment-payload>" \
  "https://api.elfa.ai/x402/v2/aggregations/trending-tokens?timeWindow=24h"

推荐：使用 @x402/fetch 库，它会自动处理付款：

import { wrapFetchWithPayment } from "@x402/fetch";
import { ExactEvmScheme, toClientEvmSigner } from "@x402/evm";
import { x402Client } from "@x402/core/client";
import { createPublicClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount("0xYOUR_PRIVATE_KEY");
const publicClient = createPublicClient({ chain: base, transport: http() });
const signer = toClientEvmSigner(account, publicClient);

const client = new x402Client().register(
  "eip155:8453",
  new ExactEvmScheme(signer));

const x402Fetch = wrapFetchWithPayment(fetch, client);

// Use x402Fetch exactly like regular fetch — payment is handled automatically on 402 responses
const response = await x402Fetch(
  "https://api.elfa.ai/x402/v2/aggregations/trending-tokens?timeWindow=24h");
const data = await response.json();

若要在其他网络上付款，请替换 base 链的导入，并注册相应的方案——例如 Arbitrum（从 viem/chains 导入 arbitrum，eip155:42161）。为你要付款的每个网络注册一个方案；客户端会使用服务端也接受的第一个方案。

使用 Chat 端点进行 x402 调用（POST）：

const response = await x402Fetch(
  "https://api.elfa.ai/x402/v2/chat",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      message: "What is the current sentiment on BTC?",
      analysisType: "chat",
      speed: "fast", // exact: "fast" $1, "expert" $2 — batch-settlement: up to $2 / $6
    }),
  });
const data = await response.json();
console.log(data.data.message);

呈现结果：

解析 JSON 响应，并以清晰易读的格式呈现。
对于热门代币：显示排名表格，包含代币名称、提及次数和变化百分比。
对于提及：显示推文链接、互动指标和账户信息。注意：Elfa 返回推文 ID，但不返回推文文本内容——请告知用户，他们需要自己的 X（Twitter）API 密钥才能获取实际推文内容。
对于叙事／摘要：呈现叙事文本及来源链接。
对于 chat 端点：清晰地显示 AI 响应。
如果响应包含错误，请解释问题所在并建议解决方法。

第 2c 步：市场情报——选择合适的端点

数据端点分为两个层级。选错层级是最常见的集成错误。

层级	端点	返回内容
测量	`smart-stats`（旧版）、`trending-cas/*`、`trending-tokens`、`top-mentions`、`keyword-mentions`、`token-news`	计数、互动指标、链接、账户元数据。由你的系统进行解读。
解读	`chat`、`chat/stream`、`event-summary`、`trending-narratives`	书面分析或摘要；如有来源链接，也会一并提供。

**测量端点不返回原始推文文本，也不包含情绪字段。**它们衡量的是关注度，而非含义。如果用户需要帖子内容，必须使用自己的 X API bearer token 获取链接帖子。如果用户需要了解含义，请将请求转至 Chat、Event Summary 或 Trending Narratives，而不要试图从计数中推断。

选择合适的接口：

用户需求	从这里开始
资产发生了什么，以及事件如何发展	`/v3/events`、`/v3/events/storylines`（第 2d 步）
谁在做多或做空，以及哪些人的判断值得信赖	`/v3/calls/positioning`、`/v3/calls/episodes`、`/v3/people/accounts?metric=alphaScore`（第 2d 步）
用通俗语言回答市场问题	`POST /v2/chat`
当前有哪些动态	`trending-tokens`、`trending-cas/*`，或 `/v3/market/crypto/mindshare` 和 `/v3/market/crypto/trending-contracts`（第 2d 步）
谁放大了某个代币或关键词的传播	`top-mentions`、`keyword-mentions`、`smart-stats`
某次变动背后有据可依的原因或主题	`token-news`、`event-summary`、`trending-narratives`
持续监控，并在满足条件时通知／执行	Auto（第 3 步）

Agent 操作手册（端点链）

单次调用用于回答问题；链式调用则能提取信号。以下是文档中介绍的组合：

用法	调用链	原理
领先时间	`trending-cas/telegram` → `trending-cas/twitter`	Telegram 通常领先；Twitter 用于确认。如果某个 CA 出现在第一个端点中、但尚未出现在第二个端点中，就说明信号出现得较早。
按可信度加权的提及	`keyword-mentions` → `smart-stats`	`keyword-mentions` 会返回 `account.username`；`smart-stats` 则能判断该账号是否拥有真实影响力。
走势 + 放大效应	`trending-tokens` → `top-mentions`	找出哪些代币出现了走势，再查看是谁推动了这一走势。
主题 → 交易标的	`trending-narratives` → `trending-tokens`	将某个主题转化为值得关注的具体代币代码。
走势 + 原因	`token-news` → `event-summary`	为价格或关注度变化附上文字说明，解释其原因。
问题 + 证据	`chat` → 定向数据端点	`chat` 给出结论；数据端点则提供用于验证结论的数字。

使用 smart-stats 对账号进行排名时，应使用比率（智能粉丝数 ÷ 粉丝数、平均触达数 ÷ 粉丝数），而非绝对数量——该端点返回的是原始指标，而非声誉评分。

smart-stats 已弃用，将于 2026 年 10 月 28 日移除。 在此之前仍可使用，且不会再扩展。以它为终点的调用链目前仍能正常工作，但新集成应基于 keyword-mentions 构建；该端点会在每条提及的互动指标旁返回 account.username。

聊天 — JSON 与流式传输

界面	端点	套餐	适用场景
API 密钥 JSON	`POST /v2/chat`	Grow+ 或 PAYG	客户端无法使用 SSE，或需要一份完整的 JSON 答案
API 密钥 SSE	`POST /v2/chat/stream`	PAYG 或 Enterprise	客户端可以使用 SSE，并需要增量输出
x402 JSON	`POST /x402/v2/chat`	按请求付费	基于钱包的 Agent，无需 API 密钥

两个界面使用相同的请求正文。analysisType 决定模式：

类型	用途	必填字段
`chat`	开放式提问	`message`
`macro`	整体市场状况	无
`summary`	快速了解概况	无
`tokenIntro`	介绍代币及其叙事	`assetMetadata.symbol` 或 `assetMetadata.chain` + `assetMetadata.contractAddress`
`tokenAnalysis`	入场、出场、市场与链上背景	与 `tokenIntro` 相同
`accountAnalysis`	评估某个账号的影响力和意图	`assetMetadata.username`

只有 analysisType: "chat" 时才必须提供 message——其他模式使用模式和 assetMetadata，并忽略自由格式的 message。省略 sessionId 可开始新会话；传回响应中的 sessionId 可继续会话。

**来源（可选）：**发送 includeSources: true，即可获取答案背后的研究所读取的链接—— /v2/chat 和 x402 聊天的结果位于 data.sources，流式传输的最终 complete 事件中则位于 sources。按读取顺序排列，不重复，最多 50 条；每条包含 url、kind （x_post、x_account、telegram、dex、explorer、prediction_market、web—— 其他任何值均按 web 处理）以及可选的 title。仅提供链接，不包含网页或帖文正文。来源表示已读取，不一定已引用。此标志不会产生额外费用。

速度：fast（较浅）、expert（默认）和 adaptive（由 Elfa 选择）—— adaptive 可用于 /v2/chat，但不可用于 /x402/v2/chat。

/v2/chat/stream 上的 SSE 事件类型（每个事件均以包含 type 的 data: 负载到达）：

事件	负载
`session_info`	`sessionId`、`analysisType`
`title`	`title` — 生成的会话／分析标题
`text`	`content` — 增量 Markdown 片段
`text_complete`	增量文本已完成
`status`	进度更新（例如“正在搜索提及……”）
`credits`	`credits` — 当前已消耗的额度
`complete`	最终的 `sessionId`、`success`、`creditsConsumed`；若 `includeSources: true`，还包括 `sources`
`invalid_request`	查询未通过安全检查，被拒绝
`error`	流式传输失败

长时间无数据时可能会收到 : keep-alive 注释。数据流以 data: [DONE] 结束。如果密钥不是 PAYG 或 Enterprise，则返回 403。

curl -sN -X POST "https://api.elfa.ai/v2/chat/stream" \
  -H "x-elfa-api-key: $ELFA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"analysisType":"chat","message":"Why is BTC moving today?","speed":"expert"}'

健康检查

GET /v2/ping 无需身份验证——在排查凭据问题前，可用它确认服务是否可访问。

curl -s https://api.elfa.ai/v2/ping

步骤 2d：API v3 — 事件、市场、观点与人物

当用户想了解发生了什么以及某个事件如何发展、谁看涨或看跌某项资产以及哪些人的观点值得信任、哪些资产最受关注，或哪些账号值得阅读时，请使用 API v3；支持加密货币和股票。端点列于 API v3 端点。完整文档：docs.elfa.ai/api/v3/overview。

API v3 需要具有 v3 访问权限的 ELFA_API_KEY（参见 API v3 端点），并遵循步骤 2a 中的密钥规则。没有密钥时，请提供一个选项，或改用 event-summary（任何密钥均可，或使用 x402）或通过 x402 使用 chat。要检查资格，请读取 /v3/key-status 中的 scopes，而非 plan： Free 密钥在此处显示 payg，且不包含 v3 权限范围。

**先解析。**实体筛选器需要的是 ID，而非股票代码。先解析资产，读取其最近一天的事件，然后查看各账号对该资产的持仓方向。请确认解析出的名称：第一个匹配项可能不是你要找的资产。from 为必填项，单位为秒。

ID=$(curl -s "https://api.elfa.ai/v3/entities?q=btc&entityType=token&limit=1" \
  -H "x-elfa-api-key: $ELFA_API_KEY" | jq -r '.entities[0].id')

FROM=$(( $(date +%s) - 86400 ))
curl -s "https://api.elfa.ai/v3/events?entityIds=$ID&from=$FROM&limit=10" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

curl -s "https://api.elfa.ai/v3/calls/positioning?entityId=$ID" \
  -H "x-elfa-api-key: $ELFA_API_KEY"

/v3/entities 执行精确匹配，不是搜索。前缀或拼写错误都不会返回结果。
股票代码并非唯一：取第一行并检查其 name，或使用 entityType 缩小范围（token、equity、project、person、organisation）。
已知的同一资产的不同形式会归入同一个家族 ID：WBTC 和 cbBTC 都归为 Bitcoin，代币化股票会解析为对应股票。并非所有形式都已归类，因此请检查 name。
人物不是账户。事件按人物的实体 ID 过滤；调用和剧集则使用 X handle。

每个 v3 端点都遵循的规则：

规则	简述
时间	请求和响应中均使用 Unix 秒和 UTC。毫秒会导致 `400`：请除以 1000
时间范围	`from` 必填，`to` 默认为当前时间，二者均包含在内。按 ID 获取或使用 `q` 搜索时无需 `from`；实体、弧、持仓和顶级账户完全不接受时间范围，而 mindshare 使用 `period`
历史记录	可查询范围为过去 30 天（PAYG）、60 天（Grow）或 2 年（Enterprise）。更早的 `from` 会被截断，`servedFrom` 会说明实际起始时间；早于该时间的 `to` 会导致 `400`。`/v3/key-status` 会通过 `historyFrom` 返回起始时间
分页	将 `nextCursor` 作为 `cursor` 传回。`hasMore: false` 表示最后一页。不支持 offset 和总数。除 `limit` 外，任何参数发生变化都会导致 `400`
列表	标记为列表的参数可接受多个值，可重复传入，也可用逗号分隔。最多 30 个 ID
按 ID 获取	`eventIds`、`storylineIds`、`arcIds`、`callIds` 和 `episodeIds` 最多可获取 30 个，无需 `from`
错误	错误或未知参数会导致 `400`，并在 `details` 中指出字段；过滤器中的未知 ID 会导致 `400`，并显示 `Unknown id: …`。`*Ids` 查询中的未知 ID 会被跳过。没有匹配项时会返回 `200` 和空列表
响应	列表位于顶层，并以其包含的内容命名（`events`、`entities`、`bars` 等），没有 `data` 包装层
速率限制	按密钥计算，并与 `/v2` 共享。收到 `429` 时，等待 `RateLimit-Reset` 秒

没有任何 v3 端点会返回帖子文本。事件包含文字标题和摘要，并链接到其背后的每篇帖子。

Agent 常见误区：

事件。 sort=relevant 会对最近 24 小时的内容排序，并拒绝 from、to、eventIds、 arcId、eventClass、eventType、implication、novelty 和 order=asc；assetClass、alertAction、hasStoryline、notable 和 entityIds（仅限代币和股票）仍可用于过滤。q 会按主题搜索事件、故事线和弧，并将最佳匹配排在前面。大多数事件的 impacts 都为空；movedFirst 或 marketWide 设为 true 表示这次波动很可能另有原因。novelty=new 不会确保每个故事只显示一次：如需如此，请按 storylineId 每个故事保留一个事件。使用 q 时收到 503 表示搜索不可用：请重试，或移除 q。
故事线。 title 和 summary 中的价格和水平数据对应 lastMaterialAt 时刻，而非当前时刻。
调用簿。 请通过 crowdingPercentile 而非 longShare 判断倾向：账户几乎总是偏多。最新一行是实时数据点（live: true），每五分钟重写一次。
热门合约。 mentionCount 统计的是帖子数，而非账户数。超过 30 天的时间范围会被截断为 30 天。
调用。 handle 仅接受 X 账户；目前无法按 Telegram 频道过滤。 /v3/calls/episodes?status=open&from=<now> 会读取所有匹配账户当前持有的内容。持仓查询只接受单个 entityId。
顶级账户。 默认的 metric 为 Standing，衡量的是关注度，而非准确度。若要按调用表现对调用者排名，请传入 metric=alphaScore（相对于市场的收益：加密资产以 BTC 为基准，股票以 SPY 为基准，同时也包含绝对收益）、hitRate 或 avgReturn。查询“最佳调用者”时请使用 alphaScore：avgReturn 未按市场调整，因此少数大额获利或一轮上涨就可能使排名靠前。Track 指标仅对至少有 20 个已评分持仓的账户排名，统计范围为自 2026 年 6 月下旬以来的所有持仓，并每日更新。请同时引用用于排名的数值（例如 track.alphaScore）和 track.scoredEpisodes。若要在新事件匹配筛选条件时收到提醒，而不是轮询，请使用 Auto events 条件（第 3 步）。各系列文档：Entities、Events、Market、Calls、People。

第 3 步：Auto — 条件引擎与触发流水线

Auto 是面向 Agent 的托管式条件引擎 + 触发流水线。你可以描述要监控的内容（价格、技术指标、由大模型评估的条件、定时检查、预测市场活动、资金费率、清算连锁反应、市场情绪），Auto 会持续评估，并在条件判定为真时触发操作。资产不局限于加密货币——HIP-3 永续合约涵盖股票、指数、大宗商品、外汇和 IPO 前公司，全天候 24/7 交易。

Auto 完整文档：docs.elfa.ai/auto/overview

生命周期顺序（强制执行）

对于 API 密钥生命周期/清理调用，在每项操作适用时，务必按以下顺序执行：

POST /v2/auto/queries/validate — 验证 EQL 并预览费用
POST /v2/auto/queries — 创建并激活
POST /v2/auto/queries/{queryId}/cancel — 仅当要在 active 查询达到终止状态前停止它时使用（达到终止状态后会返回 409）
DELETE /v2/auto/queries/{queryId} — 仅当状态已为终止状态（triggered / expired / cancelled / failed）时使用；必须先取消活动查询

取消和删除是不同的操作。 POST /cancel 会将活动查询设为 cancelled（终止状态）。DELETE 会彻底移除记录，且仅适用于终止状态的查询。对活动查询发送 DELETE 会返回 409 Conflict。

x402 模式支持相同的生命周期，但 x402 没有 DELETE 端点（只能取消）。

意图路由（严格）

在编写条件参数之前，根据用户意图选择条件来源：

意图	必需来源	最低必需字段
以账户为锚点的帖子意图（`@user posts ...`）	`source: "tweet"`	`args.username`（不带 `@`）、`args.text`、`args.minConfidence`（用户未给出阈值时使用 `80`）
Telegram 频道意图（“当此频道发布……时”）	`source: "telegram"`	`args.chatUsername` 或 `args.chatId` 其中之一，以及 `args.text`、`args.minConfidence`（用户未给出阈值时使用 `80`）
新闻或世界事件意图（ETF 获批、漏洞利用、上市、某资产的利空新闻）	`source: "events"`	至少一个筛选条件（`args.entity`、`args.eventType`、`args.implication` 等），或 `args.text` + `args.minConfidence` — 参见下文的 Events
官方 SEC 文件意图（新的 8-K、逾期 10-Q/10-K 通知、发行、所有权文件、8-K 条款）	`source: "sec"`	`method`（例如 `base_form_type`、`form_category`、`has_item_1_05`）、作为发行人 CIK 的 `args.ticker`，以及符合各方法允许列表的 `operator`/`value`
在指定的开放 Kalshi 市场上，预测市场的变动/生命周期意图	`source: "kalshi"`	`method`（例如 `yes_price`、`status`、`result`）、当前开放的 Kalshi 市场对应的 `args.ticker`，以及符合各方法允许列表的 `operator`/`value`
Polymarket 结果代币的预测市场价格/交易意图	`source: "polymarket"`	`method`（`price`、`bid`、`ask`、`size`、`side`）、结果代币的 `asset_id` 对应的 `args.ticker`，以及符合各方法允许列表的 `operator`/`value`
永续合约资金费率意图（资金费率过热、资金费率转为负值）	`source: "funding"`	`method`（优先使用 `annualized_rate`）、格式为 `SYMBOL:EXCHANGE` 的 `args.ticker`（例如 `BTC:BINANCE`）
清算流意图（连锁清算、多空头寸平仓潮）	`source: "liquidation"`	`method`（例如 `total_usd_5m`、`total_pct_oi_1h`）、格式为 `SYMBOL:EXCHANGE` 的 `args.ticker`
市场整体情绪（恐惧/贪婪状态）	`source: "fear_greed"`	`method`（`value` 或 `classification`）、空的 `args: {}`
关注关系图意图（谁关注了受监控账户、该账户关注了谁，或一组受追踪账户都关注了同一个账户）	`source: "x_follow_received"` / `"x_follow_made"` / `"x_follow_overlap"`	与来源对应的 `method`、`args.account`（重叠查询使用 `args.accounts`）、`operator` `>` 或 `>=`
推动股票/指数/大宗商品的现实世界催化剂（利率决策、CPI、财报）	催化剂自身的来源（`kalshi` / `polymarket` / `events` / `price`），可选地结合 HIP-3 的 `price` / `ta` 进行确认	选择催化剂来源，然后衔接到受其影响的资产类别 — 参见 Catalyst Triggers
无法自然表达为帖子或事件的模糊世界状态谓词	`source: "llm"`	`method: "athena_condition"`、`args.query`、`args.period`（`>= 1h`）

当提示以账户为锚点时，从 tweet 开始 — 不要先路由到 events 或 llm。当提示以 Telegram 频道为锚点时，从 telegram 开始。当提示涉及某个主题的新闻但未指定账户时，从 events 开始 — 除非这是某发行人的官方 SEC 文件，此时应路由到 sec。当触发条件对应一个可指定的具体预测市场（Kalshi 代码或 Polymarket 结果代币 ID）时，使用 kalshi / polymarket（对于支持的方法，优先于 llm）。只有当谓词无法合理地与帖子、事件或指定的预测市场匹配时，才使用 llm（athena_condition）。

适合建议使用 Auto 的情况

用户希望根据价格阈值接收提醒（“BTC 突破 100k 时提醒我”）
用户希望根据技术指标接收提醒（“RSI 跌破 30 时通知我”）
用户希望定时检查（“每 4 小时检查一次”）或按日历安排（“纽约时间每个工作日上午 9 点”——使用 cron.schedule）
用户希望相同提醒在满足自身条件时持续触发（“每次 BTC 跌破 60k 时都通知我”）——添加顶层 repeat 对象（cooldown + maxTriggers）
用户希望监控叙事／情绪变化（“AI 代币叙事转变时提醒我”）
用户希望设置多条件触发（“BTC 高于 100k 且 ETH 高于 3500”）
用户希望比较实时指标（“价格上穿布林带时提醒我”）
用户希望在触发时进行大模型分析（“触发时运行一次完整分析”）
用户希望设置基于账号的社交触发条件（“@cz_binance 发帖称 Binance Alpha 将上线新代币时通知我”）——使用 Signal：X/Twitter Post（source: "tweet"）
用户希望设置Telegram 频道触发条件（“该频道发布新的 Binance 上币传闻时提醒我”）——使用 Signal：Telegram Channel（source: "telegram"）
用户希望设置新闻触发条件（“SEC 批准现货 ETH ETF 时提醒我”、“ETH 出现利空新闻”、“任何交易所遭黑客攻击”）——使用 Events（source: "events"）
用户希望设置SEC 官方文件触发条件（“Alphabet 提交新的 8-K 时告诉我”、“出现任何逾期 10-Q 通知时提醒我”）——使用带有发行人 CIK 的 source: "sec"
用户希望设置预测市场触发条件（“该 Kalshi 市场的 YES 概率突破 60% 时提醒我”、“市场以 YES 结算时通知我”、“该 Polymarket 结果的交易价格高于 60c 时提醒我”）——使用 Prediction Markets（source: "kalshi" 或 source: "polymarket"）
用户希望设置资金费率／清算／情绪触发条件（“BTC 资金费率转负时提醒我”、“ETH 出现清算连锁反应时通知我”、“恐惧与贪婪指数跌破 20 时提醒我”）——使用 source: "funding" / "liquidation" / "fear_greed"
用户希望设置关注关系图触发条件（“有大人物关注 @elfa_ai 时告诉我”、“cobie 关注新账号时提醒我”、“我追踪的 3 家基金都关注同一账号时通知我”）——使用 source: "x_follow_received" / "x_follow_made" / "x_follow_overlap"
用户希望关注股票／指数／大宗商品的宏观催化因素（“市场开始计入美联储降息时告诉我”、“CPI 高于预期时提醒我关注黄金”）——根据催化因素来源触发，并引用 HIP-3 永续合约，该合约全天候交易。请参阅 Catalyst Triggers

Auto 访问模式

模式	路由前缀	身份验证	适用场景
API key	`/v2/auto/*`	所有路由均需 `x-elfa-api-key`	应用、仪表板
x402 无密钥	`/x402/v2/auto/*`	x402 付款 + `x-elfa-agent-secret`	AI Agent、机器人

x402 Auto（无密钥 Agent 模式）

使用 x402 Auto 时，无需 API key。请改为：

发送 x402 付款标头 PAYMENT-SIGNATURE。仅支持 x402 v2——X-PAYMENT 可作为标头名称的别名，但负载必须是 v2 付款负载
在所有查询生命周期路由中包含 x-elfa-agent-secret

Agent 密钥管理： 生成一次高强度密钥，并在所有调用中重复使用：

openssl rand -hex 32
# or: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

将其保存为 ELFA_AGENT_SECRET。请勿每次请求都轮换密钥——x402 会话所有权由 SHA256(secret) 派生。若更改密钥，Agent 身份也会改变，现有查询／会话可能无法访问。

自动定价（两种模式）

API 密钥模式（/v2/auto/*）——从您的信用余额中扣费：

操作	积分	备注
`POST /v2/auto/chat`（Builder Chat）	`1 + dynamic`	基础费用为 1 积分，另按大模型用量动态收费：`ceil(request_cost * 750)`
`POST /v2/auto/queries`（创建）	由模拟驱动	基础费用为 `5`，每次模拟的大模型调用：快速模式 `+5`，专家模式 `+18`
`POST /v2/auto/queries/validate`	免费	返回费用估算——创建前请务必调用
每篇 X 账号帖子（在 Elfa 实时数据集之外的账号上发布 `tweet`）	计划运行期间，每篇收费 `creditsPerPost`（`1`）	不计入 `estimatedCredits` 或 `x-elfa-credits`；请参阅 Validate 中的 `tweetAccounts`
`GET /v2/auto/queries/*`（列表、轮询、流、会话）	免费
`POST /v2/auto/queries/:queryId/cancel`（取消活动查询）	免费
`DELETE /v2/auto/queries/:queryId`（删除已结束的查询）	免费
`GET /v2/auto/validate-symbol/:exchange/:symbol`	免费

创建操作的美元参考费用：基础费用 $0.0725，快速调用 +$0.0725，专家调用 +$0.261。提交前请使用 /queries/validate 预览准确费用。

x402 模式（/x402/v2/auto/*）——按请求使用 USDC 付费，支持 Base、Arbitrum、Polygon、Avalanche 或 Solana：

Builder Chat 按速度计费，有两种方案——固定价格的 exact，或在 Base 上、402 列出该方案时使用预付费的 batch-settlement 通道，仅按本轮实际用量收费，最高不超过上限：

速度	`exact`（固定价格）	`batch-settlement`（最高收费）
`fast`	$1	$2
`expert`（默认）	$2	$6

操作	积分	USDC 费用
查询创建——基础费用	5	$0.0725
每次快速大模型调用	+5	+$0.0725
每次专家大模型调用	+18	+$0.261
验证、轮询、取消、会话、流	免费	免费

x402 自动化示例：

// Validate a query (x402 Auto)
const response = await x402Fetch(
  "https://api.elfa.ai/x402/v2/auto/queries/validate",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-elfa-agent-secret": process.env.ELFA_AGENT_SECRET,
    },
    body: JSON.stringify({
      query: {
        conditions: { AND: [{ source: "price", method: "current", args: { symbol: "BTC", exchange: "hyperliquid" }, operator: ">", value: 100000 }] },
        actions: [{ stepId: "step_1", type: "notify", params: { message: "BTC crossed 100k" } }],
        expiresIn: "24h"
      }
    }),
  });

建议的调用顺序（确定性 Agent 路径）

API 密钥模式（/v2/auto/*）：

POST /v2/auto/chat — 请 Builder Chat 起草查询
POST /v2/auto/queries/validate — 验证 EQL 并预览费用
POST /v2/auto/queries — 创建并激活
GET /v2/auto/queries/{queryId}/stream — 流式接收通知（或轮询）
GET /v2/auto/queries/{queryId}/sessions + /sessions/{sessionId} — 获取大模型输出（使用 llm 操作时）
（可选清理）POST /v2/auto/queries/{queryId}/cancel — 仅在状态为 active 时取消（如果查询已结束，则返回 409）
（可选清理）DELETE /v2/auto/queries/{queryId} — 仅在查询结束后删除（triggered / expired / cancelled / failed）；活动查询会被拒绝并返回 409

x402 模式（/x402/v2/auto/*）：

POST /x402/v2/auto/chat — 请 Builder Chat 起草查询
POST /x402/v2/auto/queries/validate — 验证 EQL 并预览费用
POST /x402/v2/auto/queries — 创建并激活
GET /x402/v2/auto/queries/{queryId}/stream — 流式接收通知（或通过 POST 轮询）
POST /x402/v2/auto/queries/{queryId}/sessions + /sessions/{sessionId} — 获取大模型输出
（可选清理）POST /x402/v2/auto/queries/{queryId}/cancel — 仅在状态为 active 时取消。（x402 没有用于删除已结束查询的端点。）

创建前务必先验证。 验证会返回结构化错误，您可以据此迭代修复，而无需消耗积分。

故障处理顺序（按顺序执行）：

对暂时性网络错误使用指数退避重试。
遇到 400 / 422 验证失败 → 根据验证错误—后续操作表修复查询，然后重新验证。
遇到 401 / 403 身份验证失败 → 刷新凭据或重新检查密钥权限。
遇到 402 x402 付款失败 → 重新计算费用，并使用有效的付款载荷重试。
遇到 410（SSE 流已关闭）→ 重新打开流，或改用轮询。

常见 Agent 工作流：

基于轮询的大模型工作流：

POST /v2/auto/queries                               → create query with action.type = "llm"
GET  /v2/auto/queries/{queryId}                     → poll until execution with sessionId appears
                                                      (latestEvaluation.conditionStates[] shows
                                                       progress while you wait)
GET  /v2/auto/queries/{queryId}/sessions/{sessionId} → fetch full analysis

基于 Webhook 的大模型工作流：

POST /v2/auto/queries                               → create with action.type = "llm" and params.action
(wait for webhook)                                  → receive session reference / output
(optional) GET session fetch                        → /v2/auto/queries/{queryId}/sessions/{sessionId}

Builder Chat

Builder Chat（POST /v2/auto/chat 或 POST /x402/v2/auto/chat）使用 AI 将自然语言转换为 EQL 查询。使用 sessionId 进行多轮对话。

{
  "message": "Alert me when BTC breaks 100k with RSI confirmation above 55",
  "speed": "expert",
  "sessionId": "optional-session-id"
}

响应（API 密钥模式）：

{
  "sessionId": "session-uuid",
  "response": "I can help with that... (markdown + EQL JSON code block)",
  "title": "BTC Breakout Alert",
  "reasoning": null,
  "planIds": [],
  "credits": 100
}

credits 表示本轮消耗的额度，与 x-elfa-credits 标头中的总额相同。Builder Chat 采用动态定价，因此请读取该值，不要假设每次调用的费用固定。

响应消息包含 AI 以 Markdown 格式生成的回复。生成 EQL 时，内容会放在 JSON 代码块中——提取后，通过 /queries/validate 验证，再通过 /queries 提交。

Builder Chat 提示：

包含 title 和 description（通知中会显示这些内容，以便接收者在数小时或数天后知道触发了什么）
指定代币符号、时间范围、触发行为（一次性——默认设置——或重复触发）以及投递目标。对于同一条件的重复触发，请要求提供 repeat 对象（cooldown + maxTriggers）；对于固定时间表，请使用 cron 条件
对于 Signal 触发器，请提供客观的匹配描述（避免使用“看涨氛围”等模糊措辞）
附加 "If anything is unsupported, return the closest supported query and list substitutions"，以妥善处理边缘情况
对新鲜信号，优先使用 24h–3d 的 expiresIn
持久化 sessionId 并在后续提示中重复使用，以便模型在多轮对话中保留上下文

高影响力提示词包——将以下内容作为 message 字段传入 POST /v2/auto/chat：

1) 带方向过滤的复杂 TA 突破：

Build an Auto query:
- title + description: short human-readable summary and 1-2 sentence thesis
- symbols: BTC, ETH, SOL
- timeframe: 5m
- trigger when price breaks previous 1h range high or low
- confirm direction with RSI(14): >55 for upside, <45 for downside
- actions: telegram alert + webhook to https://your-runner.example/auto/events
- one-time trigger, expires in 48h
If anything is unsupported, return the closest supported query and list substitutions.

2) CEX + DEX 监控包：

Build an Auto query pack for supported CEX + DEX symbols:
- title + description per query: short summary and thesis sentence
- watchlist: WBTC, ETH, SOL, HYPE
- trigger when 15m volume surge aligns with price momentum
- action: webhook to https://your-runner.example/auto/events
- include symbol and trigger summary in payload
- expires in 24h
If any symbol/source is unsupported, skip it and report skipped items.

3) 触发时提供新闻 + X 情绪背景：

Build an Auto query:
- title + description: short summary and the thesis behind watching this
- monitor BTC and ETH for abnormal 1h move + volume confirmation
- on trigger run llm action that adds:
  - latest market news context
  - X sentiment summary
  - risk note
- also send telegram alert with a short summary
- expires in 24h

4) 预测市场论点监控器（Kalshi）：

Build an Auto query:
- title + description: name the market thesis and the move you're watching for
- source: kalshi
- ticker: <a confirmed-open Kalshi market ticker, e.g. KXBTC-26APR0803-T77799.99>
- trigger when the YES implied probability crosses above 0.6
- action: llm to produce a catalyst hypothesis + invalidation level
- deliver to webhook: https://your-runner.example/auto/events
- include decision priority: high/medium/low
- expires in 2d
If the ticker is not open or anything is unsupported, return the closest supported query and list substitutions.

5) 投资组合风险护栏：

Build an Auto query:
- title + description: portfolio guardrail label and the risk scenario it covers
- watch my portfolio symbols: BTC, ETH, SOL, HYPE
- trigger on downside acceleration and momentum weakness
- action: telegram alert with severity and suggested next check
- recurring checks, expires in 3d

6) 带严格后续约定的 Agent 交接：

Build an Auto query:
- title + description: breakout playbook name and the follow-up intent
- trigger on breakout + trend-confirmation conditions
- action: webhook to https://your-runner.example/auto/events
- include fields: eventId, symbol, triggerReason, priority, queryId
- downstream agent decides next action under policy constraints
- expires in 24h

7) Signal——基于账户的 X/Twitter 帖子监控器：

Build an Auto query:
- title + description: short summary anchored to the account + intent
- use Signal category:
  - condition source: tweet
  - username: cz_binance (no leading @)
  - match description: "Binance Alpha is listing a new token"
  - minConfidence: 80
- action: notify (or telegram_bot) with a concise message
- expires in 24h
If unsupported, return closest supported query and list substitutions.

8) Signal——事件优先的催化剂监控器：

Build an Auto query:
- title + description: catalyst name and why it matters now
- use an events condition:
  - condition source: events
  - filters: entity ETH, eventType regulatory
  - claim: "the SEC approves a spot ETH ETF"
  - minConfidence: 80
- action: webhook to https://your-runner.example/auto/events
- include queryId, eventId, and short trigger reason in payload
- expires in 24h

查询模型（EQL）

查询包含 conditions、actions 和 expiresIn（以及可选的同级字段 repeat——默认情况下，计划只触发一次；请参阅下文的重复触发）：

{
  "title": "BTC RSI oversold on 1h",
  "description": "Mean-reversion entry: if BTC 1h RSI dips under 30, consider scaling in.",
  "conditions": {
    "AND": [
      {
        "source": "ta",
        "method": "rsi",
        "args": { "symbol": "BTC", "timeframe": "1h", "period": 14, "exchange": "hyperliquid" },
        "operator": "<",
        "value": 30
      }
    ]
  },
  "actions": [
    { "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-endpoint.example/events" } }
  ],
  "expiresIn": "24h"
}

条件规则：

根组必须是 AND 或 OR
嵌套组最多 3 层，叶条件最多 10 个
多代币符号：单个查询可以同时要求 BTC、ETH 和 SOL 条件成立

允许的 expiresIn 值： 1h、2h、4h、8h、12h、24h、48h（2d）、72h（3d）、120h（5d）、168h（7d）、240h（10d）、336h（14d）、504h（21d）、720h（30d——硬性上限）。 优先使用 24h–72h——信号会衰减，较短的窗口会促使重新评估。仅在较慢的结构性论点（代币解锁、期权到期、月度跟单交易）中使用 240h–720h，不要用于短周期 TA/剥头皮交易。

计划限制（每个账户的活跃计划数）： 根据 API 密钥级别，每个账户可同时持有的活跃计划数有限：Free 为 2，Grow 为 50，PAYG/Enterprise 不限。无论级别如何，活跃计划数的硬性上限均为 500；超过任一上限都会返回 409。只有活跃计划会计入——已过期、已取消或已终止的计划会释放容量，因此取消过时计划（或选择更短的 expiresIn）是最快的腾出空间方式。

重复触发（repeat）——按自身条件重复触发的计划：

默认情况下，计划只触发一次，然后进入终止状态。可选的顶层 repeat 对象（与 expiresIn 同级）会让计划保持活跃，并在其自身条件满足时再次触发——如果想要“每次 BTC 跌破 60k 时都通知我”，而不是按固定的 cron 节奏触发，这就是合适的工具。

{
  "conditions": { "AND": ["..."] },
  "actions": ["..."],
  "expiresIn": "7d",
  "repeat": { "cooldown": "1h", "maxTriggers": 10 }
}

存在 repeat 时，两个字段都必须提供：

字段	类型	含义
`cooldown`	字符串	两次触发之间的最短间隔。`"0"` 表示禁用速率限制。
`maxTriggers`	数字	生命周期内的触发次数上限（`1`–`1000`）；达到上限后，计划将终止。

cooldown 的允许值（它有自己的一组取值——允许小于 1 小时，不同于 cron/llm 的 1h 最低限制）：1m、5m、15m、30m、1h、2h、4h、8h、12h、24h、1d、7d，以及 "0"。使用 "0" 表示“每次不同的事件都触发”（例如每条匹配的推文或 Telegram 消息）。
maxTriggers 统计计划在其整个生命周期内触发的次数（与操作步骤的数量不同）。请检查 cooldown × maxTriggers 是否与 expiresIn 相符——如果剩余时间不足，计划会在达到上限之前过期。较长的 expiresIn 可让计划在一段安静期内继续等待；它不会提高触发上限。
唯一的重置规则。 repeat 计划只有在触发信号消失后才会再次触发。状态条件（price / ta / llm-布尔值）触发后会解除布防，并在整个条件树下一次求值为 false 时重新布防；事件条件（tweet.semantic / telegram.semantic / events.match / sec）会消耗已匹配的事件，并在下一个不同的事件发生时再次触发。

仍会被拒绝： 将 repeat 与循环 cron 条件（cron.every / cron.schedule）组合使用——两者都提供重复触发，因此组合后会因 EQL_INVALID_REPEAT 验证失败。对于固定频率的循环计划，请单独使用 cron 条件；对于由条件驱动的循环计划，请使用 repeat。

避免过度触发： 主要风险是条件持续反复变为 true——指标在阈值附近波动，或账户消息过于频繁。cooldown 是你的速率限制下限（状态/指标条件绝不要使用 "0"）；maxTriggers 是硬性熔断器（请谨慎设置，确保失控的条件会自行限制触发次数）。像 price < 60000 这样的状态条件每次重新越过阈值都会触发，因此应优先使用转换运算符（使用 crosses_below / crosses_above，而非 < / >），让阈值与当前值保持足够距离，让 cooldown 与信号的时间范围相匹配，并从保守设置开始，再逐步放宽。

推荐的初始设置：

条件类型	`cooldown`	`maxTriggers`	说明
价格 / TA 状态（`price`、`ta`）	`1h`–`4h`（≥ 你的时间范围）	`3`–`10`	优先使用 `crosses_*` 运算符；此处不要使用 `"0"`。
LLM 谓词（`llm.athena_condition`）	≥ 周期（最短 `1h`）	`3`–`5`	LLM 已按 `period` 重新检查——不要比它重新评估的速度更快地再次发出提醒。
事件 — 单一/不活跃账户或频道（`tweet`、`telegram`）	`0`–`15m`	`10`–`20`	每条不同的帖子/消息都是一个独立事件；除非来源消息过于频繁，否则使用 `"0"` 没问题。
事件 — 高活跃账户/频道或宽泛的 `events` 筛选条件	`15m`–`1h`	`10`–`20`	较短的冷却时间可将一波提及或同一事件的后续消息合并为一条提醒。
SEC 文件事件（`sec`）	`0`–`1h`	`10`–`20`	如果希望每份匹配的文件都触发，请使用 `"0"`；对于消息较多的表单类别，请添加冷却时间。
清算连锁事件（`liquidation`）	`1h`+	`5`–`10`	时间窗口会衰减至零，因此计划会针对每次连锁事件重新布防；冷却时间可防止同一次持续较久的连锁事件反复触发提醒。

允许的操作类型： webhook、notify、telegram_bot、llm。每个查询的 actions 数组恰好包含一个步骤——使用 params.action 运行独立的 LLM 工作；通过带有 params.callback.action 的 llm 操作串联后续工作，或者让你的运行器从触发事件分发后续操作。

操作参数结构（关键字段）：

`type`	必需的 `params`	可选的 `params`
`notify`	`message`（1–1000 个字符）	—
`webhook`	`url`（仅限 https，主机必须在允许列表中）	`signingSecret`（仅写入——请在生产环境中设置此项）、`allNotifications`（默认值为 `false`）
`telegram_bot`	`botToken`、`chatId`	`allNotifications`（默认值为 `false`）
`llm`	`action` ∈ `chat` / `summary` / `macro` / `accountAnalysis` / `tokenDiscovery` / `tokenAnalysis`	用于串联后续操作的 `callback.action`（`webhook` 回调还可使用 `includeAnalysis`）、`speed`（`fast` / `expert`）、每种操作的额外参数（例如 `chat` 中的 `message`）
`telegram_bot` 不接收 `message` 字段——消息正文会根据查询的 `title`、`description` 和触发上下文自动组合。需要自行指定消息文本时，请使用 `notify`（应用内推送）。在 `webhook` / `telegram_bot` 上设置 `allNotifications: true`，可让目标在触发条件满足时之外，也接收生命周期通知（失败／过期／运行失败）。

触发器 — 条件来源

市场数据交易场所（exchange）——每个 price 和 ta 条件都必须包含：

每个 price 和 ta 条件都必须包含一个 exchange 参数，用于选择该条件所依据的市场数据交易场所。允许的值为：hyperliquid、binance（必须使用精确的小写枚举值）。不再接受 gmx：创建和验证时会以 EQL_INVALID_ARG_VALUE 拒绝该值。草稿仍会存储 gmx 条件，而转换时会以 EQL_VALIDATION_ERROR 拒绝该值。此参数只影响该条件的数据源。缺少 exchange 的 price / ta 条件无法通过验证。

各交易场所的数据说明：

binance 读取其 USD-M 永续合约市场，并使用 Binance 自身的基础币种符号惯例（1000PEPE，而不是 kPEPE）；创建时会根据 Binance 实时永续合约目录进行验证。

{ "source": "price", "method": "current", "args": { "symbol": "BTC", "exchange": "hyperliquid" }, "operator": ">", "value": 100000 }

价格来源（price）：

方法	参数	返回值	说明
`current`	`symbol`、`exchange`	数字	当前价格
`change`	`symbol`、`exchange`、`period`	数字	周期内的涨跌幅
`high`	`symbol`、`exchange`、`period`	数字	周期内的最高价
`low`	`symbol`、`exchange`、`period`	数字	周期内的最低价
`volume`	`symbol`、`exchange`、`period`	数字	周期内的成交量（USD）

**TA 来源（ta）——技术指标：**每种方法还需要 symbol、timeframe 和 exchange。

方法	必需参数	可选参数	返回值
`rsi`	`symbol`、`timeframe`、`exchange`	`period`（默认值 14）	RSI（0-100）
`macd_value`	`symbol`、`timeframe`、`exchange`	—	MACD 线
`macd_signal`	`symbol`、`timeframe`、`exchange`	—	MACD 信号线
`macd_histogram`	`symbol`、`timeframe`、`exchange`	—	MACD 柱
`bbands_upper`	`symbol`、`timeframe`、`exchange`	`period`（默认值 20）	布林带上轨
`bbands_middle`	`symbol`、`timeframe`、`exchange`	`period`（默认值 20）	布林带中轨
`bbands_lower`	`symbol`、`timeframe`、`exchange`	`period`（默认值 20）	布林带下轨
`ema`	`symbol`、`timeframe`、`exchange`、`period`	—	指数移动平均线
`sma`	`symbol`、`timeframe`、`exchange`、`period`	—	简单移动平均线
`atr`	`symbol`、`timeframe`、`exchange`	`period`（默认值 14）	平均真实波幅
`stoch_k`	`symbol`、`timeframe`、`exchange`	—	随机指标 %K
`stoch_d`	`symbol`、`timeframe`、`exchange`	—	随机指标 %D
`cci`	`symbol`、`timeframe`、`exchange`	`period`（默认值 20）	CCI
`willr`	`symbol`、`timeframe`、`exchange`	`period`（默认值 14）	威廉指标 %R

TA 关键规则：

每个 ta（以及 price）条件都必须包含 exchange（hyperliquid 或 binance）
ema 和 sma 必须包含 period，该参数不可选
rsi、bbands_*、atr、cci 和 willr 接受可选的 period，默认值见上文
period 必须是 JSON 数字（14），不能是字符串（"14"）
使用 period，不要使用 length——length 不是受支持的别名
timeframe 的取值：1m、5m、15m、30m、1h、2h、4h、8h、12h、1d

Cron 来源（cron）：

方法	参数	说明
`once`	`period`	创建后经过指定周期，在首次到期评估时或之后返回 True
`onceRemainTrue`	`period`	首次到期评估时返回 True，并持续为 True
`every`	`period`	每个周期间隔返回 True
`schedule`	`expression`、`timezone?`	每当 5 字段 Cron `expression` 在 `timezone` 中匹配时返回 True
`once`、`onceRemainTrue` 和 `every` 是以查询创建时间为基准测量的间隔方法。
`schedule` 是一种日历／墙上时钟方法：

expression 是经典的 5 字段 cron 字符串（minute hour day-of-month month day-of-week）——例如 0 9 * * 1-5（工作日 09:00）。
timezone 是可选项，默认为 UTC。设置后必须是有效的 IANA 名称（例如 America/New_York、Asia/Singapore），以便正确处理夏令时转换。不接受 +02:00 这类固定时差字符串。
schedule 与其他 cron 方法一样，强制采用 最短 1 小时的间隔：分钟字段必须是单个固定值（0–59）。分钟字段中的通配符、步长、列表或范围都会被拒绝。
- 允许：7 * * * *（每小时第 7 分钟）、0 9 * * 1-5（工作日 09:00）、30 8 * * *（每天 08:30）。
- 不允许：* * * * *（每分钟）、*/15 * * * *（每 15 分钟）、0,30 * * * *（每小时两次）。
schedule 不接受 period 参数。

Builder Chat 支持尚未就绪： cron.schedule 可通过直接的 EQL/API 路径使用（Validate / Create）。Builder Chat 目前还不能可靠地生成 cron.schedule——请直接编写日历计划，并通过 /v2/auto/queries/validate 确认。

LLM 来源（llm）：

方法	参数	描述
`athena_condition`	`query`、`period`、`speed?`	由 LLM 评估的条件（自然语言）

信号来源 — X/Twitter 帖子（tweet）：

在 Builder Chat 目录中，这属于 Signal 类别，即 X/Twitter 帖子。

方法	必需参数	返回值	描述
`semantic`	`username`、`text`、`minConfidence`	boolean	当语义置信度达到阈值时，匹配来自指定 X/Twitter 账号的帖子

规则：

传入的 username 不得包含 @（例如 cz_binance，而非 @cz_binance）。
username 可以是任何公开的 X 账号。Validate 的 tweetAccounts 会说明每个账号的计费方式：included（Elfa 的实时账号集）不额外收费；per_post 则会在计划运行期间对每条帖子收取 creditsPerPost（包括帖子、引用、笔记和文章；不包括回复或转发），无论是否匹配，且费用不计入 estimatedCredits。在 Create 前告知用户。没有付费 API 计划的密钥以及 x402 只能监控 included 账号；被拒绝的账号会作为 errors[] 条目返回（参见验证错误与后续操作表）。Builder Chat 只会为 included 账号草拟 tweet 条件；其他账号请自行编写。详情：X 账号与按帖子计费。
minConfidence 必须是介于 0 和 100 之间的 JSON 整数；用户未指定阈值时，使用 80。
method、operator 和 value 会自动填入默认值（semantic、==、true）——不要将它们包含在条件 JSON 中。

{
  "source": "tweet",
  "args": {
    "username": "cz_binance",
    "text": "Binance Alpha is listing a new token",
    "minConfidence": 80
  }
}

信号来源 — Telegram 频道（telegram）：

在 Builder Chat 目录中，这属于 Signal 类别，即 Telegram 频道。

方法	必需参数	返回值	描述
`semantic`	`chatUsername` 和／或 `chatId`、`text`、`minConfidence`	boolean	当语义置信度达到阈值时，匹配来自受监控的公开 Telegram 频道的消息

规则：

使用完整方法形式时，提供 chatUsername、chatId 或两者。简写条件形式必须且只能提供一个标识符；若完整条件中同时提供两者，它们必须解析到同一频道。
知道公开频道用户名时，优先使用不带 @ 或 t.me/ 的 chatUsername。
仅当 chatId 来自工具或现有计划时才使用；它必须是有符号 64 位整数的字符串。
创建时，该频道必须解析为受监控的公开 Telegram 频道，否则验证／创建将失败。
minConfidence 必须是介于 0 和 100 之间的 JSON 整数；用户未指定阈值时，使用 80。

{
  "source": "telegram",
  "args": {
    "chatUsername": "<monitored_public_channel_username>",
    "text": "new Binance listing rumor",
    "minConfidence": 80
  }
}

事件（events）： 在 Builder Chat 目录中，这是 Signal 类别 Events。

在发生事件时触发：有关资产、项目、公司、人物或宏观经济的新闻，包括上市、黑客攻击、监管决定、宏观数据发布、公司新闻、大额资金流动，以及看涨或看跌新闻。GET /v3/events（API v3）提供这些事件，每条事件均根据多篇帖子整理撰写；条件使用该端点的筛选值，并以相同方式进行匹配。用于查找有关某个主题的新闻；查找某个账号发布的帖子则使用 tweet。目前尚未加入应用的可视化构建器目录；Builder Chat 和 API 均支持创建此条件。完整参考文档：https://docs.elfa.ai/auto/events — 事件本身：https://docs.elfa.ai/api/v3/events

方法	参数（均为可选；至少需要一个筛选条件或 `text`）	返回值
`match`	`entity`、`entityType`、`eventClass`、`eventType`、`implication`、`alertAction`、`assetClass`、`novelty`、`text` + `minConfidence`	布尔值

entity：来自 GET /v3/entities 的一个 ID（精确来说，就是 /v3/events 在 entityIds 中使用的同一个 ID），或一个代码或名称（"ETH"、"Hyperliquid"）。代码或名称会优先匹配代码："Elon Musk" 会解析为名为 MUSK 的代币，"Fed" 会解析为代码为 FED 的股票，因此对于非代币或股票的实体，请设置 entityType（token、equity、project、person、organisation）。中央银行、监管机构和宏观主题不是实体——请使用 eventType + text。
eventClass：market（新闻，包括关于单个资产的新闻）或 call（交易者持仓）。对于单个资产，请使用 entity，而不是 asset。
eventType：security、listing、regulatory、macro、protocol、company、marketFlow、price、social、other。
implication：bullish、bearish、mixed、unclear——表示对所列资产可能产生的方向。将立场填在此处，绝不要写在 text 中。
alertAction：alert（判断为有重大影响）或 monitor（值得关注）。assetClass：crypto 或 equity（未提及资产的事件无需传入）。novelty：new 或 update——不能可靠地过滤重复内容：后续对同一事件的大多数解读仍会标为 new。
text + minConfidence（必须同时提供或都不提供，起始值为 80）：一条具体主张，并根据事件标题和摘要进行核验。仅用于过滤的条件不消耗额度。
每个参数只能有一个值；多个资产或类型 → 在 OR 下设置多个 events 条件。传入数组会被拒绝，并返回 EQL_INVALID_JSON。
实际上仅支持简写形式：完整形式只能使用 operator: "=="、value: true。不支持动态值。
运行时：事件会在首次发布后的数分钟到数小时内到达（若想第一时间获取，请监控该账号的 tweet）；只会匹配不到一小时前的事件；每个事件最多触发一次计划；当天已报道过的事件中，约有 1/9 会继续后续报道。若想每个事件故事只处理一次，请跳过 storylineId 已保存的事件（使用下文所述的 eventId 获取）；storylineId 在 call 事件和少数未串联的事件中为 null。
创建前先预览：使用相同的筛选条件调用 GET /v3/events，并设置 from=<now - 1d>（对于 entity，设置 entityIds=<id>），即可查看该条件会匹配哪些事件。q 没有对应项：text 会针对每个事件核验一条主张。每个参数只能有一个值，不支持时间范围。映射说明：https://docs.elfa.ai/auto/events#from-v3-events
触发器载荷中的 match：包含 eventId、title（事件的 alertTitle）、eventClass、eventType、implication、alertAction、novelty、timeSensitivity、citedSourceCount、analyzedAt（ISO 8601）、entities[]（symbol、name、entityType；最多 10 个）以及核验 text 时的 confidence。不包含链接和摘要。
match.eventId 是 /v3/events 中事件的 id——不是 Webhook 投递 ID（X-Auto-Event-Id，应使用它去重投递）。GET /v3/events?eventIds=<match.eventId> 会返回摘要、带链接的引用帖子、价格影响和 storylineId。
/v3 端点需要 Pay-as-you-go、Grow 或 Enterprise 密钥。若没有此类密钥，请使用代码或名称指定实体，并查看 Validate 响应以确认解析结果。

{
  "source": "events",
  "args": { "entity": "ETH", "implication": "bearish" }
}

信号选择策略（选择哪个来源）：

意图与账号绑定（提示词中包含账号句柄）→ tweet。
意图与频道绑定（提示词中包含公开 Telegram 频道）→ telegram。
关于某个主题的新闻（没有指定账号）→ events。
官方 SEC 文件意图（发行人 CIK、表格类型、8-K 条目）→ sec。
若触发条件可能通过帖子或事件表达，优先选择 tweet/telegram/events，而不是 llm。
只有当条件不适合自然匹配帖子或事件时，才回退到 llm（athena_condition）。

信号 args.text 撰写准则——匹配质量主要取决于 text 的质量。请写简短的事实性主张，不要写监控指令。

表述含糊（不佳）	可执行的表述（良好）
`Bearish vibes`	`Opens a short position on oil`
`Something bullish`	`Announces a new stake in TSLA`
`Bullish on a coin`	`Posts that they're bullish on $HYPE and $SOL`
`Alpha group update`	`new Binance listing rumor`
`Team news`	`team confirms mainnet launch`
`Market crash`（事件 `text`）	`Major DeFi protocol suffers a $200M exploit`
`War conflict`（事件 `text`）	`US imposes new sanctions on Russia`
`Bearish ETH news`（事件 `text`）	不要使用 `text` — `{ "entity": "ETH", "implication": "bearish" }`

其他约束：

保持 text 原子化——每个条件只包含一个事件／主题。
对于 tweet，不要在 text 中重复账号身份——username 已限定账号范围。
对于 telegram，不要在 text 中重复频道身份——chatUsername 或 chatId 已限定频道范围。
将 A or B 意图拆分为多个 Signal 条件，并用 OR 连接；将 A and B 拆分为多个条件，并用 AND 连接。
对于事件驱动意图（tweet／telegram／events）和定期调度意图（cron.every），优先使用单独的查询，以便运行时语义更清晰。

**minConfidence 调整：**默认值为 80；提高到 85–90 可减少误报；如果需要更高的召回率，可降低到 70–75。

**调度周期（cron / llm）：**对于 cron 间隔方法（once、 onceRemainTrue、every）和 llm 来源，period 表示调度间隔，最短为 1h。允许的值：1h、2h、4h、8h、12h、24h、1d、7d。cron.schedule 不接受 period——它由 5 字段 cron expression 驱动，并遵循相同的 1h 最短间隔（每小时最多触发一次）。

Signal 来源由事件驱动，而非由调度驱动——它们会在收到相关提及事件时进行评估，而不是按轮询间隔运行。它们仍可通过 AND／OR 与其他条件类型组合。

SEC 文件来源（sec）：

根据丰富的 SEC 文件元数据触发——例如新的 8-K、逾期定期文件通知、发行表格或特定的 8-K 项目。sec 条件使用完整的 EQL 条件形式，并遵守标准限制（深度为 3，最多 10 个叶节点），因此可在 AND／OR 组中与其他来源组合。

CIK 路由：args.ticker 是发行方的 CIK，不是股票代码。它必须为 1–10 位数字，会先去除首尾空格，再规范化为 10 位、以零填充的 CIK（"1652044" → "0001652044"）。验证／创建操作会根据 SEC 提交元数据验证 CIK，并拒绝未知或格式错误的值，而不会创建永远无法触发的计划。

方法	返回值	运算符	描述
`base_form_type`	enum	`==` `!=`	规范化后的基础表单类型 — 去除修正标记（`10-K/A` → `10-K`），`424B*` → `424B`
`form_category`	enum	`==` `!=`	`current_report`（当前报告）、`periodic_report`（定期报告）、`ownership`（所有权）、`offering`（发行）、`proxy_ma`（代理权／并购）、`listing`（上市）、`registered_fund`（注册基金）、`sec_review`（SEC 审查）、`other`（其他）
`is_amendment`	boolean	`==` `!=`	表单以 `/A` 结尾
`is_late_filing`	boolean	`==` `!=`	延迟申报通知表单（`NT 10-K`、`NT 10-Q`、`NT 20-F`）
`is_offering`	boolean	`==` `!=`	发行、注册或招股说明书类申报
`is_ownership_filing`	boolean	`==` `!=`	内部人士、受益所有权或机构所有权申报
`has_item_1_03`	boolean	`==` `!=`	8-K 第 1.03 项 — 破产或接管
`has_item_1_05`	boolean	`==` `!=`	8-K 第 1.05 项 — 重大网络安全事件
`has_item_2_02`	boolean	`==` `!=`	8-K 第 2.02 项 — 经营业绩
`has_item_2_05`	boolean	`==` `!=`	8-K 第 2.05 项 — 退出或处置成本
`has_item_3_01`	boolean	`==` `!=`	8-K 第 3.01 项 — 退市或上市合规通知
`has_item_4_01`	boolean	`==` `!=`	8-K 第 4.01 项 — 更换审计会计师
`has_item_5_02`	boolean	`==` `!=`	8-K 第 5.02 项 — 董事／高管变动
`has_item_8_01`	boolean	`==` `!=`	8-K 第 8.01 项 — 其他报告事件
`has_primary_document`	boolean	`==` `!=`	已找到主要申报文件名
`has_xbrl`	boolean	`==` `!=`	归档文件包含 XBRL 资料
`submission_match_found`	boolean	`==` `!=`	已在 SEC 申报元数据中匹配到 accession
`document_count`	number	`>` `<` `>=` `<=` `==` `!=`	发现的归档文件数量

{
  "source": "sec",
  "method": "base_form_type",
  "args": { "ticker": "0001652044" },
  "operator": "==",
  "value": "8-K"
}

用户指定具体表单时使用 base_form_type，指定一类申报时使用 form_category，使用布尔方法表示规范化标志（延迟通知使用 is_late_filing，注册和招股说明书使用 is_offering，网络安全披露使用 has_item_1_05）。sec 与 Signal 来源一样由事件驱动，因此搭配 repeat 使用时，会在下一份不同的申报出现时再次触发。完整参考： SEC Filings。

预测市场来源（kalshi）：

针对 Kalshi 预测市场活动触发 — 实时成交记录和市场生命周期。每个 kalshi 条件恰好接受一个参数 ticker：一个完整的开放 Kalshi 市场代码（例如 KXBTC-26APR0803-T77799.99 = 系列 + 事件 + 行权价）。如果触发条件是受支持的 Kalshi 方法，优先使用 kalshi 而不是 llm；如果关注的是事件的隐含概率而非资产的现货价格，则优先使用 kalshi 而不是 price/ta。

基于交易的方法 — 根据最新的已执行交易记录进行评估：

方法	返回值	描述
`yes_price`	number `0`–`1`	YES 成交价 = YES 的实时隐含概率
`no_price`	number `0`–`1`	NO 成交价（NO 的隐含概率）
`trade_size`	number ≥ 0	该笔成交的合约数量
`taker_outcome_side`	enum `yes` / `no`	主动方（taker）押注的结果方向
`taker_book_side`	enum `bid` / `ask`	`bid` = YES 方向的压力，`ask` = NO 方向的压力
`is_block_trade`	boolean	大额场外协商大宗交易时为 `true`

基于市场的方法 — 根据市场生命周期更新进行评估：

方法	返回值	描述
`status`	enum `active` / `closed` / `determined` / `settled` / `finalized`	生命周期状态（`active` = 唯一可交易状态）
`result`	enum `yes` / `no`	结算结果（市场结果确定前为空）
`settlement_value`	number ≥ 0	最终结算金额（美元）（结算时填充）

各方法支持的运算符（按方法限制）：

方法	允许的运算符
`yes_price`、`no_price`	`>` `<` `>=` `<=` `==` `!=` `crosses_above` `crosses_below`
`trade_size`、`settlement_value`	`>` `<` `>=` `<=` `==` `!=`
`taker_outcome_side`、`taker_book_side`、`status`、`result`、`is_block_trade`	`==` `!=`

只有价格方法（yes_price / no_price）支持状态转换运算符 crosses_above / crosses_below；枚举和布尔方法仅支持相等性运算。value 必须是与方法类型匹配的字面值（不支持字段与字段之间的动态取值），而 is_block_trade 接受 JSON 布尔值 true / false（不是字符串 "true" / "false"）。

**仅限开放市场：**创建／验证时，args.ticker 会与 Kalshi 当前开放市场目录进行核验。closed / determined / settled / finalized 状态的 ticker 会被拒绝，并返回 EQL_INVALID_ARG_VALUE（“未找到或尚未开放”）。请先解析一个真实且当前开放的 ticker——切勿编造或猜测 ticker。生命周期条件仍适用于你已经关注的市场：在市场处于 active 状态时创建的计划，可在其后续进入 settled 状态（status）或得到结果（result / settlement_value）时，在 expiresIn 时间窗口内触发。

{
  "source": "kalshi",
  "method": "yes_price",
  "args": { "ticker": "KXBTC-26APR0803-T77799.99" },
  "operator": "crosses_below",
  "value": 0.4
}

完整的方法表、值枚举和自动化示例：预测市场 → Kalshi。

预测市场数据源（polymarket）：

根据 Polymarket 上实时的结果代币活动触发：最新成交价、最佳买价／卖价，以及最近一笔交易的数量和主动方。与 Kalshi 不同，Polymarket 仅提供价格和交易方法——没有市场生命周期（status / result）方法。

Ticker = 结果代币 asset_id。对于 Polymarket，args.ticker 是结果代币 asset_id——表示单个结果（例如 YES 代币）的长数字 ID，而非顶层 Polymarket 市场 ID（该 ID 由二元市场的双方共用）。创建时会根据 Polymarket 的实时市场验证代币；未知或非活跃的代币会被拒绝（“未找到或未激活”）。请先解析一个真实且当前活跃的结果代币 ID——切勿编造或猜测 ID。

每个方法恰好接受一个参数：ticker：

方法	返回值	描述
`price`	`[0, 1]` 范围内的数字	结果代币的最新成交概率／价格
`bid`	`[0, 1]` 范围内的数字	结果代币的最佳买价（事件中存在时）
`ask`	`[0, 1]` 范围内的数字	结果代币的最佳卖价（事件中存在时）
`size`	≥ 0 的数字	最新交易更新的数量（存在时）
`side`	枚举 `"BUY"` / `"SELL"`	最新交易的主动方，使用大写形式

数据流混合了多种事件子类型（price_change、best_bid_ask、last_trade_price、 book），且并非每个字段都会在每个事件中更新——best_bid_ask 仅更新 bid / ask，而 last_trade_price 仅更新 price / size / side。请围绕所需的特定字段设计条件，而不要假设所有字段会同步变化。

各方法支持的运算符（因方法而异）：

方法	允许的运算符
`price`、`bid`、`ask`	`>` `<` `>=` `<=` `==` `!=` `crosses_above` `crosses_below`
`size`	`>` `<` `>=` `<=` `==` `!=`
`side`	`==` `!=`

value 必须是与方法类型匹配的字面值（price / bid / ask 的范围为 0–1，size ≥ 0，side 使用大写 "BUY" / "SELL"）。Polymarket 条件不支持动态（字段与字段之间）取值——动态 Polymarket 目标会在验证时被拒绝。

{
  "source": "polymarket",
  "method": "price",
  "args": { "ticker": "115556263888245616435851357148058235707004733438163639091106356867234218207169" },
  "operator": "crosses_below",
  "value": 0.4
}

标准 EQL 限制同时适用于这两种预测市场数据源：可在 AND / OR 组内与其他数据源组合，最多 3 层深度和 10 个叶条件。完整的方法表和自动化示例：预测市场 → Polymarket。

市场结构数据源（funding）——永续合约资金费率： 根据永续合约的资金费率触发条件——多头偏向过热、费率转为负值，或不同交易平台之间出现背离。资金费率和清算流往往先于现货价格作出反应。

Ticker = 复合标识 SYMBOL:EXCHANGE（不是 symbol + exchange 参数）。SYMBOL 是基础资产（BTC，而非 BTCUSDT）；交易平台包含在 ticker 中。交易平台：binance、hyperliquid。示例：BTC:BINANCE、ETH:HYPERLIQUID。

Method	Args	Returns	Operators	Description
`annualized_rate`	`ticker`	number	all 8	标准方法。以年化百分比（APR）表示的资金费率：`32.85` = 32.85% APR。正值 = 多头向空头支付。
`interval_rate`	`ticker`	number	all 8	每个结算间隔的百分比。
`interval_hours`	`ticker`	number	level only	以小时为单位的结算间隔：`8`（Binance）或 `1`（Hyperliquid）。交易平台元数据。
`exchange`	`ticker`	enum	`==` / `!=`	交易平台：`"binance"` 或 `"hyperliquid"`。

优先使用 annualized_rate——Binance 每 8 小时结算一次，Hyperliquid 每 1 小时结算一次，因此相同的 interval_rate 阈值在不同交易平台上代表不同含义；年化处理可避免这一问题。“资金费率转为负值”对应的条件正是 annualized_rate crosses_below 0。
“level only” = > < >= <= == !=（不包括 crosses_*）。
HIP-3 DEX 前缀符号（xyz:TSLA）在此处不受支持（EQL_INVALID_ARG_VALUE，details.hip3: true）——资金费率数据源从不发布这些符号对应的键。

{ "source": "funding", "method": "annualized_rate", "args": { "ticker": "BTC:BINANCE" }, "operator": "crosses_below", "value": 0 }

市场结构数据源（liquidation）——清算流：

根据滚动时间窗口内的清算流触发条件——清算瀑布超过美元阈值、单向清洗，或清算额占未平仓合约的比例。与 funding 使用相同的复合 SYMBOL:EXCHANGE ticker。交易平台：binance、bybit、hyperliquid。

Method	Args	Returns	Operators	Description
`total_usd_1m` / `total_usd_5m` / `total_usd_1h`	`ticker`	number	all 8	滚动时间窗口内的清算美元总额。
`long_usd_1m` / `long_usd_5m` / `long_usd_1h`	`ticker`	number	all 8	多头清算额（被迫卖出）。
`short_usd_1m` / `short_usd_5m` / `short_usd_1h`	`ticker`	number	all 8	空头清算额（被迫买入）。
`largest_order_usd_1h`	`ticker`	number	all 8	滚动一小时内单笔最大清算订单的美元金额。
`count_1h`	`ticker`	number	level only	滚动一小时内的清算订单数量。
`total_pct_oi_1m` / `total_pct_oi_5m` / `total_pct_oi_1h`	`ticker`	number	all 8	时间窗口内的清算总额占未平仓合约的百分比（便于跨符号比较）。
`exchange`	`ticker`	enum	`==` / `!=`	交易平台：`"binance"` / `"bybit"` / `"hyperliquid"`。

不同交易平台的数据源质量有所不同。 Binance 使用抽样数据（每个符号每秒最多 1 笔清算），因此其数值是下限，会漏计大多数清算；你关心的清算瀑布期间尤其如此。Bybit 和 Hyperliquid 的数据则是完整的（总额精确）。对于同一现实事件，应为 Binance 设置更低的阈值。
清算瀑布平息后，时间窗口内的数值会逐渐归零，从而重新启用条件——因此，repeat 计划会在每次清算瀑布期间触发一次，而不是一生仅触发一次。
total_pct_oi_* 的数值较小：对于大型币种，每小时约 0.1% 已属高水平；起始阈值应设在 0.5–1（百分比），而非原始小数。HIP-3 符号在此处也不受支持。

{ "source": "liquidation", "method": "total_usd_5m", "args": { "ticker": "ETH:BYBIT" }, "operator": "crosses_above", "value": 500000 }

完整的方法表、数据源质量表和示例：资金费率与清算。

市场情绪数据源（fear_greed）——加密货币恐惧与贪婪指数：

根据全市场加密货币恐惧与贪婪指数触发条件。这是一个无需密钥的数据源——只有一个全局读数，没有单个市场的标识——因此其方法不接受 ticker。传入 args: {}。

方法	参数	返回值	运算符	描述
`value`	(无)	number	全部 8 种	指数分数，整数 `0`–`100`（0 = 极度恐惧，100 = 极度贪婪）。
`classification`	(无)	enum	`==` / `!=`	分类标签（见下文）。

classification 的值 ∈ "Extreme fear"（0–19）、"Fear"（20–39）、"Neutral" （40–59）、"Greed"（60–79）、"Extreme greed"（80–100）。各区间对应固定的 value 范围——要精确设置阈值，优先使用 value。
每隔约 15 分钟更新一次。crosses_* 叶节点需要之前的读数，因此只能在激活后的 第二次读取时触发。没有动态值。

{ "source": "fear_greed", "method": "value", "args": {}, "operator": "crosses_below", "value": 20 }

关注关系图数据源（x_follow_received、x_follow_made、x_follow_overlap）——新的 X 关注关系：

三个数据源针对同一组数据提出三个问题。你指定的账号始终是被监控的账号；方法描述关注关系另一端的账号。

数据源	方法	参数	返回值	运算符	衡量内容
`x_follow_received`	`follower_count`	`account`、`window?`、`period?`	number	`>` / `>=`	关注了被监控账号的账号的粉丝数。
`x_follow_made`	`followee_follower_count`	`account`、`window?`、`period?`	number	`>` / `>=`	被监控账号关注的账号的粉丝数。
`x_follow_overlap`	`distinct_followers`	`accounts`（2–25）、`window?`、`period?`	number	`>` / `>=`	有多少个被监控账号关注了同一个账号。

仅接受 > 和 >=——不支持 crosses_*，也不支持动态的字段间取值比较。账号必须是纯 X 用户名（1–15 个字母、数字或下划线）；开头的 @ 会被去除，路由时会转换为小写，accounts 中的重复项会合并为一项。

参数	值	默认值
`window`	`6h`、`12h`、`24h`、`48h`、`72h`、`7d`	`24h`（`x_follow_overlap` 为 `72h`）
`period`	`1h`、`2h`、`4h`、`8h`、`12h`、`24h`、`1d`、`7d`	`1h`

window 是回溯检测时间的范围；period 是读取之间的最短间隔。若 period 长于 window，系统会自动将其缩短至 window，而不会拒绝请求。

{ "source": "x_follow_received", "method": "follower_count", "args": { "account": "elfa_ai", "window": "24h" }, "operator": ">", "value": 10000 }

{ "source": "x_follow_overlap", "method": "distinct_followers", "args": { "accounts": ["pantheracapital", "a16z", "paradigm"], "window": "72h" }, "operator": ">=", "value": 2 }

对于 x_follow_received / x_follow_made，>= 0 会匹配所有检测到的关注关系，设定更高的值则会将范围缩小到拥有实际受众的账号。对于 x_follow_overlap，value 的下限为 2，且不能超过 accounts 的数量（使用 > 时，下限低 1）——若不符合，创建时会被拒绝。

覆盖范围有限，这些限制会影响计划的编写方式：系统只能看到 Elfa 已追踪账号的关注行为；数据按定期检查收集，而非实时流式获取，因此警报并非实时；每次评估最多会纳入 500 个匹配项；取消关注和重新关注都不会触发警报。计划没有触发，表示没有受追踪账号进行了该关注操作——并不能证明没有人关注。x_follow_made 和 x_follow_overlap 会读取被监控账号自己的关注列表，因此这些账号本身必须是 Elfa 监控的账号；x_follow_received 则没有此要求。

每个匹配账号都是一个独立事件：不使用 repeat 时，首次匹配会触发计划一次；使用 repeat 时，每个不同的匹配账号都会触发一次（要“每个都通知我”，请将 cooldown: "0"）。匹配账号在仍处于 window 范围内时不会再次触发；关注条件在首次定时评估之前不会返回任何值，因此执行前无法预览。Builder Chat 目前还不能编写这些条件；请直接通过 Validate/Create 创建。使用这些数据源前，请阅读关注关系图。

支持的运算符： >、<、>=、<=、==、!=、crosses_above、crosses_below

动态比较： value 可以引用另一个实时数据源，而不是字面值：

{
  "source": "price",
  "method": "current",
  "args": { "symbol": "ETH", "exchange": "hyperliquid" },
  "operator": "crosses_above",
  "value": {
    "source": "ta",
    "method": "bbands_upper",
    "args": { "symbol": "ETH", "timeframe": "4h", "exchange": "hyperliquid" }
  }
}

可直接复制粘贴的查询模板

1）突破提醒（webhook）：

{
  "title": "BTC breakout above 100k",
  "description": "Notify runner when BTC spot trades above the 100k level.",
  "conditions": { "AND": [{ "source": "price", "method": "current", "args": { "symbol": "BTC", "exchange": "hyperliquid" }, "operator": ">", "value": 100000 }] },
  "actions": [{ "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-endpoint.example/events" } }],
  "expiresIn": "24h"
}

2）下行保护（telegram_bot）：

{
  "title": "ETH downside guardrail (< 2500)",
  "description": "Risk-off alert: flag if ETH breaks below 2500. The notification body is auto-composed from title + description + trigger context.",
  "conditions": { "AND": [{ "source": "price", "method": "current", "args": { "symbol": "ETH", "exchange": "hyperliquid" }, "operator": "<", "value": 2500 }] },
  "actions": [{ "stepId": "step_1", "type": "telegram_bot", "params": { "botToken": "<TELEGRAM_BOT_TOKEN>", "chatId": "<TELEGRAM_CHAT_ID>" } }],
  "expiresIn": "24h"
}

3）触发式 LLM 分析：

{
  "title": "BTC > 100k — LLM review",
  "description": "On BTC breakout, run an LLM pass to decide the next follow-up action.",
  "conditions": { "AND": [{ "source": "price", "method": "current", "args": { "symbol": "BTC", "exchange": "hyperliquid" }, "operator": ">", "value": 100000 }] },
  "actions": [{
    "stepId": "step_1",
    "type": "llm",
    "params": { "action": "chat", "message": "Analyze trigger context and return the next follow-up action." }
  }],
  "expiresIn": "24h"
}

4）多标的确认：

{
  "title": "BTC + ETH joint breakout",
  "description": "Confirm majors moving together before acting.",
  "conditions": {
    "AND": [
      { "source": "price", "method": "current", "args": { "symbol": "BTC", "exchange": "hyperliquid" }, "operator": ">", "value": 100000 },
      { "source": "price", "method": "current", "args": { "symbol": "ETH", "exchange": "hyperliquid" }, "operator": ">", "value": 3500 }
    ]
  },
  "actions": [{ "stepId": "step_1", "type": "notify", "params": { "message": "BTC and ETH confirmation fired" } }],
  "expiresIn": "24h"
}

5）动态比较（价格与布林带）：

{
  "title": "ETH breakout above 4h upper BBand",
  "description": "Dynamic: fire when ETH price crosses above its own 4h upper Bollinger Band.",
  "conditions": {
    "AND": [{
      "source": "price", "method": "current", "args": { "symbol": "ETH", "exchange": "hyperliquid" },
      "operator": "crosses_above",
      "value": { "source": "ta", "method": "bbands_upper", "args": { "symbol": "ETH", "timeframe": "4h", "exchange": "hyperliquid" } }
    }]
  },
  "actions": [{ "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-endpoint.example/events" } }],
  "expiresIn": "2d"
}

6）定时 cron 检查：

{
  "title": "Every 4h: portfolio sweep",
  "description": "Recurring LLM pass every 4h.",
  "conditions": { "AND": [{ "source": "cron", "method": "every", "args": { "period": "4h" }, "operator": "==", "value": true }] },
  "actions": [{
    "stepId": "step_1",
    "type": "llm",
    "params": { "action": "chat", "message": "Summarize BTC/ETH/SOL context and flag any risk shifts." }
  }],
  "expiresIn": "3d"
}

7）由 LLM 评估的叙述条件：

{
  "title": "AI narrative shift watcher",
  "description": "Fire when dominant AI-token narrative shifts based on news + X sentiment.",
  "conditions": {
    "AND": [{
      "source": "llm", "method": "athena_condition",
      "args": { "query": "Has the dominant narrative around AI-sector tokens shifted materially in the last 6 hours?", "period": "1h" },
      "operator": "==", "value": true
    }]
  },
  "actions": [{ "stepId": "step_1", "type": "telegram_bot", "params": { "botToken": "<TELEGRAM_BOT_TOKEN>", "chatId": "<TELEGRAM_CHAT_ID>" } }],
  "expiresIn": "2d"
}

8）信号 — X/Twitter 帖文（以账号为锚点）：

{
  "title": "Binance Alpha listing post watcher",
  "description": "Fire when cz_binance posts that Binance Alpha is listing a new token so the runner can review follow-through.",
  "conditions": {
    "AND": [{
      "source": "tweet",
      "args": {
        "username": "cz_binance",
        "text": "Binance Alpha is listing a new token",
        "minConfidence": 80
      }
    }]
  },
  "actions": [{ "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-runner.example/auto/events" } }],
  "expiresIn": "24h"
}

9）事件（新闻驱动的催化因素）：

{
  "title": "ETH ETF approval event watcher",
  "description": "Fire when an event reports a spot ETH ETF approval so I can kick off a post-event playbook.",
  "conditions": {
    "AND": [{
      "source": "events",
      "args": {
        "entity": "ETH",
        "eventType": "regulatory",
        "text": "the SEC approves a spot ETH ETF",
        "minConfidence": 80
      }
    }]
  },
  "actions": [{ "stepId": "step_1", "type": "notify", "params": { "message": "Event fired: spot ETH ETF approval" } }],
  "expiresIn": "168h"
}

10）预测市场 — Kalshi（YES 概率越线）：

{
  "title": "Kalshi YES crosses 60%",
  "description": "Fire when the market's implied YES probability crosses up through 60%, signalling the market now expects this outcome.",
  "conditions": { "AND": [{ "source": "kalshi", "method": "yes_price", "args": { "ticker": "KXBTC-26APR0803-T77799.99" }, "operator": "crosses_above", "value": 0.6 }] },
  "actions": [{ "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-runner.example/auto/events" } }],
  "expiresIn": "48h"
}

11）预测市场 — Kalshi（通过 LLM 汇总结算情况）：

{
  "title": "Kalshi market resolved YES — recap",
  "description": "When the market settles with a YES result, generate a concise recap of what happened and why.",
  "conditions": { "AND": [{ "source": "kalshi", "method": "result", "args": { "ticker": "KXBTC-26APR0803-T77799.99" }, "operator": "==", "value": "yes" }] },
  "actions": [{ "stepId": "step_1", "type": "llm", "params": { "action": "chat", "message": "This Kalshi market just resolved YES. Write a concise recap explaining what resolved and what to watch next." } }],
  "expiresIn": "48h"
}

12）预测市场 — Polymarket（结果代币价格越线）：

{
  "title": "Polymarket outcome crosses 60%",
  "description": "Fire when the outcome token's last traded price crosses up through 0.60, signalling the market now expects this outcome.",
  "conditions": { "AND": [{ "source": "polymarket", "method": "price", "args": { "ticker": "115556263888245616435851357148058235707004733438163639091106356867234218207169" }, "operator": "crosses_above", "value": 0.6 }] },
  "actions": [{ "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-runner.example/auto/events" } }],
  "expiresIn": "48h"
}

13）重复触发器（repeat）：

根据计划自身的条件重新触发，而非按固定的 cron 频率执行 — 每当 BTC 向下穿越 60k 时通知一次，每小时最多通知一次，最多触发 10 次。请注意更安全的模式选择：crosses_below（对穿越临界点的动作作出响应，而不是对持续低于该点的数值作出响应），再加上 1h 冷却时间和较低的 maxTriggers 上限。

{
  "title": "Notify when BTC crosses below 60k",
  "description": "Recurring risk alert: fire each time BTC price crosses down through 60000, no more than once per hour, up to 10 times.",
  "conditions": { "AND": [{ "source": "price", "method": "current", "args": { "symbol": "BTC", "exchange": "hyperliquid" }, "operator": "crosses_below", "value": 60000 }] },
  "actions": [{ "stepId": "step_1", "type": "notify", "params": { "message": "BTC dipped below 60k again" } }],
  "expiresIn": "7d",
  "repeat": { "cooldown": "1h", "maxTriggers": 10 }
}

14）日历计划（cron.schedule）：

按墙上时钟计划运行 — 每个工作日纽约时间 09:00 执行。仅支持直接 EQL/API 路径（Builder Chat 支持即将推出）。

{
  "title": "Weekday 9am NY: market open recap",
  "description": "Every weekday at 09:00 America/New_York, run an LLM market-open recap.",
  "conditions": { "AND": [{ "source": "cron", "method": "schedule", "args": { "expression": "0 9 * * 1-5", "timezone": "America/New_York" }, "operator": "==", "value": true }] },
  "actions": [{ "stepId": "step_1", "type": "llm", "params": { "action": "chat", "message": "Give a concise market-open recap for BTC/ETH/SOL and flag overnight risk shifts." } }],
  "expiresIn": "7d"
}

15）资金费率转负（funding）：

当 Binance BTC 资金费率转为负值时触发 — 空头开始向多头支付资金费（空头拥挤信号）。请注意复合形式的 SYMBOL:EXCHANGE 代码，以及可跨平台比较的 annualized_rate。

{
  "title": "BTC funding flips negative",
  "description": "Shorts are now paying longs on Binance BTC — a crowded-short signal worth reviewing.",
  "conditions": { "AND": [{ "source": "funding", "method": "annualized_rate", "args": { "ticker": "BTC:BINANCE" }, "operator": "crosses_below", "value": 0 }] },
  "actions": [{ "stepId": "step_1", "type": "notify", "params": { "message": "BTC funding on Binance flipped negative" } }],
  "expiresIn": "7d"
}

16）清算级联（liquidation + repeat）：

每当 ETH 在 5 分钟窗口内的清算额超过 $500k 时触发。级联消退后，窗口值会衰减至零，因此使用 repeat 时会每次级联触发一次。

{
  "title": "ETH liquidation cascade (5m > $500k)",
  "description": "Alert on each distinct ETH liquidation cascade on Bybit, capped at 10 alerts.",
  "conditions": { "AND": [{ "source": "liquidation", "method": "total_usd_5m", "args": { "ticker": "ETH:BYBIT" }, "operator": "crosses_above", "value": 500000 }] },
  "actions": [{ "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-runner.example/auto/events" } }],
  "expiresIn": "7d",
  "repeat": { "cooldown": "1h", "maxTriggers": 10 }
}

17）催化因素 → 股票/指数提醒（HIP-3）：

预测市场到永续合约的桥接：当美联储决策市场重新定价时，向你的运行器发送 S&P 永续合约提醒 — 包括隔夜和周末现金股票市场休市期间。xyz:SP500 是 Hyperliquid 上的 HIP-3 市场。请先解析一个真实开放的 Kalshi 代码 — 不要猜测。

{
  "title": "Fed cut odds → S&P alert",
  "description": "When the market prices a cut as more likely than not, notify my runner to review the S&P perp.",
  "conditions": { "AND": [{ "source": "kalshi", "method": "yes_price", "args": { "ticker": "<an open Kalshi Fed-decision market ticker>" }, "operator": "crosses_above", "value": 0.6 }] },
  "actions": [{ "stepId": "step_1", "type": "webhook", "params": { "url": "https://your-runner.example/auto/events" } }],
  "expiresIn": "168h",
  "repeat": { "cooldown": "4h", "maxTriggers": 3 }
}

轮询响应格式

所有查询和执行标识符都是 UUID（例如 a12d20ff-6cb2-433e-afed-cc2e6a0380b6），而不是 q_123 或 exec_123 这类带前缀的字符串。本技能其他位置使用的简短 q_123 形式仅是为了便于阅读的占位符；切勿自行构造带前缀的 ID，也不要按此前缀进行匹配。

GET /v2/auto/queries/{queryId}（以及对应的 x402 POST 请求）会返回 queryId、status、可选的 credits、latestEvaluation（当前状态）和 executions（实际触发的内容）。如果查询失败且记录了原因，还会包含 failure（含 code、message，其值可能为 null，以及 source）；source: "billing" 表示每条帖子对应的 X 账号费用被拒付，请充值、升级或提高限额，然后重新创建计划。

区分这两个运行时界面——这是轮询中最常见的错误：

界面	解答的问题	读取此字段以获取值
`latestEvaluation.conditionStates[]`	“当前什么为真”	`currentValue` 与 `targetValue`
执行记录中的 Auto Trigger Context	“触发了什么，以及为什么”	`trigger.matchedConditions[].match.observedValue`

latestEvaluation 在查询至少评估一次之前为 null：

{
  "evaluatedAt": "2026-04-01T12:00:00.000Z",
  "conditionStates": [
    {
      "index": 0,
      "source": "price",
      "method": "current",
      "args": { "symbol": "BTC" },
      "currentValue": 97250.5,
      "targetValue": 100000,
      "operator": "<",
      "isMet": true,
      "lastUpdated": "2026-04-01T12:00:00.000Z"
    }
  ],
  "wouldTriggerNow": true,
  "matchingConditions": 1,
  "totalConditions": 1
}

conditionStates[] 条目还可能包含 reason；对于 llm 条件，还可能包含 conversationSessionId、runId 和 cacheHit。使用 matchingConditions / totalConditions 展示部分进度（“3 个条件中满足 2 个”），无需自行重新计算。

查询触发后，执行记录中会出现 Auto Trigger Context。它是说明查询为何触发的稳定公开表示——原始存储的触发载荷不属于公开 API，因此请勿依赖它们。

{
  "id": "a12d20ff-6cb2-433e-afed-cc2e6a0380b6",
  "queryId": "76e2e824-fc47-4d60-99b1-c227fbd2d3f5",
  "type": "notification",
  "status": "success",
  "details": { "notification": { "channel": "webhook" } },
  "triggerTime": "2026-04-01T12:00:00.000Z",
  "conditionsMet": 1,
  "trigger": {
    "type": "price",
    "time": "2026-04-01T12:00:00.000Z",
    "matchedConditions": [
      {
        "condition": {
          "source": "price",
          "method": "current",
          "args": { "symbol": "BTC" },
          "operator": "<",
          "value": 100000
        },
        "match": { "observedValue": 97250.5 }
      }
    ]
  },
  "createdAt": "2026-04-01T12:00:01.000Z"
}

trigger.matchedConditions[].condition.value 是阈值； .match.observedValue 是触发时观察到的值。向用户解释触发原因时，请同时报告两者。
对于 Signal 来源（tweet / telegram），match 还包含来源信息——url、 mentionedAt、confidence、accountHandle；对于 Telegram，还包括 chatUsername、chatTitle、messageId / messageIds、groupId。使用 url 直接链接到触发计划的帖子。
对于 events，match 中包含的是事件本身，包括 eventId（其 /v3/events ID，而非投递 ID）、title、其分类、entities、analyzedAt，以及在检查 text 时的 confidence；此处没有 url。使用 GET /v3/events?eventIds=<eventId> 获取其余信息。
details 按操作类型分类（trade、notification、llm、auto、script）。
执行失败时会包含 error { code, message }，例如 LLM_ACTION_UPSTREAM_ERROR。

Auto Trigger Context 也包含在出站投递载荷和脚本触发上下文中，因此 webhook 接收方无需再次轮询即可解释触发原因。

调试或补录数据时使用轮询。生产环境投递则优先使用 webhook 或 SSE 通知。保存执行记录中的 sessionId 值，以便仅在需要时通过 GET /v2/auto/queries/:queryId/sessions/:sessionId 获取完整的 LLM 分析——例如，当带有 includeAnalysis 的回调 webhook 报告 analysisTruncated: true 时。

通知 — 投递渠道

查询触发后，Auto 会通过以下三个渠道之一投递事件：

渠道	适用场景	设置
Webhook	生产环境中的 Agent 自动化	`action.type = "webhook"`，并进行签名验证 + 队列/工作进程处理
Telegram	快速、易读的人工告警	`action.type = "telegram_bot"`，并设置 `params.botToken` + `params.chatId`（直接发送）；也可以通过 webhook→bot 中继实现自定义格式
SSE Stream	实时事件消费者；无论选择哪种操作，始终可用	两种流均免费，均使用 `GET`，并且使用与创建查询相同的身份验证方式：`GET /v2/auto/queries/stream`（账户范围——一条连接接收每个查询的事件，默认方式，仅限 API 密钥），或 `GET /v2/auto/queries/{queryId}/stream`（单个查询；x402 / Agent 身份选项）。参见 SSE 帧格式。

通知中的查询 title 和 description： 这两个字段会嵌入每条外发通知（Telegram、webhook、SSE）。接收者通常会在查询设置好几小时或几天后才看到告警——这两个字段能清楚说明触发了什么以及设置查询的原因。请务必设置。

通知负载（Auto 实际发送的内容）

Auto 发出的 webhook 通知对象具有以下结构：

{
  "id": 12345,
  "type": "athena_query_notify_only",
  "category": "alerts",
  "title": "BTC breakout above 100k",
  "body": "price > threshold",
  "data": { "queryId": "q_123" },
  "priority": "high",
  "createdAt": "2026-04-01T12:00:00.000Z"
}

id 是数字通知 ID；可通过 data.queryId 关联到查询。title 和 body 来自查询的 title / description 以及触发上下文。SSE 投递使用不同且更精简的帧——参见下文的 SSE 帧格式。

规范事件负载约定（内部规范化）

将传入事件（webhook、Telegram 中继、SSE）规范化为统一的内部结构很有用，这样下游处理就无需依赖渠道。以下是推荐的运行器端约定，并非 Auto 发送的线级格式（参见上面的负载）：

{
  "version": "1.0",
  "eventType": "query.triggered",
  "eventId": "evt_01J...",
  "timestamp": "2026-04-01T12:00:00.000Z",
  "queryId": "q_123",
  "channel": "webhook",
  "trigger": {
    "symbol": "BTC",
    "reason": "price > threshold"
  },
  "evaluation": { "triggered": true },
  "action": { "type": "webhook" }
}

Webhook 请求标头（接收方必须读取的内容）：

标头	用途
`X-Auto-Event-Id`	用于去重的唯一事件 ID
`X-Auto-Signature-Timestamp`	用于重放时间窗口检查的 Unix 秒数
`X-Auto-Signature`	`v1=<hex_hmac_sha256>` — 根据原始请求体进行验证

SSE 帧格式

有两个 SSE 流；两者均免费，均为 GET，且均使用创建查询时所用的相同身份验证方式（API 密钥查询使用 x-elfa-api-key，x402 查询使用 x402 密钥——并非仅限于 x-elfa-api-key）。如需最简配置，请附加一个带有 message 的 notify 操作——这些通知只能通过 SSE 或轮询获取。

端点	范围	使用场景
`GET /v2/auto/queries/stream`	通过一个连接获取你拥有的所有查询	默认选项。通过载荷中的 `queryId` 关联事件。仅限 API 密钥——Agent 身份（`x-elfa-agent-secret`）和 x402 会收到 `403`。
`GET /v2/auto/queries/{queryId}/stream`	单个查询	你只关心一个查询，或使用 x402／Agent 身份时。

优先使用账户级流，而不是为每个查询各开一个连接。创建至少一个查询后再打开流——如果没有查询，流会返回 410。

两个流都会发送相同的帧——event: notification，id 为通知发件箱事件 UUID（不是查询 ID），并且每隔 15 秒发送一条 : keep-alive 注释。事件仅实时发送：不会重放，且会忽略 Last-Event-ID。

id: 9df34377-4d82-4b3c-a016-b0ba27556aa1
event: notification
data: {"status":"triggered","title":"Plan Triggered","body":"BTC RSI Breakout","queryId":"q_123","executionId":"2dbf0d70-a85f-4f67-9bd3-876e8fd89f86","triggerTime":"2026-04-01T12:00:00.000Z","conditionsMet":2,"timestamp":1774328400000}

status 的值为 triggered、stopped、ended 或 update。queryId 是载荷中的顶层字段——使用它通过 /v2/auto/queries/{queryId} 将事件与轮询结果关联起来。载荷还会在适用时包含执行上下文（executionId、triggerTime、conditionsMet、autoDetails）。

**流生命周期。**当没有剩余内容可发送时，每个流都会关闭，并发送最终的 end 事件：

	`/queries/stream`	`/queries/{queryId}/stream`
连接时返回 `410`	你没有活动查询	查询已处于终态，且通知已全部发送
关闭条件	没有活动查询且没有待处理执行，并持续 30 秒	查询达到终态，且其通知已全部发送
最终帧	`data: {"code":"USER_STREAM_CLOSED"}`	`data: {"code":"QUERY_STREAM_CLOSED","status":"<terminalStatus>","queryId":"<uuid>"}`

recurring（repeat）查询永远不会进入终态，因此其流会在多次触发期间保持打开。如果流在启动后发生故障，会发送包含 {"code":"STREAM_UNAVAILABLE"} 的 event: error。

Telegram 中继任务格式（将 Webhook 转换为 Telegram Bot API 时）：

{
  "eventId": "evt_01J...",
  "queryId": "q_123",
  "channel": "telegram",
  "chatId": "<CHAT_ID>",
  "text": "BTC trigger fired: price > threshold",
  "priority": "high"
}

Webhook 签名验证

为每个生产环境 Webhook 明确设置 signingSecret。 它是 webhook 操作的参数，仅可写——Elfa 会将其存储用于传送签名，且不会在查询、执行、Webhook、SSE 或 LLM 回调载荷中返回它。如果不设置，根据访问模式和服务配置，签名标头可能完全缺失，因此要求签名的接收方会拒绝所有传送。

{
  "stepId": "step_1",
  "type": "webhook",
  "params": {
    "url": "https://your-runner.example/auto/events",
    "signingSecret": "<openssl rand -hex 32>",
    "allNotifications": true
  }
}

LLM 回调 Webhook 使用相同的目标参数，路径为 params.callback.action.params，并额外包含 includeAnalysis（默认为 false）。如果不设置，回调只会告知你的端点查询已触发，而不会告知 llm 步骤写入了什么。将其设为 true 后，载荷还会包含作为 analysisText 的答案（最多 32,000 个字符）以及 analysisTruncated。Validate 会拒绝顶层 webhook 上的 includeAnalysis，且 telegram_bot 回调永远不会携带答案。请参阅回调 Webhook 中的 LLM 分析。

应使用哪个密钥——两个不同的密钥，切勿混用：

密钥	方向	用途
`x-elfa-api-key`	你 → Elfa	验证你的客户端身份
`webhook.params.signingSecret`	Elfa → 你	为 Elfa 向你的服务发送的出站 Webhook 传送签名

为每个 Webhook 操作生成一个独立的高熵密钥（openssl rand -hex 32）。不要在这里复用 API 密钥或 x402 Agent 密钥。

签名输入：

expected = HMAC_SHA256(signingSecret, timestamp + "." + eventId + "." + rawBody)

signingSecret 直接用作 HMAC 密钥——不要先对它进行哈希处理。 此技能的早期版本曾说明使用 HMAC_SHA256(SHA256(secret), ...)。对于显式签名密钥，这是错误的，会导致验证失败。

旧版 x402/Agent 回退方式： 如果 x402/Agent Webhook 未设置 signingSecret，较早的传送可能会使用 SHA256(x-elfa-agent-secret) 作为密钥进行签名。请将此方式视为旧版回退方案，而非受支持的配置——请改为设置显式的 signingSecret。

Node.js 验证：

import crypto from "crypto";

export function verifyAutoWebhook(
  signingSecret: string,
  rawBody: string,
  signatureHeader: string,
  timestamp: string,
  eventId: string,
): boolean {
  if (!signatureHeader?.startsWith("v1=")) return false;
  const givenHex = signatureHeader.slice(3);
  if (!/^[0-9a-f]{64}$/i.test(givenHex)) return false;

  const payload = `${timestamp}.${eventId}.${rawBody}`;
  const expectedHex = crypto
    .createHmac("sha256", signingSecret)
    .update(payload)
    .digest("hex");

  const given = Buffer.from(givenHex, "hex");
  const expected = Buffer.from(expectedHex, "hex");
  if (given.length !== expected.length) return false;
  return crypto.timingSafeEqual(given, expected);
}

操作检查清单：

对 X-Auto-Signature-Timestamp 实施有界重放窗口（时间偏差超过 30s 时拒绝）。
在持久化存储中按 X-Auto-Event-Id 去重。
快速返回 2xx，然后异步处理（队列 + 工作进程）。

Telegram 机器人设置（用于 `action.type: "telegram_bot"` 或中继）

在 Telegram 中打开 @BotFather → /newbot → 保存机器人令牌（视为机密）。
向机器人发送任意消息（或在机器人所在的群组中发送）。
curl "https://api.telegram.org/bot<BOT_TOKEN>/getUpdates" → 读取 message.chat.id。
通过以下方式发送消息：

curl -X POST "https://api.telegram.org/bot<BOT_TOKEN>/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": "<CHAT_ID>", "text": "Auto trigger fired for BTC RSI"}'

私聊、群组和超级群组： telegram_bot 可向私聊、群组和超级群组发送消息。不支持频道，创建时会拒绝。群组有两个注意事项：(1) 群组聊天 ID 为负数（-1001234567890）——请从 getUpdates 原样复制，包括前导 -；(2) 机器人必须有权发帖——创建时，Auto 会检查机器人的成员身份和权限；如果机器人无法发帖，创建将失败，并显示 Telegram bot cannot send messages in this chat (check its permissions)。如果群组之后升级为超级群组（聊天 ID 会改变），Auto 会检测到迁移、更新已存储的 ID 并重试——无需执行任何操作。

Agent 运行器——参考架构

Auto 负责处理查询评估和事件发出。你的运行器负责事件接收、验证、去重、策略续行和审计日志记录。

Auto Query
  → Auto Event Ingress (Webhook / SSE)
  → Signature Verification + Idempotency
  → Job Queue
  → Agent Decision Worker
  → Action Adapter (Telegram / Internal API / Order Router)
  → Logs + Metrics + Alerts

核心处理循环：

接收事件（Webhook 或 SSE 帧）。
验证签名（仅限 Webhook）。
检查幂等性——是否已处理过 eventId？
将任务加入队列，并快速返回 2xx 确认。
工作线程解析额外上下文（轮询查询、获取 LLM 会话）。
应用策略，决定下一步操作。
执行下游操作。
记录结果，以便重放或调试。

指令信封——从入口传递给工作线程的结构化契约：

{
  "eventId": "evt_123",
  "queryId": "q_123",
  "objective": "Handle trigger and decide next action",
  "allowedActions": ["notify", "fetch_session", "execute_adapter"],
  "constraints": {
    "maxExecutionSeconds": 30,
    "riskMode": "conservative"
  }
}

最简 TypeScript 工作线程骨架：

type AutoJob = { eventId: string; queryId: string; raw: unknown };
const queue: AutoJob[] = [];
const processed = new Set<string>();

function onWebhook(eventId: string, queryId: string, raw: unknown) {
  if (processed.has(eventId)) return; // idempotent
  queue.push({ eventId, queryId, raw });
}

async function workerLoop() {
  while (true) {
    const job = queue.shift();
    if (!job) { await new Promise((r) => setTimeout(r, 250)); continue; }
    // 1) Pull latest query/execution state if needed
    // 2) Fetch session details for llm actions
    // 3) Decide next action (policy + agent logic)
    // 4) Execute action (notify, relay, order adapter)
    processed.add(job.eventId);
  }
}

部署模式：

模式	适用场景
单进程（API + 工作线程）	早期原型
API + 队列 + 工作线程	大规模生产环境中的可靠性
无服务器消费者 + 队列工作线程	工作负载波动较大且使用托管运维的场景

本地（Docker Compose）堆栈：

version: "3.9"
services:
  redis: { image: redis:7-alpine, ports: ["6379:6379"] }
  ingress:
    build: ./ingress
    environment:
      AUTO_SECRET: ${AUTO_SECRET}
      REDIS_URL: redis://redis:6379
    depends_on: [redis]
    ports: ["3000:3000"]
  worker:
    build: ./worker
    environment:
      AUTO_SECRET: ${AUTO_SECRET}
      REDIS_URL: redis://redis:6379
      ELFA_BASE_URL: https://api.elfa.ai/v2/auto
    depends_on: [redis]

最简环境契约（本地和云端使用相同的键）：

AUTO_SECRET=<event-signing secret>
ELFA_BASE_URL=https://api.elfa.ai/v2/auto
QUEUE_URL=<redis/sqs/pubsub endpoint>
RUNNER_MODE=local|cloud

可靠性检查清单：

在持久存储中按 eventId 存储去重键
设置重试策略和死信队列
保持 Webhook 处理程序快速且非阻塞
记录每次运行的决策输入和输出
设置运行状况检查，并在工作线程延迟时发出警报

各阶段的建议配置：

阶段	模式
原型	Auto Telegram + 本地工作线程
生产环境	Auto Webhook + 队列 + 工作线程
实时运维	Auto SSE + 工作线程服务

完整详情：通知 | Agent 运行器

通知故障排除

症状	可能原因	修复方法
轮询或流式传输时出现 `400` / `401`	缺少或无效的 API 密钥或身份验证标头	发送 `x-elfa-api-key`
Webhook 签名不匹配	对错误的载荷签名（未使用原始请求正文），或使用前先对密钥进行哈希处理	密钥必须是原始 `signingSecret`，载荷为 `timestamp + "." + eventId + "." + rawBody`。不要使用 `SHA256(secret)` 作为密钥
Webhook 投递时没有签名标头	Webhook 操作未明确设置 `signingSecret`	设置 `params.signingSecret` 并重新创建查询
下游操作重复	事件处理没有幂等性	在加入队列或执行前按 `eventId` 去重
已收到事件，但 Agent 没有任何操作	入口内联处理导致超时	快速返回确认，将事件推送到队列，并在工作线程中处理
SSE 断开并反复重连	没有重试/退避机制，或消费者不稳定	添加重连退避机制和心跳监控
一段时间后缺少触发	查询已过期或已取消	轮询状态；检查 `expiresIn`、`status`、`latestEvaluation`
“为什么还没有触发？”	条件接近满足，但尚未满足	查看 `latestEvaluation.conditionStates[]`——比较 `currentValue` 和 `targetValue`，以及 `matchingConditions` 和 `totalConditions`。不要根据执行记录推断
“为什么触发了？”	需要的是触发时的值，而不是当前值	查看该执行记录的 `trigger.matchedConditions[]`——比较 `.match.observedValue` 和 `.condition.value`。`latestEvaluation` 的值此后已发生变化
签名时间戳被拒绝	运行器时钟偏差	同步时钟（NTP）；限制重放时间窗口
创建时出现 `Telegram bot cannot send messages in this chat`	机器人不在群组中，或群组撤销了该机器人的 `can_send_messages` 权限	将机器人添加到聊天，并授予发送权限（或将其设为管理员），然后重试
创建 Telegram 时群组失败	`chatId` 缺少前导 `-`，或目标是频道	群组 ID 为负数（`-1001234567890`）；不支持频道

验证错误——后续操作表

当 /v2/auto/queries/validate（或 Create）拒绝请求时，问题几乎总是表述方式，而非能力不足。请继续迭代 Validate，而不是放弃该查询。

错误信号	含义	后续操作
`EQL_MISSING_ARG`	缺少必需参数（例如 `ema`/`sma` 的 `period`，或任何 `price`/`ta` 条件的 `exchange`）	根据 TA Args Contract 添加缺失参数，然后重新验证
`price`/`ta` 缺少或无效的 `exchange`	每个 `price`/`ta` 条件都需要 `exchange`	在条件的 `args` 中添加 `exchange`（`hyperliquid` 或 `binance`），然后重新验证
`EQL_INVALID_ARG` / 类型错误	类型错误（用 `"14"` 而不是 `14`），或键名无法识别（`length` 而不是 `period`）	使用准确的键名和 JSON 数值类型
未知 `method`	不支持此指标名称	选择最接近的受支持方法；请 Builder Chat 替换
不支持的 `timeframe` / `period`	值不在枚举范围内	调整为最接近的允许值
不支持的 `symbol` / 来源	资产未编入索引，或不支持该 DEX 交易对	跳过该 `symbol` 并报告；继续处理受支持的子集
超出深度 / 叶节点数量限制	深度超过 3 或叶节点超过 10 个	拆分为两个查询，并由你的运行器连接
`cron` / `llm` 周期过短	低于 1h 最低要求	提高到 `1h` 或更长
`tweet` 用户名，`details.reason: paid_plan_required`	该密钥没有付费 API 计划，且此账号不在 Elfa 的实时账号列表中（如果此类密钥下的账号拼写错误，也会出现此情况）	检查拼写；使用付费 API 密钥，或选择 `included` 账号
`tweet` 用户名，`details.reason: not_found`	没有 X 账号使用该用户名，或该值不是用户名	检查拼写并传入纯用户名（不带 `@`）
`tweet` 用户名，`details.reason: protected`	该账号受保护	选择公开账号
`tweet` 用户名，`details.reason: capacity_reached`	每帖账号池已满	稍后重试，或选择 `included` 账号
x402 上的 `tweet` 用户名，`EQL_INVALID_ARG_TYPE`	x402 仅监控实时账号列表中的账号	选择其他账号，或使用付费 API 密钥
`503` `ERR_SERVICE_UNAVAILABLE`，`error.message: ACCOUNT_LOOKUP_UNAVAILABLE`	X 账号查询失败；该账号可能确实存在	几秒后重试
无效的 `minConfidence`（`tweet` / `telegram` / `events`）	不是整数，或不在 `0..100` 范围内	使用 `0` 到 `100` 之间的 JSON 整数（可从 `80` 开始）
`events` 的 `entity` 未知 / 有歧义	没有匹配的实体，或多个实体的匹配度相同（`details.candidates`）	设置 `entityType`，将候选项的 `publishedId` 作为 `entity` 传入，或移除 `entity` 并使用 `eventType` + `text`
`events` 未设置筛选条件且没有 `text`，或 `text`/`minConfidence`/`entityType` 未成对使用	至少需要一个筛选条件或 `text`；`text` 和 `minConfidence` 必须同时使用；`entityType` 只能与 `entity` 一起使用	添加筛选条件，或配对使用参数
无法解析的 `telegram` 频道	`chatUsername` / `chatId` 无法解析为受监控的公开频道，或简写形式同时带有两个标识符	简写形式只使用一个标识符，移除 `@` 和 `t.me/`，并选择受监控的公开频道
无效的 `sec` CIK	`args.ticker` 不是 1–10 位数字，或 CIK 不在 SEC submissions 元数据中	传入发行人的 CIK（而非股票代码），然后重新验证
`EQL_INVALID_ACTION`	查询或草稿在顶层或 `llm` 回调中使用了 `market_order` / `limit_order`	替换为 `webhook`、`notify`、`telegram_bot` 或 `llm`，并在你自己的运行器中执行
`kalshi` 代码未开放（`args.ticker` 上的 `EQL_INVALID_ARG_VALUE`）	代码不是当前开放的 Kalshi 市场（已关闭 / 已结算 / 未知）	查找当前开放的完整代码并重新验证；不要猜测代码
`kalshi` 枚举 / 运算符无效	枚举 `value` 超出范围，或运算符不在该方法的允许列表中（例如在 `trade_size` 上使用 `crosses_above`）	使用 `kalshi` 来源参考中的各方法运算符允许列表和枚举集合
`kalshi` `is_block_trade` 类型错误	`value` 以字符串而非 JSON 布尔值传入	使用 JSON `true` / `false`，不要使用 `"true"` / `"false"`
未找到 / 未激活 `polymarket` 代码	`args.ticker` 不是有效的 Polymarket 结果代币（`asset_id`）——未知或未激活	查找当前激活的结果代币 `asset_id` 并重新验证；不要猜测 ID
`polymarket` 运算符 / 动态值无效	运算符不在该方法的允许列表中（例如在 `size` 上使用 `crosses_above`，在 `side` 上使用 `>`），或使用了动态（字段对字段）`value`	使用各方法的运算符允许列表；使用字面量 `value`（`polymarket` 不支持动态值）
`cron.schedule` 执行频率过快	分钟字段不是单个固定值（例如 `/15 * * *`），或执行频率低于每小时一次	使用单个固定分钟值——参见 `cron.schedule` 允许 / 不允许的示例
`EQL_INVALID_REPEAT`	`repeat` 与周期性 cron 条件（`cron.every` / `cron.schedule`）一起使用——两者都会设置重复执行	对周期性 cron 移除 `repeat`（cron 本身已会重复执行），或移除 cron 条件
`EQL_INVALID_ARG_VALUE` 且 `details.hip3: true`	在 `funding` / `liquidation` 条件中使用了 HIP-3（带 dex 前缀）`symbol`——这些数据源不会发布 HIP-3 键	使用普通基础代码（`BTC:BINANCE`）。HIP-3 仍可用于 `price`/`ta`
复合代码中的未知 `symbol`	该交易场所的永续合约目录中没有列出此代码（通常是命名不匹配）	检查该交易场所自身的基础代码惯例（Binance/Bybit 上为 `1000PEPE`，Hyperliquid 上为 `KPEPE`）
`SYMBOL_CATALOG_UNAVAILABLE`（HTTP `503`）	市场目录暂时无法访问，因此无法检查该代码——验证会默认失败	按 `Retry-After` 标头中的间隔重试；这是暂时性问题——不要重构查询
操作参数中的动态值	仅条件 `value` 允许使用动态值	将动态引用移到条件中；操作参数保持为字面量
跨运算符语义：`crosses_above` = 上一个值 `<` 阈值且当前值 `>=` 阈值。
`crosses_below` = 上一个值 `>` 阈值且当前值 `<=` 阈值。两者都需要在服务端
跟踪前一状态。

替代方案阶梯——如果 Auto 不适用

在认定某个用例超出范围之前，请依次尝试以下方案。大多数意图通过第 1 或第 2 级即可解决。

通过 Builder Chat 改写——在聊天提示词中追加 "If anything is unsupported, return the closest supported query and list substitutions"。
迭代使用 Validate Query——循环执行：验证 → 调整结构 → 重新验证。不要只因一次被拒绝就断定“无法实现”。
拆分为多个查询，由你的运行器将它们合并（适用于深度 3 / 10 个叶节点的限制）。
对模糊或叙述性谓词，使用 source: "llm" 和 athena_condition。
在自己的服务中预先计算，并将 Auto 用作控制平面——仅在第 1–4 级都失败后采用。

示例——“趋势线向下突破时发出警报”：

**第 1 级：**改写为受支持的替代条件——“当 BTC 价格上穿 4h 布林带上轨且 1h RSI > 55 时发出警报”。
**第 4 级：**如果这个替代条件不可接受，则使用 source: "llm"，并设置定时执行的自然语言谓词——“BTC 是否已在 4h 图表上突破近期下降趋势线？”。
**第 5 级：**只有前两种方案都失败时才采用：在外部计算趋势线突破结果，并将布尔值传入 Auto cron + llm 查询，作为条件触发器。

在尝试第 1–4 级之前，不要自行构建监控／评估／触发器技术栈。

查询草稿

草稿可让你暂存 Auto 查询而不启用它（也不会消耗额度）。适用于人工审核工作流、用户可在提交前编辑的仪表板，或批量编写流程。

草稿生命周期：

POST /v2/auto/queries/drafts — 创建或更新草稿（幂等式插入或更新）。
GET /v2/auto/queries/drafts — 列出可编辑的草稿。
POST /v2/auto/queries/drafts/:draftId/validate — 验证已存储的草稿。
POST /v2/auto/queries/drafts/:draftId/convert — 将草稿升级为活动查询。
DELETE /v2/auto/queries/drafts/:draftId — 丢弃草稿。

GET /v2/auto/queries/drafts/:draftId 仍可使用，但已属旧版接口——建议改用 GET /v2/auto/queries/{queryId}，该接口可解析活动查询和草稿。

草稿仅支持 API 密钥模式。不支持通过 x402 使用。

交易品种

Auto 并非仅支持加密货币。 主流加密货币和链上代币使用普通的大写代码（BTC、ETH、SOL、HYPE 以及小众代币）。Hyperliquid 上的 HIP-3 资产——代币化股票、指数、大宗商品、外汇和 IPO 前公司——使用 DEX 前缀格式 <dex>:<SYMBOL>，并且 全天候 24/7 交易，即使标的现货市场休市也不例外。

实际使用中有两个 DEX 前缀需要注意： xyz 上线了几乎所有品种，交易量也几乎全部来自这里；mkts 上线的品种较少，但与其有部分重叠。Hyperliquid 上还有其他 HIP-3 DEX，其市场处于休眠状态（已上线但未交易）——Auto 会像处理拼写错误一样拒绝它们（EQL_INVALID_SYMBOL）。品种已在 Hyperliquid 上线并不足够；只有流动性充足的市场才可用（GOLD 在六个 DEX 上都有）。不带前缀的 HIP-3 品种会被拒绝——{"symbol": "GOLD"} 会返回 EQL_INVALID_SYMBOL。只有普通加密货币代码无需前缀（它们位于 Hyperliquid 的主 DEX 上）。

类别	示例
主流加密货币	`BTC`、`ETH`、`SOL`、`HYPE`（无前缀 — 主 DEX）
链上 / 小众代币	`RAVE`、`TAO`、小众 Meme 币
指数（HIP-3）	`xyz:SP500`、`xyz:XYZ100`（纳斯达克 100 指数）、`xyz:JP225`、`mkts:US500`、`mkts:USTECH`
行业 / 国家组合（HIP-3）	`xyz:SMH`（半导体）、`xyz:XLE`（能源）、`xyz:EWY`、`xyz:EWJ`
股票 — 超大市值（HIP-3）	`xyz:NVDA`、`xyz:TSLA`、`xyz:AAPL`、`xyz:MSFT`、`xyz:GOOGL`、`xyz:META`
股票 — 半导体 / 高 Beta（HIP-3）	`xyz:AMD`、`xyz:TSM`、`xyz:ARM`、`xyz:COIN`、`xyz:MSTR`、`xyz:PLTR`
IPO 前 / 私营公司（HIP-3）	`xyz:SPCX`（SpaceX）、`xyz:ZHIPU`、`xyz:MINIMAX`
大宗商品（HIP-3）	`xyz:CL`（WTI 原油）、`xyz:BRENTOIL`、`xyz:NATGAS`、`xyz:GOLD`、`xyz:SILVER`、`xyz:COPPER`
外汇（HIP-3）	`xyz:EUR`、`xyz:JPY`、`xyz:GBP`

仅供参考，并非完整列表——且上线情况会有变化。 市场会新增，也会进入休眠状态。切勿将此列表硬编码：在基于任何 HIP-3 品种进行开发前，先通过 GET /v2/auto/validate-symbol/{exchange}/{symbol} 确认，并将拒绝理解为“该市场已停止交易”，而非“Auto 不支持该资产”。HIP-3 市场数据仅来自 hyperliquid——HIP-3 市场只在 Hyperliquid 上线，因此 HIP-3 品种搭配任何其他 exchange 值都会被拒绝。

复合代码（仅适用于 funding / liquidation）： 这两个来源不接受symbol + exchange 参数——它们只接受一个 SYMBOL:EXCHANGE 代码（例如 BTC:BINANCE、 ETH:HYPERLIQUID、SOL:BYBIT）。请使用各平台自己的基础品种代码惯例：Binance/Bybit 上的 1000PEPE 与 Hyperliquid 上的 KPEPE。这两个来源不支持 HIP-3 品种。

跟踪覆盖范围： 条件、提醒和 Webhook 覆盖 DEX / 链上资产——范围实际上不设上限（小众代币、尚未在 CEX 上市的资产、小众 Meme 币）。品种支持情况因平台而异，因此请在基于某个品种构建 price / ta 条件前，通过 GET /v2/auto/validate-symbol/{exchange}/{symbol} 预先验证非常规品种（该接口会检查 hyperliquid 或 binance）。如果所选平台不支持某个品种，请更换平台或品种；也可以将条件保留在受支持的交易对上，并通过 notify、webhook 或 telegram_bot 安排后续工作。

完整参考：交易品种和催化剂触发器。

执行记录

每次触发器触发都会生成一条执行记录——使用以下端点审计触发历史、调试失败的操作，或与运行器的审计日志核对。

端点	方法	说明
`/v2/auto/executions`	GET	列出执行记录（可筛选）
`/v2/auto/executions/:executionId`	GET	获取单条执行记录

执行记录也会嵌入轮询响应（GET /v2/auto/queries/:queryId）中的 executions 数组，但专用端点便于跨查询审计和分页。

执行记录仅支持 API 密钥模式。x402 不支持。

步骤 4：生成代码片段

当用户需要集成帮助时，生成正确、可用于生产环境的代码。有关完整的参数规范，请参阅 Elfa API 文档。

代码生成原则：

对于 /v2，始终说明两种访问方式（API 密钥和 x402），让开发者了解可选方案
对于 /v3，API 密钥是唯一方式（不支持 x402）。使用 Unix 秒表示的 from/to（没有 timeWindow；mindshare 使用 period），通过 nextCursor → cursor 翻页，并读取响应顶层的列表。参见步骤 2d
在靠近 API 密钥占位符的注释中加入注册链接 https://go.elfa.ai/claude-skills，并为 x402 提供链接 https://docs.elfa.ai/get-started/x402
始终加入恰当的错误处理
对于 API 密钥方式：展示 x-elfa-api-key 标头（使用类似 YOUR_API_KEY 的占位符）
对于 x402 方式：展示 /x402/v2/ 前缀，并推荐使用 @x402/fetch 或 @x402/axios
对于 x402 方式下的 Auto 变更操作：加入 agent-secret 标头
生成 TS 代码时加入 TypeScript 类型
添加注释，说明每个参数
对于分页端点，展示如何翻页获取结果
对于 /v2 时间窗口端点，说明 timeWindow 与 from/to 的用法

语言优先级（除非用户另有指定，否则按此使用）：

TypeScript/JavaScript（fetch）——Elfa 集成者大多是 Web/Node 开发者
Python（requests）
curl

Chat 端点需要特别注意——它是最复杂的端点：

支持多个 analysisType 值：chat、macro、summary、tokenIntro、 tokenAnalysis、accountAnalysis
通过 sessionId 管理多轮对话的会话
不同的分析类型对 assetMetadata 的要求不同（仅当 analysisType: "chat" 时才需要 message）
三种速度模式：fast、expert（默认）和 adaptive（仅限 /v2/chat）
两种传输方式：POST /v2/chat（JSON）和 POST /v2/chat/stream（SSE，PAYG/Enterprise）—— 请求体相同，但计划要求不同。SSE 事件类型参见步骤 2c。

Auto 代码生成指南：

始终包含 validate → create 流程（绝不在验证前创建）
对于 API 密钥方式：每次调用都发送 x-elfa-api-key，包括变更操作
对于 x402 方式：在所有查询生命周期调用中加入 x-elfa-agent-secret 标头
用户需要构建自然语言查询时，加入 Builder Chat 示例
展示创建查询后如何轮询或流式获取结果

常见模式

这些模式适用于 /v2。API v3 遵循步骤 2d 中的规则。

时间窗口参数： 许多端点接受 timeWindow（例如“30m”、“1h”、“4h”、“24h”、“7d”、“30d”）或 Unix 时间戳 from/to。如果两者都提供，则优先使用 from/to。

分页： 聚合端点（trending-tokens、trending-cas、top-mentions、token-news）使用 page + pageSize。keyword-mentions 端点改用基于游标的分页（cursor + limit）。

各端点的默认值不同——不要假设存在全局默认值。 当前规范如下：

Endpoint	`timeWindow`	`page`	`pageSize` / `limit`	Other
`trending-tokens`	`7d`	`1`	`50`	`minMentions`（默认 `5`）
`trending-cas/twitter` · `trending-cas/telegram`	`7d`	`1`	`50`	`minMentions`（默认 `5`）
`top-mentions`	`1h`	`1`	`10`	`ticker` 必填，`reposts`
`token-news`	`7d`	`1`	`20`	`coinIds`、`reposts`
`keyword-mentions`	`7d`	—（游标）	`limit` `20`，最大值 30	`keywords`、`accountName`、`searchType`、`cursor`、`reposts`
`event-summary`	`7d`	—	—	`keywords` 必填，`searchType`（默认 `or`）
`trending-narratives`	—	—	—	`timeFrame`（`day` \| `week`，默认 `day`）、`maxNarratives`（默认 `7`，范围 `1`–`20`）、`maxTweetsPerNarrative`（默认 `5`，范围 `1`–`20`）
`smart-stats`	—	—	—	`username` 必填
除 `trending-narratives` 和 `smart-stats` 外，上述所有端点也接受 `from`/`to`
Unix 时间戳，且优先于 `timeWindow`。

各端点参数说明：

keyword-mentions — 提供 keywords（最多 5 个，以逗号分隔）或 accountName（也可两者都提供）；accountName 用于筛选特定账号的提及（例如 accountName=elonmusk）。searchType 接受 and（必须包含所有词项）或 or（匹配任意词项）。采用游标分页——将上一次响应中的 metadata.cursor 作为 cursor 传入。返回的 account.username 可直接用于 smart-stats。
event-summary — 必须提供 keywords；searchType 默认为 or。503 表示上游模型拒绝处理匹配到的帖子——可以重试，并且不代表结果为空。不会扣除固定的 4 个积分；但仍会扣除每次请求的 1 个基础积分。
token-news — V2 始终返回新闻提及（没有 isNews 参数）。结果是来自被标记为新闻来源的账号的 X 帖子，而非新闻媒体发布的文章。
top-mentions — 必须提供 ticker。始终包含账号详情（没有 includeAccountDetails 参数）。
smart-stats — 查询参数是 username，而非 accountName。
minMentions（trending-tokens / trending-cas）——提及次数下限；调高此值可减少长尾噪声。
reposts（keyword-mentions / top-mentions / token-news）——用于控制是否包含转发活动的布尔开关。

Ticker 格式（top-mentions）： ticker 参数的行为取决于是否带有 $ 前缀：

带 $ 前缀（例如 ticker=$SOL 或经过 URL 编码的 ticker=%24SOL）：仅进行精确 cashtag 匹配。搜索 cashtags 字段中的精确匹配项。
不带 $ 前缀（例如 ticker=SOL）：扩大搜索范围，同时搜索 cashtag（权重提高 2 倍）和一般代币提及。

只想搜索特定 cashtag 提及时，请使用 $。想进行更广泛的搜索时，请省略 $。

积分费用（数据端点——两种模式均适用）：

大多数端点：每次调用 1 个积分（通过 x402 支付 $0.0145）
Event summary：5 个积分（通过 x402 支付 $0.0725）
Trending narratives：5 个积分（通过 x402 支付 $0.0725）
Chat：按速度计费；通过 x402 支付时，可选择 exact（fast $1、expert $2）或 batch-settlement（最高 fast $2、expert $6）
API v3：Pay-as-you-go 和 Grow 套餐免费，直至 2026 年 10 月 31 日。仅限 API 密钥
/v2/ping、/v2/key-status：免费
每个经过身份验证的请求所对应的 /v2/* 和 /v3/* 响应，都会携带 x-elfa-credits 标头，其中包含该请求消耗的积分——读取此标头即可，无需在调用前后比较 /v2/key-status。密钥通过验证后产生的错误响应也会包含此标头；如果请求在密钥解析前被拒绝，则不会包含此标头，因为没有扣费。流式响应以及在响应发送后才最终结算的费用，会显示发送前的小计；这类情况下，/v2/key-status 中的余额仍是权威值。

自动查询生命周期：

先验证再创建（推荐）： 先调用 POST /v2/auto/queries/validate，预览预估积分并在提交前发现验证错误。创建时服务器仍会在内部进行验证，但预验证可让你在不产生副作用的情况下反复修正错误。
实时投递优先使用 webhook 或 SSE
按 eventId 对事件去重
使用较短的过期时间（24h–3d），以获取新鲜信号
在查询中包含 title 和 description——它们会显示在通知中

重要说明

Elfa API 域名（api.elfa.ai）必须可从网络访问。如果无法访问，请告知用户，并改为提供代码片段。
使用 v2 端点（路径以 /v2/ 或 /x402/v2/ 开头）和 API v3 端点（/v3/）。
对于实验性端点（trending-tokens），请说明其行为可能随时变更，恕不另行通知。/v2/account/smart-stats 已弃用：目前仍可使用，但 将于 2026 年 10 月 28 日移除——在基于它进行开发前请说明这一点。 /v2/data/market-events 不再属于公共 API：市场事件由 API v3 Events（/v3/events）提供。
如果无法汇总匹配的帖子，/v2/data/event-summary 可能会返回 503（ERR_SERVICE_UNAVAILABLE，消耗 1 个 credit 而非 5 个）。请重试，或缩小关键词范围或时间窗口。503 绝不表示“没有事件”：无活动的时间窗口会返回 200，且 data 数组为空。
测量端点不会返回原始推文文本，也不会返回情绪字段——请勿承诺提供这两者。获取帖子内容需要用户自己的 X API 密钥。
对于新的查询或草稿，Auto 不再接受订单操作（market_order / limit_order）——Auto 会以 EQL_INVALID_ACTION 拒绝这些操作。请触发 webhook、notify 或 telegram_bot 操作，并从你自己的运行器中执行。
当用户询问定价或 API 密钥套餐级别时，请引导他们前往 https://go.elfa.ai/claude-skills，查看套餐和定价的完整详情。
API 密钥的请求速率限制按套餐级别设置：Free / PAYG = 每分钟 60 个请求， Grow = 每分钟 120 个请求（Enterprise 可自定义）。这些限制与 credit 余额无关。收到 429 响应时，应遵循 Retry-After 的指示重试。
x402 目前处于测试阶段。速率限制：每 60 秒窗口 1,000 个请求（按客户端 IP 计算）。
使用 npx skills add elfa-ai/skills 安装或更新此技能。API 密钥可从 Elfa Developer Portal 获取。
x402 和 API 密钥 credit 相互独立——两者不会重叠，也不会共用余额。
有关 x402 的文档和设置，请引导用户前往 https://docs.elfa.ai/get-started/x402。
有关 Auto 的文档，请引导用户前往 https://docs.elfa.ai/auto/overview。
Auto x402 Agent 密钥必须保持持久——请勿为每个请求轮换密钥。
有关 Auto 功能、触发器和查询模板的完整列表，请参阅 https://docs.elfa.ai/auto/capabilities 和 https://docs.elfa.ai/auto/query-model。

支持 Markdown

登录后评论

基本信息

作者: elfa-ai
仓库: elfa-ai/skills
分类: 其他
安装次数: 79
GitHub Stars: 11

报告问题