tradingview-alert-builder

name	tradingview-alert-builder
description	Use when a user wants to auto-trade from TradingView through StrategyFactory - "build a strategy", "connect TradingView", "make the webhook JSON", "set up auto-trading on Bybit/Blofin/Toobit/WEEX/Bitunix", or when API keys need encrypting for a TradingView alert payload.

TradingView Alert Builder (StrategyFactory)

Generates the ready-to-paste TradingView alert JSON files and webhook URL for auto-trading through https://fastcloud.daviddtech.com. Credentials are encrypted server-side via POST /encryptor/. Plaintext keys never go into any file or alert.

The one command that does everything

SF_API_KEY="<key>" SF_API_SECRET="<secret>" [SF_PASSPHRASE="<pass>"] \
python3 scripts/build_tradingview_json.py \
  --exchange bybit --chart-symbol \
  --sizing usdt --amount 100 --leverage 10 \
  --tp 4 --sl 2 \
  --uid <exchange-uid> --verify \
  --name "my-strategy" --out-dir ./my-strategy

Pair source: --chart-symbol (recommended default) emits the {{ticker}} placeholder so each alert trades whatever chart it is set on. Alternative: --coin-pair BTCUSDT.P, sent VERBATIM; the user must match their exchange's exact format, we never rewrite it. Sizing alternative: --sizing tv uses the strategy's own order size via {{strategy.order.contracts}} (base-quantity mode; drop --amount). --include-signal-meta attaches {{timenow}}/{{close}} for traceability. TradingView substitutes these placeholders both in the alert Message box and inside Pine alert_message strings.

It affiliate-checks the UID, encrypts the keys (encryptor v2), verifies the key actually works (check_api_active + accountbalance), then writes long_entry.json, short_entry.json, close_long.json, close_short.json, alert_messages.pine, webhook_url.txt, and a personalized README.md with the TradingView setup steps. Run --help for all flags (multi-TP scale-outs, percent-of-wallet sizing, reduce alerts, Telegram notifications, absolute prices).

Workflow

1. Collect: exchange, coin pair, sizing (default: fixed USDT margin), leverage (platform default 7), TP/SL (percent from entry is right for TradingView; absolute prices only for fixed setups), exchange UID.
2. Credentials: pass via SF_API_KEY/SF_API_SECRET env vars (plus SF_PASSPHRASE, required for Blofin and WEEX). Never on the command line, never echoed, never written to disk in plaintext.
3. Run the script with --uid and --verify. Stop on any failure and surface event_id + reason verbatim. For test keys or when the user has no UID handy, use --skip-affiliate-check and omit --verify (the only network call left is the required POST /encryptor/).
4. Hand the user the output folder; the generated README.md explains both TradingView wiring options (4 separate alerts, or one Pine {{strategy.order.alert_message}} alert). Remind them webhook alerts need a paid TradingView plan (Essential or higher).

Contract facts (do not improvise; the baseline failure is invented fields)

Fact	Value
Trade endpoint	POST https://fastcloud.daviddtech.com/webhooks/<exchange>. NOT /<exchange>, NOT /webhook
Exchanges	bybit, blofin, toobit, weex, bitunix
Encrypt endpoint	POST /encryptor/ with {api_key, api_secret, passphrase?}, then use the *_new outputs with "encryptor": "2"
Symbol	coin_pair: {{ticker}} placeholder (chart mode, default) or BTCUSDT.P form (never exchange-native like BTC-SWAP-USDT)
Direction	position: "0" long entry, "1" short entry. Closes/partial exits use mode:"reduce_by_percent" with position as side selector ("3"/"5" long, "4"/"6" short) and reduce_percent ("100" = full close): it reads the live position size, is reduce-only, and a TP/SL race lands as a clean skipped:true
Sizing	qty + qty_in_percentage: "0" base qty, "1" % of wallet, "2" USDT margin
Leverage	buy_leverage/sell_leverage, 1-125. The webhook multiplies qty by leverage itself: "$100 at 10x" means qty:"100", never "1000"
TP/SL	Gate is force_tp:"1". TP = tp_3_price (+tp_3_size:"100"), SL = stop_loss_price. tp_type:"1" = values are % from entry. Bare take_profit/stop_loss fields are silently IGNORED. In multi-TP, the FINAL leg must ride in tp_3_*
Margin mode	margin_mode: "1" isolated, "0" cross. Inert unless ignore_margin:"0" is also sent
Flip / re-entry	exit_existing_trade:"1" closes the opposite side before entry. pyramiding:"1" blocks same-direction re-entry on Bybit ONLY; do not send it to other exchanges

Current platform limits (the script enforces these; do not bypass)

• Percent TP/SL (tp_type:"1") is not yet supported on Toobit/WEEX. Use --absolute-prices or no TP/SL there.
• Base-quantity (base/tv) sizing with percent TP/SL is Bybit-only.
• Multi-TP scale-outs are not yet supported on Blofin/Bitunix. Bybit is the reliable multi-TP exchange.

Hard rules

• Plaintext API keys never go into JSON files, chat output, logs, or argv. The script aborts if a plaintext credential would reach an output file.
• If the affiliate check fails, stop and give the exchange's signup link (the script prints it; Bitunix has no public link, point at support).
• Never invent field names. If a parameter isn't in the table above or in --help, it does not exist. Check claude-skills/strategyfactory-webhook.md before adding anything.
• These files place real-money trades. Tell the user to fire one test alert with a small size and check the exchange before trusting a live strategy.

Common mistakes

Mistake	Reality
URL fastcloud.daviddtech.com/bybit or /webhook	Only /webhooks/bybit is a direct trade route; anything else falls into the queued fan-out handler and does nothing useful
take_profit: "4" / stop_loss: "2"	Ignored. Use tp_3_price/stop_loss_price with tp_type:"1" for percent
Pre-multiplying leverage into qty	10x oversized position; the webhook applies leverage
margin_mode:"0" for isolated	Inverted: "1" is isolated, "0" is cross (and it needs ignore_margin:"0" to apply at all)
Closing with static position 3/4 trade payloads	Use mode:"reduce_by_percent" + reduce_percent:"100" instead: it reads the live position size and is reduce-only on every exchange
One JSON with {{strategy.order.action}} in a position field	The service needs numeric position codes; use per-signal JSON files or Pine alert_message wiring
Absolute TP prices in a strategy alert	Entry price varies per signal; use percent mode where the exchange supports it