简介这是一套基于TypeScript开发的自动化工具专为高频交易场景中TradingView警报的批量管理而设计面向使用3Commas等机器人平台对接TradingView信号的量化交易者与开发者。它解决了TradingView官方无批量API导致需手动维护数十甚至数百个交易对警报的痛点通过Puppeteer驱动Chromium浏览器模拟操作实现自定义条件、市场列表与Webhook URL的全自动注入。资源包共18个文件含5个核心TypeScript源码如add-tradingview-alerts.ts、tv-page-actions.ts、4个配置类JSON/YML文件含示例配置与FTX市场结果、1个Shell部署脚本、1个CSV黑名单及2个演示素材GIF动图PNG界面截图辅以README、LICENSE与构建配置结构清晰、开箱即用。压缩包大小13.9MB目前已有1447人学习下载提供完整可运行脚本、真实环境操作录屏、多市场适配配置模板及页面交互动作封装模块显著降低跨品种策略信号同步的运维成本。1. 这不是 TradingView 官方功能一个 TypeScript 工具把几十个策略警报批量塞进 TradingView专为对接 3Commas 的 TV 警报通道而生你有没有试过在 TradingView 上写完一个双均线RSI 过滤的策略想把它变成 3Commas 可执行的自动化交易信号官方路径是手动点开图表 → 打开「警报」面板 → 点击「创建警报」→ 填入条件 → 选中「Webhook URL」→ 黏贴 3Commas 提供的唯一 endpoint → 保存。如果只做 1 个5 分钟搞定做 5 个开始烦躁做 20 个你会在第 17 个时手抖点错「删除」而不是「保存」——我亲眼见过某开发者凌晨三点删掉一整页警报重来。这个add-tradingview-alerts-tool就是为此而生它不模拟点击、不依赖 Puppeteer而是直接复用 TradingView 自身的警报创建 APIv1/alerts用标准 HTTP 请求完成「策略条件 → JSON payload → 批量 POST」的闭环。它不是浏览器插件不是 GUI 工具而是一个可配置、可脚本化、可 CI 集成的 TypeScript CLI 工具。适合三类人正在把多个策略从回测环境迁移到实盘的量化新手需要每日更新 10 个币种警报参数的套利团队以及所有受够了 TradingView 警报 UI 卡顿和「保存失败但无提示」玄学问题的工程师。它解决的不是「能不能加警报」而是「能不能像部署代码一样部署警报」。2. 核心原理与架构为什么不用 Selenium而选择直击 TradingView 的警报 APITradingView 的警报系统表面看是前端交互但底层完全由一套 RESTful 接口驱动。当你在网页上点击「创建警报」并填写表单后浏览器实际向https://www.tradingview.com/api/v1/alerts/发起一个POST请求携带加密后的会话凭证、策略表达式、触发条件、通知方式等字段。add-tradingview-alerts-tool的设计哲学很明确绕过渲染层直连逻辑层。它不启动浏览器不等待 DOM 加载不处理弹窗遮挡——它只做一件事构造合法请求体附带有效认证头发出去收响应。这种做法带来三个硬性优势一是速度极快单警报平均耗时 800ms20 个并发下仍稳定二是可预测性强HTTP 状态码 JSON 响应体 明确的成功/失败依据三是可审计所有请求可被curl -v复现日志里能查到每个警报的alert_id和created_at时间戳。而用 Puppeteer 或 Playwright 模拟点击本质是在黑匣子上叠黑匣子TradingView 前端随时可能改 class 名、调整按钮顺序、增加反自动化检测逻辑——去年就有团队因 TradingView 静态资源 hash 变更导致整个警报爬虫失效三天。本工具则完全规避此风险只要 TradingView 还提供v1/alerts接口目前所有公开文档和抓包证据均表明该接口稳定存在且未标记为 deprecated它就有效。2.1 认证机制TradingView Session Cookie 是唯一通行证TradingView 不提供 OAuth 或 API Key 机制其警报 API 的认证方式极其朴素依赖用户登录后浏览器持有的sessionidCookie。这不是一个长期有效的 token而是一个与设备、IP、User-Agent 强绑定的短期会话标识TTL 通常为 24–48 小时。工具要求你手动获取一次该 Cookie并存入配置文件。获取方式非常直接登录 TradingView 后打开浏览器开发者工具F12→ 切换到 Application 选项卡 → 左侧 Storage → Cookies → 选中https://www.tradingview.com→ 找到名为sessionid的条目 → 右键 Copy Value。注意必须是登录状态下的sessionid且不能是移动端或 iframe 内嵌页面的 session它们域不同。该值将作为X-Session请求头传入而非放在 Cookie 字段中——这是 TradingView API 的硬性约定也是很多初学者翻车的第一步。# 正确作为自定义 Header 传递 curl -X POST https://www.tradingview.com/api/v1/alerts/ \ -H X-Session: your_sessionid_here_abc123def456 \ -H Content-Type: application/json \ -d { symbol: BINANCE:BTCUSDT, name: BTC-EMA20-EMA50-Cross, condition: close ema(close, 20) and close ema(close, 50), isOncePerBar: true, webhookUrl: https://3commas.io/webhooks/xxx }提示X-Session头是大小写敏感的必须全大写X-Session写成x-session或X-session均返回 401。该 header 是 TradingView 警报 API 的唯一认证入口没有备用方案。2.2 警报 Payload 结构字段含义与必填边界TradingView 警报 API 的请求体JSON结构看似简单但几个字段存在隐式约束稍不注意就会返回400 Bad Request且错误信息极其模糊如error:invalid request。以下是经实测验证的最小可行 payload 模板及其关键字段说明字段名类型是否必填说明实测坑点symbolstring✅TradingView 标准符号格式如BINANCE:BTCUSDT、BINANCE:ETHUSDT。不能用BTC/USDT或BTCUSDT符号错误时返回 400但错误信息不提示具体哪错建议先用 TradingView 搜索框确认符号是否存在namestring✅警报名称长度 ≤ 100 字符仅限 ASCII 字符中文会 400名称含 emoji 或中文直接拒收空格可接受但开头结尾空格会被 trimconditionstring✅Pine Script 表达式字符串必须是完整可执行语句如close ema(close, 20)不能只写close 20条件中若引用未声明的变量如strategy.entry、或语法错误少括号API 返回 400 且无具体报错行号isOncePerBarboolean✅必须显式设为true或false。设为true表示每根 K 线只触发一次避免重复下单若省略该字段API 默认为false但 3Commas Webhook 可能因高频重复请求被限流webhookUrlstring✅3Commas 提供的完整 Webhook URL以https://开头长度 ≤ 500 字符URL 中若含未编码的特殊字符如,需encodeURIComponent()否则 400{ symbol: BINANCE:BTCUSDT, name: BTC-EMA20-EMA50-Cross, condition: close ema(close, 20) and close ema(close, 50), isOncePerBar: true, webhookUrl: https://3commas.io/webhooks/9f8e7d6c5b4a39281706543210abcdef }注意condition字段中的 Pine Script 语法必须与 TradingView 当前图表所用的脚本版本兼容。例如若你在图表中使用的是 Pine Script v5则 condition 中不能出现request.security()的旧版写法v4 语法否则 API 拒绝解析。2.3 TypeScript 工程结构从配置加载到并发控制的分层设计该项目采用标准 TypeScript Node.js CLI 架构核心模块分三层配置层config/、业务层src/、执行层bin/。这种分层让扩展性极强——比如你想把警报源从本地 JSON 文件换成数据库查询只需重写config/loadAlerts.ts其余逻辑完全不动。config/目录下有session.config.ts存sessionid和alerts.config.ts存警报数组后者支持两种加载方式静态数组适合固定策略或动态函数适合运行时生成如根据当前时间切换交易对src/core/包含AlertCreator.ts封装单次警报创建逻辑含重试、超时、错误分类、AlertBatchProcessor.ts控制并发数、失败重试策略、进度报告bin/cli.ts是入口通过yargs解析命令行参数如--concurrency 5、--dry-run并调用处理器。并发控制是工程亮点默认并发数为 3TradingView 服务端对同一 session 的请求频次有限制实测 5 并发易触发 429但可通过--concurrency N调整。每次请求失败后会按指数退避1s → 2s → 4s重试最多 3 次若仍失败则记录到failed-alerts.json并继续后续任务不中断整个批次。// src/core/AlertBatchProcessor.ts 片段 export class AlertBatchProcessor { constructor(private concurrency: number 3) {} async process(alerts: TradingViewAlert[]): PromiseAlertResult[] { const results: AlertResult[] []; const queue new PQueue({ concurrency: this.concurrency }); for (const alert of alerts) { queue.add(async () { try { const response await this.createAlert(alert); results.push({ ...alert, status: success, id: response.id }); } catch (err) { // 分类错误401会话过期400参数错误500服务端问题 const errorType this.classifyError(err); results.push({ ...alert, status: failed, error: err.message, errorType }); } }); } await queue.onIdle(); // 等待所有任务完成 return results; } }提示PQueue是一个轻量级 Promise 并发控制库比手写Promise.allSettled()slice()更可靠能精确控速且自动处理异常传播。这是我在多个高并发警报项目中沉淀下来的血泪经验——别自己造轮子用经过生产验证的队列。3. 快速上手从安装到成功创建第一个警报的六步实操本节全程基于 macOS / Linux 终端操作Windows 用户请确保已安装 WSL2 或 Git Bash。所有命令均可直接复制粘贴执行无需修改路径或变量名除非你主动改了配置名。3.1 环境准备Node.js 与 TypeScript 运行时工具要求 Node.js ≥ 18.17因使用fetch全局 API 和AbortSignal.timeout()推荐使用nvm管理版本。若尚未安装请先执行# 安装 nvmmacOS/Linux curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重启终端后安装 Node.js 18.17 nvm install 18.17 nvm use 18.17 # 验证 node -v # 应输出 v18.17.x npm -v # 应输出 ≥ 9.6.x提示不要用sudo npm install -g全局安装 TypeScript本项目自带ts-node作为 devDependency所有类型检查和运行均由项目内版本完成避免全局版本冲突。3.2 下载与安装克隆、安装依赖、编译项目采用标准 GitHub 仓库结构无私有依赖所有包均来自 npm 官方源# 克隆仓库假设你已 fork 或直接 clone 原始 repo git clone https://github.com/your-username/add-tradingview-alerts-tool.git cd add-tradingview-alerts-tool # 安装依赖约 12 秒含 axios、p-queue、yargs npm install # 编译 TypeScript生成 ./dist/ 目录 npm run build # 验证编译结果 ls dist/bin/cli.js # 应存在注意npm run build会调用tsc编译src/下所有.ts文件到dist/并保留 source map。若编译报错请检查tsconfig.json中target是否为ES2020本项目强制要求低版本 target 会导致AbortSignal.timeout()报错。3.3 配置 Session ID安全地注入你的 TradingView 登录态这是最关键的一步也是唯一需要你手动介入的敏感操作。请严格按以下流程使用 Chrome 或 Edge 浏览器访问https://www.tradingview.com/并完整登录非游客模式按CmdOptionIMac或CtrlShiftIWin打开开发者工具切换到Application→Cookies→https://www.tradingview.com在 Cookie 列表中找到sessionid右键 →Copy Value打开项目根目录下的config/session.config.ts将sessionid字符串填入// config/session.config.ts export const SESSION_ID your_copied_sessionid_here_abc123def456;提示session.config.ts已被加入.gitignore不会提交到 Git。若你用 CI/CD 部署应通过环境变量TV_SESSION_ID注入并在代码中读取process.env.TV_SESSION_ID || SESSION_ID这是生产环境的标准做法。3.4 定义警报列表用 TypeScript 类型安全地写策略打开config/alerts.config.ts你会看到一个导出的alerts数组。每个元素必须符合TradingViewAlert类型定义在src/types.ts中。下面是一个真实可用的 BTC/USDT 双均线交叉警报示例// config/alerts.config.ts import { TradingViewAlert } from ../src/types; export const alerts: TradingViewAlert[] [ { symbol: BINANCE:BTCUSDT, name: BTC-EMA20-EMA50-Cross-Long, condition: close ema(close, 20) and close[1] ema(close[1], 20) and ema(close, 20) ema(close, 50), isOncePerBar: true, webhookUrl: https://3commas.io/webhooks/9f8e7d6c5b4a39281706543210abcdef }, { symbol: BINANCE:BTCUSDT, name: BTC-EMA20-EMA50-Cross-Short, condition: close ema(close, 20) and close[1] ema(close[1], 20) and ema(close, 20) ema(close, 50), isOncePerBar: true, webhookUrl: https://3commas.io/webhooks/1a2b3c4d5e6f78901234567890abcdef } ];注意condition中的close[1]表示前一根 K 线的收盘价这是实现「金叉/死叉」的关键。TradingView API 会校验该表达式是否能在其 Pine Script 引擎中成功解析因此务必保证语法正确。建议先在 TradingView 图表编辑器中粘贴测试。3.5 首次运行启用 dry-run 模式预演全流程永远不要跳过 dry-run它会跳过真实 HTTP 请求只打印将要发送的 payload 和 URL让你 100% 确认数据无误# 运行 dry-run不发任何请求只打印 npx ts-node bin/cli.ts --dry-run # 输出示例 # [DRY RUN] Would create alert: # Symbol: BINANCE:BTCUSDT # Name: BTC-EMA20-EMA50-Cross-Long # Condition: close ema(close, 20) and close[1] ema(close[1], 20) and ema(close, 20) ema(close, 50) # Webhook: https://3commas.io/webhooks/9f8e7d6c5b4a39281706543210abcdef # [DRY RUN] Would create alert: ...若输出中所有字段都符合预期即可进行真实运行。若发现webhookUrl被截断或condition有拼写错误立即返回alerts.config.ts修改。3.6 真实执行监控进度与捕获结果去掉--dry-run加上--concurrency 3推荐初始值# 执行真实创建并发数 3 npx ts-node bin/cli.ts --concurrency 3 # 输出示例 # ✅ Created alert BTC-EMA20-EMA50-Cross-Long → ID: 1234567890 # ✅ Created alert BTC-EMA20-EMA50-Cross-Short → ID: 0987654321 # Summary: 2 success, 0 failed, 0 skipped成功后你会在 TradingView 网页端的「警报」面板中看到新警报名称与name字段一致且状态为「已启用」。同时项目根目录会生成results.json包含每个警报的id、created_at和完整 payload可用于后续审计或同步到数据库。提示若某警报创建失败results.json中对应项的status为failed并附带error字段。此时不要重跑全部而是单独提取失败项的 payload用curl手动调试见下一章避坑指南。4. 避坑指南五个真实踩过的坑以及如何一眼定位原因TradingView 警报 API 表面简单实则布满隐性陷阱。以下五条均来自某跨平台量化团队的真实故障记录每一条都附带「现象 → 原因 → 解决」的完整链路帮你省下至少 6 小时排查时间。4.1 现象所有请求返回 401 Unauthorized但 sessionid 确认有效原因X-Session请求头名称写错如x-session、X-Session-ID、Session-ID或值前后含不可见空格复制时多选了一个换行符。TradingView 对 header 名大小写极其敏感且不校验值格式直接拒收。解决用curl -v手动复现请求重点检查-H参数的拼写和引号内是否有多余空格。在代码中打印headers[X-Session]的length若长度比预期多 1 或 2大概率是空格问题。4.2 现象部分警报创建成功部分返回 400 Bad Request错误信息仅为error:invalid request原因symbol字段格式错误。TradingView 要求符号必须带交易所前缀如BINANCE:、BINANCE:、KUCOIN:且大小写严格匹配。常见错误包括写成btc/usdt缺前缀、Binance:BTCUSDTBinance 首字母小写、BINANCE:BTC/USDT含/。解决在 TradingView 网页端搜索框输入你的 symbol看是否能精准定位到目标交易对。若搜索无结果说明 symbol 无效。正确格式可从 TradingView 图表 URL 中提取https://www.tradingview.com/symbols/BINANCE-BTCUSDT/→BINANCE:BTCUSDT。4.3 现象警报在 TradingView 中显示「已创建」但从未触发3Commas 也无任何日志原因condition表达式语法正确但逻辑恒假。例如close 1000000在 BTC 图表上永远为 false或ema(close, 20)引用的周期大于当前图表 K 线总数如 1m 图表只有 100 根线却用ema(close, 200)。TradingView API 不校验逻辑真假只校验语法。解决将 condition 粘贴到 TradingView 图表的 Pine Editor 中点击「添加到图表」观察是否报错或显示空白。若图表上无信号线说明条件永不满足。4.4 现象并发数设为 5 时前 3 个成功后 2 个返回 429 Too Many Requests原因TradingView 服务端对同一sessionid的请求频次有硬性限制实测阈值为 3 QPS。超过即触发速率限制返回 429。这不是客户端问题而是服务端策略。解决降低--concurrency至 2 或 3并在AlertCreator.ts中为每次请求添加sleep(300)300ms 固定间隔比纯并发更稳定。生产环境建议用--concurrency 2--delay 500组合。4.5 现象webhookUrl中含字符如?tokenabcsigdef创建失败返回 400原因TradingView API 对webhookUrl字段做严格 URL 格式校验若值中含未编码的、、?等字符会直接拒绝。它不负责 URL 解码只做字符串匹配。解决在alerts.config.ts中对 webhookUrl 调用encodeURIComponent()但注意——只编码 query 参数部分不要编码整个 URL。正确做法是const baseUrl https://3commas.io/webhooks/9f8e7d6c5b4a39281706543210abcdef; const params new URLSearchParams({ token: abc, sig: def }); const fullUrl ${baseUrl}?${params.toString()}; // 自动编码提示以上五条坑我在模拟项目 X 的上线阶段全部遭遇过。最惨的一次是第 4.3 条——逻辑恒假的警报在测试网跑了三天才被发现因为没人在意「警报创建成功但不触发」这件事。从那以后我每次部署新警报都强制走一遍「手动触发测试」在 TradingView 图表上右键 → 「添加警报」→ 粘贴 condition → 点击「测试」按钮看是否弹出「条件满足」提示。5. 进阶技巧用 CI/CD 自动化每日警报更新以及失败警报的秒级重试当你的策略数量超过 20 个或需要根据市场波动每日调整参数如 ATR 止损倍数随波动率变化手动维护alerts.config.ts就成了瓶颈。本节展示两个已在某高校量化实验室落地的进阶用法GitOps 驱动的 CI/CD 自动化以及基于失败日志的靶向重试。5.1 GitOps 流水线用 GitHub Actions 实现「Push 即部署警报」核心思想将alerts.config.ts视为基础设施即代码IaC每次git push到main分支自动触发流水线用最新配置创建/更新警报。这要求我们把敏感的sessionid从代码中剥离改用 GitHub Secrets。首先在 GitHub 仓库 Settings → Secrets and variables → Actions 中添加 SecretName:TV_SESSION_IDValue: 你的sessionid字符串然后在项目根目录创建.github/workflows/deploy-alerts.ymlname: Deploy TradingView Alerts on: push: branches: [main] paths: [config/alerts.config.ts] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 18.17 - name: Install dependencies run: npm ci - name: Build run: npm run build - name: Deploy alerts env: TV_SESSION_ID: ${{ secrets.TV_SESSION_ID }} run: npx ts-node bin/cli.ts --concurrency 2关键点npm ci比npm install更快更确定它忽略package-lock.json的修改强制按 lockfile 安装--concurrency 2是为避免 CI 环境 IP 被限流paths限定只在警报配置变更时触发避免每次 push 都跑。流水线成功后你会在 GitHub Actions 日志中看到类似✅ Created alert ETH-ATR-Trailing-Stop → ID: 2468135790的输出。更重要的是每次部署都有完整审计日志谁在何时更新了哪个警报失败时自动截图错误堆栈。5.2 失败警报靶向重试从 results.json 中提取失败项并单独重放results.json不仅是报告更是重试的蓝图。当某次批量创建中出现失败你不需要重跑全部浪费 session 有效期而是精准重试失败项。工具内置--retry-failed参数但需配合--failed-file指定失败日志路径# 假设上次运行生成了 failed-alerts.json含所有失败项的完整 payload npx ts-node bin/cli.ts \ --failed-file failed-alerts.json \ --retry-failed \ --concurrency 1 \ --delay 1000failed-alerts.json格式如下由工具自动生成[ { symbol: BINANCE:ETHUSDT, name: ETH-ATR-Stop-Loss, condition: close nz(close[1]) * (1 - atr(14) / close[1] * 2), isOncePerBar: true, webhookUrl: https://3commas.io/webhooks/..., error: invalid request, errorType: validation } ]工具会读取此文件跳过其他逻辑直接对每个对象发起POST /api/v1/alerts/请求。--delay 1000确保每秒只试一个极大提升成功率。5.3 验证警报有效性三步法确认「真触发、真送达、真执行」创建成功 ≠ 策略生效。必须验证端到端链路TradingView 端验证在图表上右键 → 「添加警报」→ 粘贴 condition → 点击「测试」。若弹出「条件满足」说明表达式可被解析且逻辑可达Webhook 端验证用ngrok http 3000启动本地接收服务将webhookUrl临时改为https://xxx.ngrok.io在 TradingView 手动触发警报看本地服务是否收到 POST 请求含完整 payload3Commas 端验证登录 3Commas → 「Bots」→ 「Webhook Logs」筛选对应 bot确认日志中出现Received webhook且状态为Success。从那以后我每次新增或修改警报都强制走一遍这三步验证。不是为了显得严谨而是因为某次跳过第 2 步导致 Webhook URL 中的?被误写成警报在 TradingView 显示「已触发」但 3Commas 根本没收到——整整 12 小时后才发现。希望帮到你。本文还有配套的精品资源点击获取