文件

🚀 5 分鐘快速上手

如果你只想趕快試試，照這個順序做就好：

1. 到 註冊 開帳號（免費，不要信用卡）
2. 按儀表板上方藍色 banner「跟著 4 步引導走」
3. 跟著新手引導 4 步：開 API key → 貼進來 → 建策略（勾「先試跑」）→ 發測試訊號
4. 看到測試訊號出現在「訊號」頁，就完成了

想要更詳細的步驟說明，繼續往下看。

📡 TradingView Alert 完整設定

這是用戶最常卡關的地方。我們已經提供「📋 TV 模板」一鍵複製，但理解原理你會更有掌控感。

Step 1：打開你的策略圖表

在 TradingView 開好你已經寫好的 Pine Script 策略圖表（或公開策略）。策略必須能產生 buy / sell 訊號（用 strategy.entry 或 alertcondition）。

Step 2：建立 Alert

1. 圖表右上角「🕐」圖示 → Create Alert
2. Condition 選你的策略或 alertcondition
3. Options：Frequency 建議選 Once Per Bar Close（避免每 tick 觸發）
4. Expiration：Open-ended（除非你只想跑一段時間）

Step 3：設定 Webhook

1. 切到 Notifications tab
2. 勾 Webhook URL
3. 把你 dashboard 給的 webhook URL 貼上
4. 下面的 Message 欄位貼 JSON message body（dashboard 給的 TV 模板會幫你產好）

Step 4：儲存 + 測試

按 Create。之後策略觸發時 TradingView 會 POST 到你的 webhook，訊號會出現在 dashboard 的「訊號」頁。

🔑 各交易所 API key 申請

Binance

1. 登入 → 右上頭像 → API Management
2. Create API → 輸入名稱（例：tvsbot）
3. 2FA 驗證
4. 編輯權限：勾「Enable Spot & Margin Trading」+「Enable Futures」
5. 不要勾「Enable Withdrawals」
6. 建議加 IP 白名單（看 TVSBot 之後給的 IP）
7. 儲存 API Key + Secret，貼到 dashboard

官方教學：Binance API Key 設定 ↗

OKX

1. 右上頭像 → API → 建立 API key V5
2. 取名稱、設 Passphrase（OKX 特別需要 Passphrase）
3. 權限：勾 Trade
4. 不要勾 Withdraw
5. 3 個都要貼到 dashboard：API Key、Secret、Passphrase

官方教學：OKX API Key 設定 ↗

Bitget

1. 右上頭像 → API 管理 → 建立 API
2. 取名稱 + 設置 Passphrase
3. 權限：勾 Trade，不勾 Withdraw
4. 儲存 API Key + Secret + Passphrase 到 dashboard
5. 建議綁 IP 白名單（看 dashboard 給的後端 IP）— Bitget 沒強制但加了多一層防護

Bybit

1. 右上頭像 → API → 建立新 Key
2. 選擇 System-generated API Keys
3. 權限：勾 Contract Trade + Spot Trading
4. 不勾 Withdraw
5. 建議綁 IP 白名單（看 dashboard 給的後端 IP）— Bybit 允許多個 IP，逗號分隔

Gate.io

1. 登入 → 右上頭像 → API 管理（API Management）
2. 點「建立 API Key」→ 取個好認的名稱（例如 tvsbot）
3. 2FA / 郵件驗證
4. 權限：勾 現貨交易（Spot Trade）+ 永續合約交易（Perpetual Futures Trade）
5. 不要勾 提幣（Withdrawal）
6. 建議綁定 IP 白名單。Gate 規定如果開了 IP 白名單，不能同時開提幣權限（雙保險）。
7. 儲存後系統會給 API Key + Secret，貼到 dashboard

官方教學：Gate.io API Key 設定 ↗

BingX

1. 登入 → 右上頭像 → API 管理
2. 「建立 API Key」→ 取個名稱（例如 tvsbot）
3. 2FA / Google Authenticator 驗證
4. 權限選擇：勾 讀取（Read） + 合約交易（Perpetual Trade） + 現貨交易（Spot Trade）
5. 不要勾 「提幣（Withdraw）」這欄
6. 建議綁 IP 白名單（看 dashboard 給的後端 IP）
7. 儲存後複製 API Key + Secret 到 dashboard

官方教學：BingX 開放平台 ↗

Hyperliquid（DEX 永續）

1. 用我們連結註冊 → app.hyperliquid.xyz/join/TVSBOT ↗ （你可以完成「驗證 Hyperliquid」任務拿 7 天試用）
2. 登入後到 More → API
3. 點 Generate API Wallet → 系統會給你一個新的 wallet address + private key
4. 授權主錢包簽名同意「Use this API wallet to trade」
5. 儲存：API wallet address 和 API wallet private key（**不是主錢包的**）
6. 到 TVSBot 加 API key 時選 Hyperliquid，貼上述兩項

⚙ 永續合約：持倉模式 / 槓桿 / 保證金

如果你只下現貨可以跳過這節。 但如果你想用 TVSBot 跑永續合約策略，這節務必看完一次，因為「持倉模式」設錯，訊號會被交易所靜默拒絕或下到錯的位置上。

什麼是「持倉模式」？

三家主流交易所都有兩種持倉模式：

• 單向持倉（One-way mode）：一個合約只能有一個方向倉位。多單存在時送 sell 訊號 = 平多。TVSBot 預設假設這個模式，訊號邏輯最直觀，新手強烈建議。
• 雙向持倉（Hedge mode）：同一合約可以同時有多單 + 空單，下單時要明確指定 positionSide=LONG/SHORT。適合做對沖、grid 策略；但用 TVSBot 之前你必須自己在 webhook 裡明確指定 positionSide，否則交易所會回錯「position side does not match」。

各家持倉模式設定位置

• Binance Futures：右上頭像 → Preference → Position Mode → 選 One-way Mode。有持倉時不能切換，要先平倉。
• OKX：右上頭像 → 交易設置 → 持倉模式 → 選 單向持倉。逐倉 / 全倉是另一個獨立設定。
• Bitget：交易頁右上「設置」齒輪 → 持倉模式 → 選 單向持倉。
• Bybit：右上設置 → Position Mode → 選 One-Way Mode。

槓桿（leverage）

策略可以在 webhook payload 設 leverage: 5，TVSBot 會先 set_leverage 再下單。注意：

• 每個交易對的最大槓桿不同（BTC 通常最高，山寨幣低），超過會被擋。
• 我們在風控設定有「最大槓桿上限」(預設 10)。即使 webhook 寫 100x，也會被自動降到你的上限，不會阻擋下單。
• 修改既有倉位的槓桿，部分交易所要求先平倉。

保證金模式（margin mode）

• Cross（全倉）：整個錢包當保證金，較不易被爆倉但風險彼此關聯。TVSBot 預設 cross。
• Isolated（逐倉）：只用單筆指定保證金，爆倉只賠那一筆。在 payload 加 margin_mode: "isolated" 切換。

部位大小：五種 qty_type 怎麼選

• ⭐ margin_usdtmargin_usdt（永續最直覺、推薦）：用 X USDT 做「保證金」，系統 × leverage 算名義價值。例：qty=20, leverage=3 → 保證金 $20、倉位 $60（散戶直覺「我用 20 元 × 3 倍開單」就對應這個）。
• margin_pct：永續合約常用。用 USDT 餘額的 N%「當保證金」配合 leverage 開倉。例：餘額 1000 USDT × 10% × 5x = 500 USDT 名義價值的多單。跟 margin_usdt 差別在「以 % 算 vs 以 $ 算」。
• fixed：寫死數量（如 0.01 BTC）。簡單但跟著餘額變化沒辦法。
• percent：USDT 餘額百分比（10 = 10%）。適合穩定加倉的現貨策略。
• ⚠️ usdtusdt（進階：直接指定倉位 notional）：qty 就是倉位名義價值。**leverage 只影響保證金需求、不會放大倉位**。例：qty=20, leverage=3 → 倉位 $20、保證金 ~$6.67。不熟 perp 機制請用 margin_usdt。

📦 Webhook 訊號格式（payload）

TradingView Alert 的 Message 欄位內容必須是合法 JSON，欄位如下：

{
  "secret": "你的 webhook secret",
  "strategy": "策略名稱（必須跟 dashboard 上的一致）",
  "action": "buy" | "sell" | "close",
  "symbol": "BTCUSDT",
  "exchange": "binance" | "okx" | "bitget" | "bybit",
  "market_type": "spot" | "futures",
  "order_type": "market",

  // 部位大小：擇一寫法
  "qty_type": "fixed" | "usdt" | "percent" | "margin_pct",
  "qty": 0.01,              // 對應 qty_type 的數值

  // 或用 margin_pct 簡寫（只 futures 用，自動視為 qty_type=margin_pct）
  "margin_pct": 10,         // 用 10% 餘額當保證金

  "leverage": 5,            // futures 才用
  "margin_mode": "cross",   // futures 才用，預設 cross

  "tp_price": null,
  "sl_price": null,
  "tp_pct": null,           // % 形式（以進場價為基準）
  "sl_pct": null,
  "reduce_only": false,     // close 時自動帶 true
  "comment": "純記錄欄位"   // 不影響執行，方便回看
}

必填：secret / strategy / action / symbol / exchange，加上以下任一組部位大小寫法：

• qty_type="fixed" + qty（如 0.01 BTC）
• qty_type="usdt" + qty（如 100 USDT 等值）
• qty_type="percent" + qty（如 10 表 10% USDT 餘額）
• qty_type="margin_pct" + qty + leverage（永續最常用）
• margin_pct 簡寫（自動等價於 qty_type=margin_pct）

其他欄位有預設值。用 dashboard 的「📋 TV 模板」按鈕都會自動填好。

action 三種值：buy / sell / close

• buy：開多 / 加倉多單
• sell：開空 / 加倉空單（spot 則賣出資產）
• close平倉。系統會自動 fetch_positions 找對應 symbol 的當前倉位，反向 reduce_only 送單。沒倉位視為 noop 不報錯。僅 futures 支援（spot 沒有倉位概念）。

自動停損停利（TP/SL）

主單成交後系統自動掛兩筆 reduce_only 條件單：take_profit_market（停利）+ stop_market（停損）。僅 futures 支援，spot 會 skip。

• tp_price / sl_price：絕對價格（如 BTC 72000）
• tp_pct / sl_pct：以進場價為基準的百分比（如 tp_pct=2 表進場價 +2% 停利；買 BTC@70000 → 停利 71400）
• 絕對價優先；兩者都給的話以絕對價為準
• 一邊掛單失敗不影響另一邊（如 SL 成功但 TP 失敗）。失敗原因會出現在訊號詳情頁的 bracket 區塊。

Trailing stop（跟隨停損）

trailing_stop_pct：價格朝有利方向走時，停損點跟著移動鎖住獲利；朝不利方向走則停在當下高位（多單）或低位（空單）。例：

• 買 BTC@70000，trailing_stop_pct=2 → 停損初始 68600
• 價漲到 75000 → 停損跟著上移到 73500
• 價跌回 73500 → 觸發平倉，實際出場約 73500
• 目前僅 Binance Futures 支援（callback rate 範圍 0.1-5%）。其他交易所之後支援。
• 跟 sl_pct / sl_price 互斥；同時設了會以 trailing 為準（不會掛兩條停損）。

🔧 常見錯誤排除

「找不到策略」

訊號收到了但被 reject。原因：payload 的 strategy 跟 dashboard 上的策略名稱不一致。檢查大小寫、空白、繁簡體。

「secret 錯誤」（401）

payload 的 secret 跟你 profile 的 webhook_secret 對不上。到「策略 → 📋 TV 模板」重新複製。

「invalid webhook token」（401）

URL 裡的 token 無效。檢查 webhook URL 是不是完整複製，常見是 URL 結尾少了字元。

「認證失敗」（下單時）

ccxt 呼叫交易所被拒絕。通常是：

• API key 已被你在交易所那邊撤銷
• API key 有 IP 白名單但 TVSBot 後端 IP 不在裡面
• API key 沒有 Trade 權限

「餘額不足」

字面意思。檢查交易所帳戶餘額。

「Invalid JSON / payload」（400）

TradingView 寄來的 message 不是合法 JSON。常見原因：

• 用了中文引號「」 取代英文 " — TV 模板要照原樣複製、不要被輸入法改字
• JSON 內逗號漏寫或多寫一個尾逗號（trailing comma）
• 把 {{strategy.order.action}} 這種 TV 變數忘了加引號（必須當字串）

Dashboard 訊號頁有 raw payload，可以複製到 jsonlint.com 驗證。

「缺少必填欄位」（422）

payload 缺欄位或欄位拼錯。一定要有的：

action（buy / sell / close）、symbol、qty_type、qty。期貨還要 leverage、market_type=futures。

怎麼測 webhook 是否暢通？

去策略頁按「🔔 Ping 測試訊號」按鈕，系統會用 dry-run 模式發一筆假訊號到你的 webhook。15 秒內如果訊號頁出現一筆 「validation_status=test」 就代表整條鏈路通。

訊號完全沒收到

可能性：

• TradingView Alert 沒設定 Webhook URL（只設了瀏覽器通知）
• Webhook URL 打錯（多了空白、少字元）
• TradingView 那邊 Alert 已經過期或被刪
• 策略本身沒觸發訊號

到「訊號」頁看有沒有任何紀錄。如果完全沒紀錄，問題在 TradingView 那邊。