ClearEdge Automation

Mastering TradingView Alert JSON Payload Structure for Futures Trading

Master the TradingView alert JSON payload structure for futures. Learn to use dynamic placeholders and broker-specific syntax to ensure your trades execute.

A TradingView alert JSON payload for futures trading is a structured message sent via webhook that tells your automation platform exactly what trade to execute. The payload includes required fields like symbol, action, quantity, and order type, plus optional fields for stops, targets, and authentication. Format depends on your broker, malformed JSON is the most common failure point.

Key Takeaways

Required JSON fields for futures alerts typically include symbol, action (buy/sell), quantity, order type, and an authentication token.
Broker-specific syntax varies: Tradovate, TradeStation, NinjaTrader, and AMP each expect slightly different field names and contract symbols.
Use TradingView's built-in placeholders like {{strategy.order.action}}, {{ticker}}, and {{close}} to build dynamic payloads.
The most common errors are missing commas, unquoted strings, mismatched contract symbols (ES vs ESZ2025), and stale authentication tokens.
Always test payloads in a paper account before sending live orders, malformed JSON can fail silently or fire incorrect quantities.

What Is a TradingView Alert JSON Payload?

A TradingView alert JSON payload is a structured text message in JSON format that gets sent to a webhook URL when your alert fires. The payload tells the receiving automation platform exactly what to do: which contract, which direction, how many contracts, and what order type to use. Without a properly structured payload, your tradingview alert json payload structure for futures setup will either fail silently or send the wrong instructions to your broker.

JSON Payload: A JavaScript Object Notation message containing key-value pairs that describe a trade instruction. For futures automation, it acts as the bridge between a TradingView alert and broker order execution.

The payload sits in the "Message" box of your TradingView alert. When the alert condition triggers, TradingView posts that JSON text to the webhook URL you specified. Your automation platform parses the JSON, validates it, and routes the order to your broker. The whole process typically completes in 100-500ms depending on your platform and broker connection.

What Are the Required Fields for Futures Alert Payloads?

Every futures alert JSON payload needs at minimum: a symbol identifier, an action (buy or sell), a quantity, and an authentication token. Most platforms also require an order type field (market, limit, stop) and an account identifier when you trade multiple accounts.

Webhook URL: The unique HTTPS endpoint provided by your automation platform that receives JSON payloads from TradingView. Each platform issues a distinct URL tied to your account.

Here is a baseline payload structure for a futures market order:

{ "token": "your-auth-token-here", "symbol": "ES1!", "action": "buy", "quantity": 1, "order_type": "market", "account": "your-account-id" }

A few details matter for futures specifically. The symbol field needs to match what your broker expects, ES1! works in TradingView for the continuous front-month contract, but some brokers want ESZ2025 or /ES. Quantity refers to contracts, not shares. And the action field uses different conventions: some platforms use "buy"/"sell", others use "long"/"short" or "BUY"/"SELL" with specific casing.

Optional but Recommended Fields

stop_loss: Price level for protective stop
take_profit: Price level for profit target
time_in_force: GTC, DAY, IOC, FOK
price: Required for limit and stop orders
strategy_id: Tag to identify which strategy fired
comment: Free-text note for journaling

How Do Broker-Specific JSON Payloads Differ?

Each broker integration expects slightly different field names, symbol formats, and structural conventions. The core concept is the same, but the keys and values vary enough that a payload built for Tradovate will not work with TradeStation without modification. Confirm the exact format in your platform's documentation before going live.

Tradovate Example

{ "token": "abc123", "account": "DEMO12345", "symbol": "ESZ5", "action": "Buy", "orderQty": 1, "orderType": "Market" }

TradeStation Example

{ "token": "abc123", "account": "SIM123456", "symbol": "@ES", "action": "BUY", "quantity": 1, "orderType": "Market", "duration": "DAY" }

NinjaTrader Example

{ "token": "abc123", "account": "Sim101", "instrument": "ES 12-25", "action": "Buy", "quantity": 1, "orderType": "Market" }

The most common gotcha is symbol format. NinjaTrader uses contract month codes like "ES 12-25" while Tradovate uses "ESZ5" and TradeStation uses "@ES" for the continuous contract. Get this wrong and the order rejects at the broker level even if the JSON itself is valid. For ES, NQ, GC, and CL specifics, see our futures instrument automation guide.

How Do You Use Dynamic Placeholders in Alert Templates?

TradingView provides built-in placeholders that get replaced with live values when the alert fires. Using placeholders lets one alert template handle both long and short signals, multiple symbols, and dynamic price levels without hardcoding values.

Alert Template: A reusable JSON structure with TradingView placeholder variables that get substituted with real-time values at the moment the alert triggers. Templates reduce manual setup and prevent stale price data.

The most useful placeholders for futures automation:

{{ticker}} - Current symbol from the chart
{{close}} - Closing price of the bar that triggered the alert
{{strategy.order.action}} - "buy" or "sell" from a Pine Script strategy
{{strategy.order.contracts}} - Position size from your strategy
{{strategy.position_size}} - Current position size
{{time}} - Bar timestamp

A dynamic Pine Script strategy payload looks like this:

{ "token": "abc123", "symbol": "{{ticker}}", "action": "{{strategy.order.action}}", "quantity": {{strategy.order.contracts}}, "price": {{close}}, "order_type": "market" }

Notice that numeric placeholders like {{close}} and {{strategy.order.contracts}} are NOT wrapped in quotes. String fields like {{ticker}} and {{strategy.order.action}} ARE wrapped in quotes. Mixing these up is a frequent cause of failed alerts. For deeper Pine Script integration, our pine script automation guide walks through strategy alert setup.

What Are the Most Common JSON Payload Errors?

Most failed TradingView webhook alerts trace back to four issues: malformed JSON syntax, mismatched symbol formats, expired authentication tokens, and incorrect quoting around placeholders. Each fails differently, some throw obvious errors, others fire trades with wrong sizes.

Syntax Errors

JSON is strict. A missing comma, an extra trailing comma, or a single quote where a double quote belongs will reject the entire payload. Run your alert message through a JSON validator like jsonlint.com before saving the alert. Common offenders:

Trailing comma after the last field
Single quotes instead of double quotes
Unquoted string values
Quotes around numeric values when the platform expects integers

Symbol Mismatches

If your chart shows ES1! but your broker expects ESZ2025, the alert fires but the order rejects. Always confirm the exact contract symbol your broker accepts during the current month, then update your alerts before each rollover. First notice day and contract expiration timing matters here.

Authentication Failures

Tokens can expire, get rotated, or get pasted with extra whitespace. If alerts stop firing suddenly, the token is the first thing to check. Most platforms log rejected payloads with the reason, check your platform dashboard before assuming the alert never sent.

Quantity and Direction Bugs

The worst errors are the silent ones. A payload that fires a 10-contract order when you meant 1, or buys when you meant to sell. These usually come from copy-pasting templates without updating quantity, or from mixing up {{strategy.order.action}} with hardcoded "buy". Paper trade every new alert template for a week before risking live capital.

Troubleshooting Failed Alerts: The systematic process of checking webhook logs, validating JSON syntax, confirming symbol formats, and verifying authentication when alerts fail to execute. Most platforms provide a webhook log viewer to inspect rejected payloads.

How Should You Test JSON Payloads Before Going Live?

Test every payload in a paper account, then in a sim account at your broker, then with a single micro contract on live before scaling up. This three-stage validation catches JSON errors, broker-specific quirks, and unexpected strategy behavior at progressively higher cost levels.

A practical test sequence:

Validate the JSON syntax in a linter
Send a manual test payload through your platform's webhook tester
Connect to a paper account and trigger the alert with relaxed conditions
Switch to sim or demo at your broker, run for a few sessions
Move to live with MES or MNQ micros before scaling to ES or NQ

Document what failed at each stage. Most platforms keep a webhook activity log showing the raw payload received, parsing result, and broker response. That log is the first place to look when something breaks. For a complete walkthrough of webhook testing, the TradingView automation guide covers the end-to-end setup, and our webhook setup guide goes into platform-specific details.

Pre-Live Checklist

JSON validates without errors
Symbol matches broker's current contract month
Quantity is correct (start with 1 contract)
Authentication token is current
Stop loss and take profit values are realistic
Alert frequency is set appropriately (Once Per Bar Close usually)
Paper tested for at least 5 trading sessions

Frequently Asked Questions

1. What happens if my JSON payload has a syntax error?

The webhook receiver rejects the payload and no order is placed. Most automation platforms log the rejection with an error message, but TradingView itself does not validate JSON before sending, so you have to check your platform's webhook log to see what went wrong.

2. Do I need to wrap numeric values in quotes?

No, numeric values like quantity, price, and timestamps should be unquoted integers or decimals. Wrapping numbers in quotes turns them into strings, which some platforms accept and others reject depending on their parser strictness.

3. Can one alert send orders to multiple accounts?

Yes, if your automation platform supports multi-account routing. You either include an array of account IDs in the payload or configure the platform to mirror the order across linked accounts. Check your platform's documentation, since the syntax varies.

4. How do I include stop loss and take profit in the payload?

Add them as separate fields like "stop_loss": 5825.00 and "take_profit": 5845.00, using values calculated in your Pine Script. You can also use placeholder math like {{plot_0}} to pull values from indicator plots or strategy variables.

5. Why does my alert work in paper but fail in live?

Usually the symbol format differs between sim and live accounts, or the live account ID is different from the paper account ID in the payload. Double-check both fields, and confirm your token has live trading permissions enabled.

6. What TradingView plan do I need for webhook alerts?

Webhook alerts require at least the Essential plan (formerly Pro). Higher tiers like Plus and Premium offer more alerts per account, faster server-side execution, and longer alert expiration windows, which matters for multi-timeframe and high-frequency setups.

Conclusion

A correct tradingview alert json payload structure for futures comes down to matching your broker's exact field names, using proper JSON syntax, and validating every template before live trading. The required fields are predictable, but broker-specific details around symbols and casing trip up most new automation users.

Test in paper, then sim, then micros before scaling. Keep your webhook logs handy when something breaks, malformed JSON and stale tokens cause the majority of failures.

Want to dig deeper? Read our complete guide to TradingView automation for full webhook setup instructions, alert templates, and broker integration details.

References

Disclaimer: This article is for educational purposes only. It is not trading advice. ClearEdge Trading executes trades based on your rules, it does not provide signals or recommendations.

Risk Warning: Futures trading involves substantial risk. You could lose more than your initial investment. Past performance does not guarantee future results. Only trade with capital you can afford to lose.

CFTC RULE 4.41: Hypothetical results have limitations and do not represent actual trading.

By: ClearEdge Trading Team | About