Docs

🚀 5-Minute Quickstart

If you just want to try it quickly, follow these steps in order:

1. Go to sign up for an account (free, no credit card)
2. Click the blue banner at the top of the dashboard: "Follow the 4-step guide"
3. Follow the 4-step onboarding: create API key → paste in → create strategy (check "dry-run first") → send test signal
4. Once the test signal shows up on the "Signals" page, you're done

For more detailed steps, keep reading.

📡 TradingView Alert Setup

This is where users most often get stuck. We provide the "📋 TV Template" one-click copy, but understanding the mechanics gives you more control.

Step 1: Open your strategy chart

Open the TradingView chart with your Pine Script strategy (or a public strategy).The strategy must produce buy / sell signals (using strategy.entry or alertcondition).

Step 2: Create the Alert

1. Top-right "🕐" icon on the chart → Create Alert
2. Condition — pick your strategy or alertcondition
3. Options: For Frequency, choose Once Per Bar Close (avoid triggering on every tick)
4. Expiration: Open-ended (unless you only want it to run for a limited time)

Step 3: Configure the Webhook

1. Switch to the Notifications tab
2. Check Webhook URL
3. Paste the webhook URL from your dashboard
4. In the Message field below, paste the JSON message body (the dashboard's TV template will generate it for you)

Step 4: Save + Test

Click Create. When your strategy triggers, TradingView will POST to your webhook, and signals will appear on the dashboard's "Signals" page.

🔑 API Key Setup for Each Exchange

Binance

1. Log in → top-right avatar → API Management
2. Create API → enter a name (e.g., tvsbot)
3. 2FA verification
4. Edit permissions: enable "Enable Spot & Margin Trading" + "Enable Futures"
5. Do NOT enable "Enable Withdrawals"
6. Do NOT enable an IP whitelist — TVSBot has no fixed outbound IP, so binding one will get your orders rejected by Binance
7. Save API Key + Secret, paste into the dashboard

Official guide: Binance API Key setup ↗

OKX

1. Top-right avatar → API → Create API key V5
2. Name it, set a Passphrase (OKX specifically requires a Passphrase)
3. Permissions: enable Trade
4. Do NOT enable Withdraw
5. All 3 must be pasted into the dashboard: API Key, Secret, Passphrase

Official guide: OKX API Key setup ↗

Bitget

1. Top-right avatar → API Management → Create API
2. Name it + set a Passphrase
3. Permissions: enable Trade, do not enable Withdraw
4. Save API Key + Secret + Passphrase to the dashboard
5. Do NOT enable an IP whitelist — TVSBot has no fixed outbound IP, so binding one will get your orders rejected by Bitget

Bybit

1. Top-right avatar → API → Create New Key
2. Choose System-generated API Keys
3. Permissions: enable Contract Trade + Spot Trading
4. Do not enable Withdraw
5. Do NOT enable an IP whitelist — TVSBot has no fixed outbound IP, so binding one will get your orders rejected by Bybit

Gate.io

1. Log in → top-right avatar → API Management
2. Click "Create API Key" → pick a recognizable name (e.g., tvsbot)
3. 2FA / email verification
4. Permissions: enable Spot Trade + Perpetual Futures Trade
5. Do NOT enable Withdrawal — TVSBot can't check Gate.io's withdraw permission automatically, so please double-check this yourself
6. Do NOT enable an IP whitelist — TVSBot has no fixed outbound IP. (For the record, Gate's rule is that with an IP whitelist enabled, withdraw permission cannot be enabled at the same time.)
7. After saving, the system gives you the API Key + Secret — paste into the dashboard

Official guide: Gate.io API Key setup ↗

BingX

1. Log in → top-right avatar → API Management
2. "Create API Key" → pick a name (e.g., tvsbot)
3. 2FA / Google Authenticator verification
4. Permission selection: enable Read + Perpetual Trade + Spot Trade
5. Do NOT enable the "Withdraw" option
6. Do NOT enable an IP whitelist — TVSBot has no fixed outbound IP, so binding one will get your orders rejected by BingX
7. After saving, copy the API Key + Secret into the dashboard

Official guide: BingX Open Platform ↗

Hyperliquid (DEX Perpetual)

1. Sign up using our link → app.hyperliquid.xyz/join/TVSBOT ↗ (you can complete the "Verify Hyperliquid" task for a 4-day trial)
2. After logging in, go to More → API
3. Click Generate API Wallet → the system gives you a new wallet address + private key
4. Authorize from the main wallet by signing "Use this API wallet to trade"
5. Save: API wallet address and API wallet private key (**NOT the main wallet's**)
6. When adding the API key in TVSBot, choose Hyperliquid and paste the two values above

⚙ Perpetuals: Position Mode / Leverage / Margin

If you only trade spot, you can skip this section. But if you want to run perpetual strategies with TVSBot, read this section once — getting "position mode" wrong means the exchange will silently reject signals or place them in the wrong position.

What is "position mode"?

The three major exchanges all have two position modes:

• One-way mode: each contract can only hold one directional position. Sending a sell signal while a long is open = close long. TVSBot assumes this mode by default — signal logic is most intuitive; strongly recommended for beginners.
• Hedge mode: the same contract can hold long + short simultaneously, and orders must explicitly specify positionSide=LONG/SHORT. Suitable for hedging or grid strategies; but with TVSBot you must specify positionSide explicitly in the webhook, otherwise the exchange will return "position side does not match."

Position mode setting locations per exchange

• Binance Futures: top-right avatar → Preference → Position Mode → choose One-way Mode. Cannot switch while a position is open; close first.
• OKX: top-right avatar → Trade settings → Position Mode → choose One-way Mode. Isolated / Cross is a separate setting.
• Bitget: trade page top-right "Settings" gear → Position Mode → choose One-way Mode.
• Bybit: top-right settings → Position Mode → choose One-Way Mode.

Leverage

A strategy can set leverage: 5 in the webhook payload — TVSBot will call set_leverage before placing the order. Notes:

• Maximum leverage differs per trading pair (BTC is usually highest; altcoins lower). Exceeding the limit will be blocked.
• Risk settings have a "max allowed leverage" (default empty = no cap, uses the leverage from your webhook). If you set a number as a cap, signals above it are lowered to the cap before ordering. Note: lowering leverage also shrinks the notional, which can drop it below the exchange's minimum order size.
• Changing the leverage of an existing position requires closing it first on some exchanges.

Margin mode

• Cross: the entire wallet serves as margin — less likely to be liquidated, but risks are interlinked. TVSBot defaults to cross.
• Isolated: only the specified margin per trade is used; liquidation only loses that single position. Add margin_mode: "isolated" in the payload to switch.

Position sizing: how to choose among the five qty_type options

• ⭐ margin_usdtmargin_usdt (most intuitive for perps, recommended): you post X USDT as margin, the system multiplies by leverage to get notional. Example: qty=20, leverage=3 → margin $20, position $60 (matches the intuitive "I'm using $20 at 3x leverage").
• margin_pct: common for perpetuals. Use N% of USDT balance as "margin" combined with leverage to open a position. Example: 1000 USDT × 10% × 5x = a long with 500 USDT notional value. Differs from margin_usdt in "% vs $".
• fixed: hard-coded quantity (e.g., 0.01 BTC). Simple, but can't adapt as balance changes.
• percent: percentage of USDT balance (10 = 10%). Suitable for steadily compounding spot strategies.
• ⚠️ usdtusdt (advanced: direct notional): qty IS the position notional. **Leverage only affects margin requirement, does NOT amplify position.** Example: qty=20, leverage=3 → position $20, margin ~$6.67. If unsure about perp mechanics, use margin_usdt.

📦 Webhook Signal Format (payload)

The content of TradingView Alert's Message field must be valid JSON, with the following fields:

{
  "secret": "your webhook secret",
  "strategy": "strategy name (must match the one in the dashboard)",
  "action": "buy" | "sell" | "close",
  "symbol": "BTCUSDT",
  "exchange": "binance" | "okx" | "bitget" | "bybit",
  "market_type": "spot" | "futures",
  "order_type": "market",

  // Position sizing: pick one format
  "qty_type": "fixed" | "usdt" | "percent" | "margin_pct",
  "qty": 0.01,              // value corresponding to qty_type

  // Or use margin_pct shorthand (futures only; auto-treated as qty_type=margin_pct)
  "margin_pct": 10,         // Use 10% of balance as margin

  "leverage": 5,            // futures only
  "margin_mode": "cross",   // futures only, defaults to cross

  "tp_price": null,
  "sl_price": null,
  "tp_pct": null,           // percentage form (based on entry price)
  "sl_pct": null,
  "reduce_only": false,     // auto-set to true on close
  "comment": "log-only field"   // pure record field, does not affect execution
}

Required: secret / strategy / action / symbol / exchange, plus one of the following position sizing formats:

• qty_type="fixed" + qty (e.g., 0.01 BTC)
• qty_type="usdt" + qty (e.g., 100 USDT equivalent)
• qty_type="percent" + qty (e.g., 10 means 10% of USDT balance)
• qty_type="margin_pct" + qty + leverage (most common for perpetuals)
• margin_pct shorthand (auto-equivalent to qty_type=margin_pct)

Other fields have defaults. The dashboard's "📋 TV Template" button auto-fills everything.

Three values for action: buy / sell / close

• buy: open long / add to long position
• sell: open short / add to short position (on spot, sells the asset)
• closeclose position. The system will automatically fetch_positions to find the current position for that symbol and send a reverse reduce_only order. No position = noop, no error. Futures only (spot has no position concept).

Auto take-profit / stop-loss (TP/SL)

After the main order fills, the system automatically places two reduce_only conditional orders: take_profit_market (take-profit) + stop_market (stop-loss). Futures only; spot will skip.

• tp_price / sl_price: absolute price (e.g., BTC 72000)
• tp_pct / sl_pct: percentage based on entry price (e.g., tp_pct=2 means take-profit at +2% of entry; buy BTC@70000 → TP at 71400)
• Absolute price takes precedence; if both are given, absolute price wins.
• Failure on one side does not affect the other (e.g., SL succeeds but TP fails). Failure reasons appear in the bracket section of the signal detail page.

Trailing stop

trailing_stop_pct: as price moves favorably, the stop-loss point follows and locks in profit; if price moves unfavorably, it stays at the current high (long) or low (short). Example:

• Buy BTC@70000 with trailing_stop_pct=2 → initial stop at 68600
• Price rises to 75000 → stop trails up to 73500
• Price falls back to 73500 → triggers close, actual exit ~73500
• Currently only supported on Binance Futures (callback rate range 0.1-5%). Other exchanges will be supported later.
• Mutually exclusive with sl_pct / sl_price; if both are set, trailing wins (two stop-losses will not be placed).

🔧 Troubleshooting

"Strategy not found"

Signal received but rejected. Reason: payload's strategy doesn't match the strategy name on the dashboard. Check case, whitespace, and traditional/simplified characters.

"secret error" (401)

The payload's secret doesn't match your profile's webhook_secret. Re-copy from "Strategy → 📋 TV Template."

"invalid webhook token" (401)

The token in the URL is invalid. Check whether the webhook URL was copied completely — commonly the URL is missing characters at the end.

"Authentication failed" (when placing orders)

The ccxt call to the exchange was rejected. Usually because:

• The API key has been revoked on the exchange side
• The API key has an IP whitelist enabled (TVSBot has no fixed outbound IP — please turn the whitelist off)
• The API key lacks Trade permission

"Insufficient balance"

Literally what it says. Check your exchange account balance.

"Invalid JSON / payload" (400)

The message TradingView sent isn't valid JSON. Common causes:

• Smart quotes (“ ”) instead of straight " — IME / auto-correct mangled the template. Re-copy from dashboard.
• Missing or trailing commas inside the JSON
• TV variables like {{strategy.order.action}} used without quotes (must be a string)

The signals page shows the raw payload — paste it into jsonlint.com to validate.

"Missing required field" (422)

Payload missing a field or field name typo. Required fields:

action (buy / sell / close), symbol, qty_type, qty. Futures also need leverage and market_type=futures.

How do I check the webhook is reachable?

On the strategies page, hit the "🔔 Ping test" button. The system fires a dry-run signal at your webhook. Within ~15s a row with validation_status=test should show up on the signals page — that confirms the full chain works.

No signal received at all

Possibilities:

• TradingView Alert wasn't configured with a Webhook URL (only browser notifications were set)
• Webhook URL was typed incorrectly (extra whitespace, missing characters)
• The TradingView Alert has expired or was deleted
• The strategy itself isn't triggering signals

Check the "Signals" page for any records. If there are no records at all, the issue is on the TradingView side.