Common Exchange Setup — Universal Workflow
Regardless of which exchange you use, the connection flow is the same four steps. This page covers the pattern so each exchange-specific page can focus on what's actually different (permissions, passphrase, symbol format).
- Four steps: create key on exchange → add to TVH → set webhook URL in TradingView → verify
- Grant Read + Trading permissions. Never grant Withdraw.
- Tick Demo Account for Binance Spot, Binance Futures USD-M, Bybit (Spot + Futures), and OKX. For BitMex (and Binance Coin-M), use the separate testnet identifier instead.
- Sub-account routing happens via the
apiKeyfield (named API-key selection in TVH). Create one TVH API key per exchange sub-account, give each a descriptive name, and reference the name insignal.apiKey.
The 4-step universal flow
Step 1 — Create an API key on the exchange
Each exchange's UI is slightly different, but the inputs are always the same:
- Log in to your exchange account.
- Navigate to API Management / API Keys.
- Create a new key with a recognisable name like
tvh-botortvh-spot. - Restrict the key by IP — paste TVH's IP whitelist (see Webhook URLs & IP Whitelist). On Bybit, OKX, and KuCoin this step is replaced by third-party API binding — no IP whitelist needed.
- Grant the right permissions (see table below).
- Copy the Key, Secret, and Passphrase if the exchange requires one (OKX, KuCoin, Coinbase Advanced).
Per-exchange screenshots: Binance, Bybit, OKX, KuCoin, Coinbase, BitMex.
Step 2 — Add the key to TVH
Open Account → Settings → API Keys in TVH, then click Add API Key. Fill the universal form:
| Field | What to enter |
|---|---|
| Name | Free-text label, shown everywhere in TVH (e.g. binance-main) |
| Exchange | Dropdown — pick the identifier (e.g. binance, binance-futures, okx) |
| API Key | Public key from the exchange |
| API Secret | Secret/private key from the exchange |
| Passphrase | OKX, KuCoin, and Coinbase Advanced require this — paste yours |
| Demo Account | Tick to route this key to the exchange's paper-trading endpoint (Binance Spot, Binance Futures USD-M, Bybit Spot, Bybit Futures, OKX) |
| Sub-Account | Free-text label for your reference (e.g. binance-scalper-sub1). To route trades to a specific sub-account, create one TVH API key per sub-account (using the sub-account's exchange API key + secret) and select it via signal.apiKey in your TradeCommand |
Save. The key is encrypted at rest and used by the Functions backend at execution time.
Full UI walkthrough: Account & API Keys.
Step 3 — Set the webhook URL in your TradingView alert
When you create a TradingView alert, paste the right URL into the Webhook URL field:
Default endpoint — for every exchange except Binance (Spot + Futures):
Binance endpoint — for binance (Spot), binance-futures (USD-M), binance-futures-coin, and their testnets. The TVH UI auto-selects this URL when you pick a Binance identifier in the API Keys form:
Each endpoint also has a Classic variant that skips the queue for lower latency (no retry, no dedup). See Webhook URLs & IP Whitelist.
Step 4 — Place a trade and verify
Fire your alert (or use the Trade Command Builder UI). Then check three places:
- Activity Log in TVH — the signal must show
Status: Success. - Exchange wallet / positions — confirm the order landed in the right account (live vs demo, main vs sub).
- TradingView alert log — the alert must have fired with the right body.
If any of these is missing, jump to the Common errors section below.
Permissions to grant (and NOT to grant)
This table applies to every exchange. The exact label varies (e.g. Binance says "Enable Spot & Margin Trading", Bybit says "Trade"), but the intent is identical.
| Permission | Grant? | Why |
|---|---|---|
| Read / View | ✅ Always | TVH needs to read balance, positions, order status |
| Spot Trading | ✅ If you trade spot | Place / cancel spot orders |
| Futures Trading / Derivatives | ✅ If you trade futures | Place / cancel futures orders |
| Margin Trading | ⚠️ Optional | Only if you intentionally use spot margin |
| Withdraw | ❌ NEVER | TVH never withdraws. If the key leaks, the attacker still can't drain funds. |
| Internal Transfer (between sub-accounts) | ⚠️ Optional | Needed for some sub-account flows |
The single most important security rule. TVH does not need it, and granting it turns a leaked key into a fund-drain risk. Every exchange page in this chapter repeats this — it's that important.
IP whitelist setup
Not every exchange needs an IP whitelist. Some — Bybit, OKX, and KuCoin — support third-party API binding, where you authorise TVH directly while creating the key, so the connection is already scoped and no IP whitelist is required. Exchanges without binding (Binance, Coinbase, BitMEX) rely on IP restrictions instead.
Where the exchange uses IP whitelisting, you should set it. TVH publishes a stable list of IPs per webhook endpoint:
- Copy the IPs from Webhook URLs & IP Whitelist.
- In the exchange's API-key edit page, paste them into the IP-restriction field (newline-separated on most exchanges; comma-separated on Binance).
- Save — the restriction takes effect immediately.
Two IP sets exist: one for alerts.tv-hub.org, one for binance.tv-hub.org. Pick the one matching your exchange.
Demo Account checkbox — explained
The Demo Account checkbox on the TVH API-key form does one thing: it routes this key's orders to the exchange's paper-trading endpoint instead of live.
| Exchange | Demo behaviour |
|---|---|
Binance Spot (binance) | ✅ Demo Account checkbox — routes to Binance's paper-trading endpoint |
Binance Futures USD-M (binance-futures) | ✅ Demo Account checkbox — routes to Binance's paper-trading endpoint |
Binance Futures Coin-M (binance-futures-coin) | ❌ Use the binance-futures-coin-testnet identifier instead — no demo path for Coin-M |
| Bybit Futures + Spot | ✅ Demo Account checkbox — routes to Bybit's demo-trading endpoint |
| OKX | ✅ Demo Account checkbox — routes to OKX's demo-trading endpoint |
| BitMex | ❌ Use the bitmex-testnet identifier instead |
| KuCoin / Coinbase | ❌ No demo path supported in TVH |
Critical detail: the rest of the setup is identical. Same exchange identifier in the TradeCommand, same symbol format, same webhook URL. Only the route on the exchange side changes.
See Account & API Keys — Demo Account for the full table.
Sub-Accounts
Sub-account routing in TVH happens via the named apiKey field: each TVH API key holds the exchange credentials of one specific (sub-)account, and TVH matches your TradeCommand's apiKey value against the name of that key. To trade a sub-account, you point at the API key that belongs to it.
The recommended pattern: create one TVH API key per exchange sub-account (using the sub-account's own exchange API key + secret), give each TVH key a descriptive name, and reference the name in signal.apiKey:
{
"token": "...",
"exchange": "binance-futures",
"apiKey": "binance-scalper-sub1",
"pair": "BTCUSDT",
"isMarket": true,
"isBuy": true,
"units": 0.01
}
Per-exchange notes for sub-account API-key generation:
| Exchange | Sub-account model |
|---|---|
| Binance | Generate the sub-account's own API key from the master UI (or log in directly as the sub-account); add it to TVH with a name like binance-sub1 |
| Bybit | Generate a sub-account-scoped API key under your UTA master; add it as a separate TVH key |
| OKX | Trading sub-accounts each get their own API key — add each one separately |
| KuCoin | API-key-per-sub-account is the cleanest path (master-with-sub-permission also works) |
| Coinbase / BitMex | ❌ No sub-account flow in TVH |
If apiKey is empty or omitted, the order goes to whichever TVH key matches the exchange identifier — usually your master.
Common errors
| Symptom | Cause | Fix |
|---|---|---|
401 Unauthorized / "Invalid token" | Wrong TVH user token | Re-copy token from Account → Settings |
| "API key not found" | apiKey doesn't match a TVH key name | Match the TVH key label exactly, including case |
-2015: Invalid API-key, IP, or permissions for action | Wrong/missing IP whitelist on the exchange key — often the default IP set was allowed when the key needs the Binance set | Whitelist the correct TVH IPs: Binance uses the Binance set, everything else the default set. See Webhook URLs & IP Whitelist |
Invalid Sign (OKX/KuCoin) | Missing or wrong Passphrase | Paste the passphrase you set when creating the key |
invalid_key / invalid_signature | Whitespace or a missing char in key/secret | Re-copy and re-paste both fields in TVH |
| "Insufficient balance" / "Insufficient margin" | Wallet, size, or leverage issue | Top up the right wallet (Spot vs Futures vs sub-account), or reduce size/leverage; confirm the key has trade permission |
| "Unknown symbol" / "Invalid instrument" | Wrong symbol format (BTCUSDT ≠ BTC/USDT) | See Symbol format reference |
-4061: Order's position side does not match user's setting | Account hedge/one-way mode doesn't match the trade | Match the account mode, or set hedge mode. See Hedge Mode |
| No Activity Log entry at all | Wrong webhook URL | Re-copy the URL from Webhook URLs & IP Whitelist |
| Ran in demo but you wanted live | Demo Account flag is ticked | Edit the key in TVH and untick |
| Order goes to the wrong (sub-)account | apiKey field missing or misspelled | Add "apiKey": "<exact-TVH-key-name>" to your TradeCommand |
For the full error-string reference and step-by-step triage, see Debug a Failed Alert.
Next steps
Pick your exchange and follow the family page: