Docs

From zero to TradingView auto-trading — the complete guide. About a 10-minute read.

🚀 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. After logging in you land in the setup guide. Skipped it? Press "Continue setup" on the dashboard.
  3. Follow the 5-step guide. Pick an exchange → create an API key → paste it in → create a strategy (check "dry-run first") → send a 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.

Note:TradingView's free plan only allows 1 alert; paid plans starting at Essential allow 20+. If you want to run multiple strategies, consider upgrading TradingView.

🔑 API Key Setup for Each Exchange

🛑 Iron rule: NEVER enable Withdraw permission.
When you add a key we ask the exchange for its permissions: Binance, OKX and Bitget keys with Withdraw enabled are rejected, and a failed check doesn't let the key through either. We can't check Bybit, BingX or Gate.io automatically — please make sure Withdraw is not enabled.
📌 About IP whitelists: please don't enable one.
TVSBot's backend runs on Fly.io's shared egress and has no fixed outbound IP today, so there is no address we can give you to put in an exchange whitelist. Adding one will get your orders rejected intermittently or entirely. Reduce your risk these two ways instead: enable only the Trade (futures) permission and never Withdraw, and create the key on a sub-account. If we ever get a fixed outbound IP we'll show it on the API Keys page and update these docs.

Binance

  1. Open your Futures account before creating the key: a key created earlier, or on a Portfolio Margin account, can't get Futures permission.
  2. Profile icon → Account → API Management → Create API, choose System-generated, then pass 2FA.
  3. Edit restrictions: tick Enable Reading and Enable Futures.
  4. Paste the API Key and Secret Key here.

Turn on: Enable Reading, Enable Futures

Never turn on: Withdrawals, and any transfer permission.

Leave the IP allowlist empty (no fixed IP). A key with no IP bound can only read; if Enable Futures can't be ticked, follow Binance's guide below.

Binance official guide ↗

OKX

  1. Trading page menu → Account mode: pick any mode except Spot mode (needed for futures).
  2. Profile → API (API and connections) → Create API key.
  3. Permissions: tick only Read and Trade.
  4. Set your own passphrase and write it down; OKX won't show it again.
  5. Paste the API Key, Secret and Passphrase here.

Turn on: Read, Trade

Never turn on: Withdraw, Transfer, Loan, Earn.

The passphrase is one you set when creating the key, not your OKX login password. If you lose it, create a new key.

Leave the IP allowlist empty: TVSBot has no fixed outbound IP yet.

A key with Trade permission and no IP bound is deleted by OKX after 14 days without use.

OKX: connect a third-party bot ↗ · OKX API FAQ ↗

Bitget

  1. Finish identity verification (KYC) and turn on Google Authenticator first.
  2. Profile icon → API Key → Create API key, choose System-generated.
  3. Set a passphrase (8–32 letters or numbers) and write it down.
  4. Choose Read-Write, then enable futures trading in the API permissions.
  5. Paste the API Key, Secret and Passphrase here.

Turn on: Read-Write + futures trading

Never turn on: Withdraw, Transfer.

You set the passphrase when creating the key; Bitget won't show it again. If you lose it, create a new key.

Leave the IP allowlist empty: TVSBot has no fixed outbound IP yet.

Bitget API Key management page ↗

Bybit

  1. Use the website (keys can't be created in the Bybit app) and turn on Google Authenticator first. New accounts may have to wait up to 48 hours.
  2. Profile icon → API → Create New Key.
  3. Choose Read-Write and enable contract trading (orders and positions) in the API permissions.
  4. Paste the API Key and Secret here.

Turn on: Read-Write + contract trading (orders, positions)

Never turn on: Wallet permissions (transfer, withdraw); spot and other trading aren't needed.

Leave the IP allowlist empty: TVSBot has no fixed outbound IP yet.

Keys without a bound IP expire after 90 days. Before then, edit the key on Bybit's API page, keep No IP restriction and submit to extend it 90 days.

Bybit official guide ↗ · Bybit API management page ↗

Gate

  1. Finish account verification, set a fund password and 2FA first.
  2. Website profile icon → API Management → Create API Key, choose APIv4 Key.
  3. Choose Read and Write, and enable futures/contract trading in the API permissions.
  4. Accept the risk notice, enter your fund password and 2FA, then paste the API Key and Secret here.

Turn on: Read and Write + futures/contract trading

Never turn on: Withdrawals, wallet transfers.

Leave the IP allowlist empty: TVSBot has no fixed outbound IP yet.

Keys without a bound IP are valid for 90 days. Note the expiry date.

Do NOT enable Withdrawal — TVSBot can't check Gate.io's withdraw permission automatically, so please double-check this yourself

Gate official guide ↗

BingX

  1. Open BingX's API Management page → Create API.
  2. Enable read and perpetual futures trading in the API permissions.
  3. Finish the exchange's verification, then paste the API Key and Secret here.

Turn on: Read + perpetual futures trading

Never turn on: Withdraw, Universal Transfer, sub-account management.

Leave the IP allowlist empty: TVSBot has no fixed outbound IP yet.

A key with trading permission and no IP bound is deleted by BingX after 14 days with no API calls.
BingX note: BingX's contract symbols follow the same convention as Binance — BTC-USDT with a hyphen. Payload using BTCUSDT also works; the system converts automatically.

BingX API management page ↗

Hyperliquid (DEX Perpetual)

⚡ Hyperliquid is not a CEX — authentication differs from the other 6: it uses wallet signing instead of API key + secret. We recommend the "API Wallet" mechanism (sub-account mode) — your main wallet authorizes a dedicated wallet to trade; even if the private key leaks, it can only trade and not withdraw, limiting the blast radius.
  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
Hyperliquid note:
1) Symbols use BTC / ETH instead of BTCUSDT — ccxt unified format BTC/USDC:USDC also works.
2) Perpetuals (perp) only. Before placing an order, confirm your webhook market_type=futures.
3) No KYC, no deposits to the exchange — wallet signing trades directly (USDC stays on your own chain).
4) To learn about API Wallet security design: official API Wallets docs ↗.
Haven't opened accounts on these exchanges yet? Go to the dashboard API key page. When you add a key and pick the exchange, its sign-up link appears.

⚙ 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."
Strong recommendation: before running perpetuals with TVSBot, switch position mode on the exchange to "One-way mode."
If you insist on Hedge mode, add the corresponding parameters in the TV alert payload, and understand that our current close logic does not specifically handle Hedge mode (will be supported in Phase 2).

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.
  • Differences by exchange: on OKX, Bitget and Binance, margin_mode sets the margin mode of the pair (if setting it fails, the open is not sent); Gate perpetuals are always isolated, so margin_mode has no effect on Gate; Bybit always uses the margin mode set in your own Bybit account (TVSBot never changes account-level settings) — to trade isolated, set it on Bybit yourself and leave margin_mode out of the signal (an open with isolated is refused). Closing is not affected by margin_mode.

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.
  • TP/SL is not verified yet on OKX / Gate / Bybit / Bitget: a futures open that carries TP/SL parameters is refused as a whole on those four exchanges (it is not sent; closes and reduce-only orders are unaffected) — set TP/SL on the exchange instead.
  • A close signal does not cancel these TP/SL / trailing orders: they stay open on the exchange after the position is closed and can trigger on a later position, so cancel them yourself on the exchange after you close. The template library and the TV template builder do not offer these fields for now.

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: a futures open that carries trailing_stop_pct on another exchange is refused as a whole (it is not sent).
  • 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.

Can't find the answer? Email hello@tvsbot.com with your signal ID (visible on the dashboard signals page), and we'll investigate for you.