Signal bots
TradingView alerts and Telegram channel posts become Smart Trades.

01How a signal is handled

• Buy (or long) opens a long Smart Trade; sell (or short) opens a short on futures. On spot, sell closes the bot's open trades. Close (or exit) closes the bot's open trades on that symbol.
• Size: the signal's sizeQuote if given, but never more than the bot's maximum (by default its default size).
• Leverage: a signal may lower the leverage, never raise it above the bot's setting. Margin is isolated.
• Targets and stop: from the signal when it has them, otherwise from the bot's Smart Trade template (take-profits as % from the entry, stop %, trailing stop %, breakeven after a target).
• Entries: market, unless the signal text lists entry prices; then a limit ladder that times out after 24 hours.
• The same action on the same symbol within 10 seconds is treated as a duplicate and ignored (alerts are often sent twice).
• The signal goes through exactly the same checks as a Smart Trade typed in the app. A signal that fails them is not traded, and the reason is written to the bot's log.
• The bot must be running. A paused or stopped bot ignores signals and logs that it did.

02TradingView webhook

1. Create the bot. Signals, Create signal bot (or Bots, New bot, Signal). Choose the account and market, source tradingview, a default size and, on futures, the maximum leverage. Set the Smart Trade template used when the alert has no targets.
2. Start the bot.
3. Copy the webhook URL. Signals shows it with a Copy button: https://your-domain/api/hooks/<botId>/<secret>. Anyone with the URL can send signals to this bot, so do not share it.
4. In TradingView, create an alert, open Notifications, tick Webhook URL and paste the URL.
5. Paste the alert message (JSON) into the alert's message field. Signals shows a ready example.

Alert message (JSON)

{
  "action": "buy",
  "symbol": "{{ticker}}",
  "sizeQuote": "50",
  "tp": ["66000", "68000"],
  "sl": "62000"
}

A plain-text alert is also accepted: it is read by the signal parser (below). The webhook always answers 202 for a valid URL, so TradingView does not retry; what happened is in the bot log. The body is limited to 16 KB and each bot accepts up to 30 signals a minute.

03The signal parser

The parser reads free text such as a Telegram post: symbol, side, entry prices, targets, stop loss and leverage. It understands forms like "65k", "66,500", "TP1", "Targets", "Stop", "Lev 10x". It never guesses: anything uncertain lowers its confidence, and a bot trades only at confidence 0.5 or higher (server/src/signals/parser.ts).

Signals, Telegram signal parser: paste a post and press Preview to see exactly what a bot would read from it. When fields are missing, the preview says such a signal would be skipped and logged.

04Telegram channel signals

A Telegram signal bot trades the posts of one Telegram channel (not a group: in a channel only its admins can post). It needs the operator's Telegram bot (Create the bot) to be an admin of that channel, so it can read the posts.

To make sure nobody can point a bot at a channel they do not control, the channel is bound only after its owner posts a one-time code in it. The binding uses the channel's permanent numeric id, so a username that later changes hands cannot take it over. Posts older than 2 minutes are never traded (after downtime Telegram can replay up to a day of posts).

In version 1.0.0 the app's signal bot form has no field for the channel name, so a Telegram signal bot is created through the API (docs/API.md):

1. Add the operator's bot to your channel as an admin.
2. Sign in and find your account id.

   curl -s -X POST https://your-domain/api/auth/login -H 'content-type: application/json' \
     -d '{"email":"you@example.com","password":"your-password"}'        # add "totp":"123456" with 2FA on
   curl -s https://your-domain/api/accounts -H "authorization: Bearer TOKEN"

3. Create the bot with your channel's @username or numeric id:

   curl -s -X POST https://your-domain/api/bots -H "authorization: Bearer TOKEN" -H 'content-type: application/json' -d '{
     "type": "signal", "accountId": "ACCOUNT_ID", "symbol": "BTC/USDT:USDT", "marketType": "swap", "name": "My channel",
     "config": { "source": "telegram", "telegramChat": "@mychannel", "defaultSizeQuote": "50", "leverage": 3,
                 "smartTradeTemplate": { "takeProfits": [], "stopLossPct": "3" } } }'

   The answer contains telegramVerifyCode, for example KESTREL-AB12CD34.
4. Post that code in the channel. The channel is then bound to the bot. You can delete the post afterwards.
5. Start the bot in the app (Bots), or with POST /api/bots/<id>/start.

From then on each post the parser reads with confidence 0.5 or more opens a Smart Trade, exactly as a webhook signal would. The bot appears in the app like any other bot, with its log.