Signal Syntax
The complete list of what an alert message can contain. Most people never need this page - the Alert Builder writes the message for you. It is here for people who write their own messages or Pine Script alert_message strings.
In simple words
A message is a list of "name: value" pairs between curly brackets. Three of them are needed (license key, action, symbol); everything else is optional. A field that is not on this page is ignored.The smallest message
minimal buy
{ "licenseKey": "TB-XXXXXXXX-XXXXXXXX-XXXXXXXX", "action": "buy", "symbol": "EURUSD" }Without a size the EA trades 0.01 lot. Send it to https://app.tradehookx.com/webhook.
Required fields
| Field | Meaning |
|---|---|
| licenseKey | The license key of the terminal that should trade (also accepted as license_key). |
| action | What to do - see Actions below. For strategies use {{strategy.order.action}}. |
| symbol | What to trade, e.g. XAUUSD or {{ticker}}. Only closeall may leave it out (then it closes on every symbol). |
Actions
| action | What the EA does |
|---|---|
| buy / sell | Open a buy or a sell at market price. |
| buylimit / selllimit | Pending order at "price": buy below / sell above the current price. |
| buystop / sellstop | Pending order at "price": buy above / sell below the current price (breakout). |
| closelong / closeshort | Close buy / sell trades on the symbol with the same magic - all, or only "close_lots". |
| closeall | Close buys and sells on the symbol (or on every symbol without one) with the same magic. |
| cancel | Delete pending orders on the symbol with the same magic. |
| closelongvol / closeshortvol | Close this many lots of the buys / sells (oldest first). Lots from "close_lots" (or "volume", "size", "lots"). |
| closelongpct / closeshortpct | Close this % of the buys / sells. Percent from "close_pct" (or "percent", "size"), 1-100. Rounded down to the lot step, at least one step; 100 closes all. |
| newsltplong / newsltpshort | Set a new stop loss and/or take profit on the open buys / sells (same magic). Uses "sl" / "tp" with their types. |
| {{strategy.order.action}} | TradingView puts "buy" or "sell" here each time your strategy trades. |
The vol / pct / newsltp actions need EA v2.27 or newer
These names match PineConnector, so alerts made for it work here too. On a terminal with an older EA they are refused with "needs TradeHookX EA v2.27" - update the EA, or use closelong / closeshort with close_lots.close half of the gold buys of strategy 5151
{ "licenseKey": "TB-...", "action": "closelongpct", "symbol": "XAUUSD", "close_pct": 50, "magic": 5151 }move the stop loss of the gold sells to 1% from entry
{ "licenseKey": "TB-...", "action": "newsltpshort", "symbol": "XAUUSD", "sl": 1, "sl_type": "percentage_distance" }Size
| Field | Meaning | Example |
|---|---|---|
| size (or lots) | How big the trade is. | "size": 0.05 |
| size_type | "units" (default) = lots, or contracts when lot_multiplier is set. "percentage" (or "risk") = risk % of the balance - needs "sl". With EA v2.38 the stop can be in pips, percent or a fixed price; older EAs accept pips only. If the terminal cannot get the symbol's tick value within about a second, EA v2.39 refuses the trade and says why; it does not guess a size. | "size_type": "percentage", "size": 1 |
| lot_multiplier | Contracts × multiplier = lots. For strategies that send contract counts. | "lot_multiplier": 0.0001 |
| risk | Same as size_type percentage: lose this % of the balance if the SL is hit. | "risk": 1 |
| close_lots | For closes: how many lots to close, oldest trades first. Leave out = close all that match. | "close_lots": 0.04 |
Sizes are rounded to your broker's lot step and kept between its minimum and maximum lot.
Stop loss and take profit
| Field | Meaning |
|---|---|
| sl / tp | The value. How it is read depends on sl_type / tp_type. |
| sl_type / tp_type | "price_distance" (default) = pips from entry · "percentage_distance" = % of the entry price · "fixed_price" = the exact level. |
| price | The order price for buylimit / selllimit / buystop / sellstop. |
| max_spread | Refuse the new trade while the spread is wider than this many pips (1 pip = 10 of the symbol's smallest price steps). Wins over the terminal's Max spread and works even with that filter off. Not passed on to copy followers. Needs EA v2.36. |
| alert_id | Optional. A second alert with the same id on this license within 24 hours is ignored, so a re-sent alert cannot open a second trade. Give every real order its own id, for example {{strategy.order.id}}-{{timenow}}. Without it, every alert runs. |
| expiry_hours | Pending orders only: cancel the order if it is not filled after this many hours (0-720, 0 = never). Without it the terminal's Default expiry is used. |
buy with SL and TP in pips
{ "licenseKey": "TB-...", "action": "buy", "symbol": "EURUSD", "size": 0.1, "sl": 20, "tp": 40 }gold with SL and TP as a percentage
{ "licenseKey": "TB-...", "action": "buy", "symbol": "XAUUSD", "size": 0.01,
"sl": 0.5, "sl_type": "percentage_distance", "tp": 1, "tp_type": "percentage_distance" }What is a TradeHookX pip?
One pip = 10 × the symbol's smallest price step (its "point"), on every symbol. That is the normal pip on forex, but much smaller on other markets:
| Symbol (typical broker) | Smallest step | 1 TradeHookX pip | 100 pips = |
|---|---|---|---|
| EURUSD (5 digits) | 0.00001 | 0.0001 | 0.0100 (100 normal pips) |
| USDJPY (3 digits) | 0.001 | 0.01 | 1.00 |
| XAUUSD gold (2 digits) | 0.01 | 0.10 | $10 of price |
| BTCUSD (2 digits) | 0.01 | 0.10 | $10 of price |
| US100 index (2 digits) | 0.01 | 0.10 | 10 index points |
Brokers differ - check the digits of your symbol in MT5. For gold, crypto and indexes the percentage type is usually easier.
Multiple take profits, breakeven, trailing
| Field | Meaning |
|---|---|
| tp1, tp2, tp3 | Take-profit distances in pips. |
| tp1_lots, tp2_lots, tp3_lots | Lots to close at each level. |
| be_after_tp1 | true = move the stop loss to the entry price when TP1 is hit. |
| be_after_tp2 | true = move the stop loss to the TP1 price when TP2 is hit. |
| breakeven_trigger (or be_trigger) | Pips of profit after which the stop moves to entry. |
| breakeven_offset (or be_offset) | Pips above entry for that stop (default 2). |
| trailing_stop | Trailing distance in pips. |
| trailing_step | Pips the price must move before the stop moves again (default 5). |
| trailing_activation | Pips of profit before trailing starts. |
three take profits with breakeven
{
"licenseKey": "TB-...", "action": "buy", "symbol": "XAUUSD", "size": 0.03, "sl": 300,
"tp1": 200, "tp1_lots": 0.01, "tp2": 400, "tp2_lots": 0.01, "tp3": 600, "tp3_lots": 0.01,
"be_after_tp1": true, "be_after_tp2": true
}Routing and behaviour
| Field | Meaning |
|---|---|
| magic | A number stamped on the trade. Closes, cancels and close-opposite only touch trades with the same magic. Leave out = the EA default (20240202). On a terminal that leads a copy group it must be that group's magic. |
| execution_mode | "close_opposite" (smart netting), "flip" (close all, reverse) or "mt_native" (just open). Unknown values become mt_native. See Closing Trades. |
| comment | Text stored on the order (max 100 characters; MT5 shows about 31). |
| strategy | A 3-letter tag. Only used by local EAs whose StrategyTag input is set: they ignore entries with another tag. |
| tv_username | Your TradingView username - required once TradingView binding is active (also accepted as username). |
Plain-text messages
Instead of JSON you can send comma-separated text: license key, action, symbol, then name=value pairs.
text signal
TB-XXXXXXXX-XXXXXXXX-XXXXXXXX,buy,EURUSD,lots=0.05,sl=20,tp=40,magic=5151Good to know
- •Field names are case sensitive in JSON: "licenseKey", not "LicenseKey".
- •Numbers can be written with or without quotes ("0.01" or 0.01).
- •TradingView placeholders such as {{ticker}}, {{close}}, {{strategy.order.action}} and {{strategy.order.contracts}} are filled by TradingView before the message is sent.
- •An entry is executed only if it reaches the terminal within 30 seconds; a close within 55 seconds. Older signals end as "Signal expired".