TradingView's Signal Bot feature allows traders to publish and automate their trading strategies directly on OKX. This guide details the two primary alert message specifications you can use to connect your TradingView alerts to your OKX Signal Bot. The system intelligently parses your messages, ensuring a seamless experience whether you use Pine Script™ strategies or a more universal approach.
Understanding Pine Script™: Strategy vs. Indicator
Pine Script™ is TradingView's programming language for creating custom technical analysis tools. It's crucial to understand the difference between two main script types.
Pine Script™ Strategies are designed for backtesting and forward-testing trading ideas. They use special strategy.*() functions to place buy and sell orders into a broker emulator, which simulates trade execution. The results are displayed in the "Strategy Tester" tab. These scripts are ideal for developing and testing automated trading systems.
Pine Script™ Indicators (or "studies") perform calculations and display information on the chart but are not built for backtesting. They are computationally lighter and execute faster than strategies because they don't interact with the trade emulator.
You can use either the dedicated strategy format or the universal format; both are fully compatible with OKX Signal Bots.
Section A: For Pine Script™ Strategy Users
This specification is tailored for users who build their trading algorithms using Pine Script™'s strategy.*() functions. It seamlessly integrates TradingView's strategy-specific placeholder values, making it the ideal choice for a direct, streamlined connection.
Alert Message Parameters Overview
This table outlines the required and optional parameters for your alert message when using a Pine Script™ strategy.
| Parameter | Required | Values & Description |
|---|---|---|
| id | Required | {{strategy.order.id}} - The unique identifier for the executed order. |
| action | Required | {{strategy.order.action}} - Returns "buy" or "sell" for the order. |
| marketPosition | Required | {{strategy.market_position}} - The intended position state after order execution ("long", "flat", "short"). |
| prevMarketPosition | Required | {{strategy.prev_market_position}} - The position state before the order executed. |
| instrument | Required | The trading pair. Use {{ticker}} (e.g., BTCUSDT.P) or OKX's instId format (e.g., BTC-USDT-SWAP). |
| signalToken | Required | A unique authentication token provided by OKX when you create your signal. |
| timestamp | Required | {{timenow}} - The exact UTC time the alert fired (e.g., 2023-06-01T17:38:10Z). |
| maxLag | Optional | Maximum acceptable delay in seconds (1-3600). Default is 60. Signals older than this are ignored. |
| investmentType | Optional* | For entry signals: base, margin, contract, percentage_balance, percentage_investment. For exit signals: base, percentage_position. |
| amount | Required | The quantity for the order. Its meaning depends on the chosen investmentType. |
*If omitted, the system defaults to percentage_investment for entries and percentage_position for exits. For maximum compatibility with your strategy's intended order size, we strongly recommend setting investmentType to base and amount to {{strategy.order.contracts}}.
Detailed Parameter Specifications
1. ID Parameter
This field uses the {{strategy.order.id}} placeholder to pull the unique identifier from your strategy's order function, ensuring each signal is distinct.
2. Action Parameter
The {{strategy.order.action}} placeholder automatically populates this field with "buy" or "sell" based on the strategy's logic.
3. Market Position
This parameter, populated by {{strategy.market_position}}, tells the bot the state your strategy expects to be in after this order (e.g., "long").
4. Previous Market Position
Using {{strategy.prev_market_position}}, this indicates the state the strategy was in before this order was triggered.
5. Instrument Specification
You can define the trading instrument in two ways:
- TradingView Ticker: Use the
{{ticker}}placeholder for the symbol the alert is on (e.g.,BTCUSDT.P). - OKX Instrument ID: Use OKX's official instrument format (e.g.,
BTC-USDT-SWAP).
6. Signal Token Authentication
The signalToken is a critical security key generated by OKX when you create a signal. It authenticates all incoming messages. You can find this token in the "Details" section of your active signal on OKX. It must be copied into your TradingView alert message.
7. Timestamp for Signal Freshness
The {{timenow}} placeholder ensures every alert is stamped with a precise UTC timestamp. This allows OKX to calculate the signal's age and enforce the maxLag rule.
8. Managing Signal Delay with MaxLagMaxLag (default: 60 seconds) is a safety feature. It discards any signal where the difference between its timestamp and its arrival time at OKX exceeds this value. This prevents the bot from executing trades on stale data that may no longer be relevant.
9. Configuring Investment Type and Amount
This pair of parameters controls the order size. For the best results, use investmentType: base and amount: {{strategy.order.contracts}} to mirror your strategy's exact order quantities.
- For Entry Signals: Options include investing a specific amount (
base), a margin amount (margin), a number of contracts (contract), or a percentage of your available balance or active investment. - For Exit Signals: Options include closing a base amount or a percentage of the current open position.
👉 Explore more strategies for configuring your trade sizes
Section B: Universally Compatible Specifications
This format is designed for maximum flexibility. It works with Pine Script™ indicators (studies), manual alerts, or any other method of generating signals on TradingView. It uses a simplified set of clear action commands.
Alert Message Parameters Overview
| Parameter | Required | Values & Description |
|---|---|---|
| action | Required | ENTER_LONG, ENTER_SHORT, EXIT_LONG, EXIT_SHORT. |
| instrument | Required | The trading pair (Same formats as Section A). |
| signalToken | Required | Your OKX-generated authentication token. |
| timestamp | Required | {{timenow}} - The UTC time the alert fired. |
| maxLag | Optional | Maximum delay in seconds (1-3600). Default is 60. |
| orderType | Optional | market (default) or limit. |
| orderPriceOffset | Conditional | Required for limit orders. A percentage value [0, 100] defining the offset from the current price. |
| investmentType | Optional | Defines how the order size is calculated (see table below). |
| amount | Optional | The value corresponding to the chosen investmentType. |
Detailed Parameter Specifications
1. Action Commands
The bot operates in a one-way (buy/sell) position mode.
ENTER_LONG: Opens a long position (buy).ENTER_SHORT: Opens a short position (sell).EXIT_LONG: Closes all or part of an open long position (sell).EXIT_SHORT: Closes all or part of an open short position (buy).
2. Instrument Specification
Identical to Section A. Use {{ticker}} or OKX's instId format to specify the market.
3. Signal Token Authentication
Functions exactly as in Section A. This token is mandatory for authenticating your alerts with OKX.
4. Timestamp for Validation
The {{timenow}} placeholder is used to tag the alert with its creation time for latency checks.
5. Enforcing Timeliness with MaxLag
This parameter works the same way as in Section A, rejecting any signals that arrive after the specified delay threshold.
6. Order Type and Price Offset
- OrderType: Choose between
marketorders (executed immediately at the current market price) orlimitorders (executed at a specified price or better). OrderPriceOffset: Only used with
limitorders. This percentage value determines how far from the current bid/ask price the limit order is placed.ENTER_LONG: Price = [1 - (offset/100)] * Bid PriceENTER_SHORT: Price = [1 + (offset/100)] * Ask PriceEXIT_LONG: Price = [1 + (offset/100)] * Ask PriceEXIT_SHORT: Price = [1 - (offset/100)] * Bid Price
7. Investment Type and Amount Logic
These optional parameters give you control over trade sizing. If you omit them, the bot uses its default configuration: entering with 100% of available balance for single-pair bots or 50% for multi-pair bots, and exiting 100% of the position.
- For Entry Signals: You can specify size by margin, contracts, or a percentage of balance/investment.
- For Exit Signals: You can specify to close a percentage of the open position.
👉 Get advanced methods for manual alert configuration
Practical Examples and Precedence
Multi-Entry Feature: Signal Bot supports multiple entry points for a single instrument, allowing for strategies like Dollar-Cost Averaging (DCA).
Field Precedence Rules: When settings are defined in both the Signal Bot's configuration and the incoming alert message, specific rules apply:
- Bot Settings Override Signal Settings: If both the bot and the signal define a parameter (e.g.,
orderType), the bot's setting takes precedence. - Signal Settings Fill the Gaps: If a parameter is not defined in the bot's configuration but is provided in the signal, the signal's parameter will be used.
Frequently Asked Questions
What is the main difference between Section A and Section B formats?
Section A is designed specifically for Pine Script™ strategies and uses native placeholder values like {{strategy.order.action}}. Section B is a universal format that uses simple commands like ENTER_LONG and works with indicators, manual alerts, and other methods.
Where do I find my signalToken?
Your signalToken is generated when you create a signal on OKX. Navigate to the "Details" section of your active signal on the OKX platform, and you will find the token in the recommended alert message setup area.
What happens if my alert is delayed?
The maxLag parameter defines the maximum acceptable delay in seconds. If the time difference between the signal's timestamp and its processing by OKX exceeds maxLag, the signal will be discarded to prevent acting on outdated market information.
Can I use limit orders with my Signal Bot?
Yes, but only when using the Section B format. You need to set orderType: limit and provide an orderPriceOffset percentage value to define the price level for the limit order.
What does 'investmentType: base' mean?
In Section A, this refers to the number of units of the base currency (e.g., the number of BTC in a BTC/USDT trade). It is recommended to use this with {{strategy.order.contracts}} for the most accurate trade execution relative to your strategy's backtest.
How does the bot handle signals for a multi-pair portfolio?
For multi-pair bots, if no investment parameters are specified in the signal, the default behavior is to invest 50% of the available balance per entry signal to maintain capital across multiple positions.