Trading Signal Bot Alert Message 2.0 Specifications

Table of Contents

• Introduction

• Section A - for PineScript™ Strategy Users

• Section B - Universally Compatible

• FAQs

Introduction

With the launch of Signal Bots, TradingView users can now publish their signals and create a Signal Bot on OKX. In this guide, we will walkthrough the various alert message specifications that OKX supports for users.

For those who are well-versed in PineScript™ and exclusively rely on strategy scripts to send out signals, we've meticulously designed an exclusive specifications format. This format seamlessly integrates PineScript™'s strategy placeholders, enabling you to transmit trading signals with remarkable ease. If you're a native PineScript™ strategy user, this format is your ideal companion, providing a streamlined approach to merge your strategy scripts with TradingView's strategy placeholders. If you are a strategy writer and use strategy.*() functions to build your trading signals, please turn to Section A - for PineScript™ Strategy Users below.

On the other hand, we understand that not everyone relies solely on PineScript™ strategy scripts. In Section B - Universally Compatible of this guide, we provide a versatile set of specifications that go beyond scripting methods. These specifications work for all signal generation approaches. Whether you use custom indicators, various charting techniques, or even prefer manual alerts, this "one size fits all" specification framework has you covered.

An Express Overview of Pine Script™: "Strategy" vs "Indicator"

Pine Script™ strategies serve the purpose of conducting backtesting on historical data as well as forward testing in live markets. Alongside performing indicator calculations, strategies include calls to strategy.*() functions that transmit trade orders to Pine Script™'s broker emulator. This emulator can then simulate the execution of these orders. The outcomes of backtests are visualized in the "Strategy Tester" tab located at the bottom of the chart, adjacent to the "Pine Script™ Editor" tab.

On the other hand, Pine Script™ indicators also involve calculations, but they are not intended for use in backtesting scenarios. Due to their independence from the broker emulator, indicators consume fewer resources and execute more swiftly.

It's important to note that you have the flexibility to utilize either the format in Section A or that in Section B - both are fully compatible. Based on the messages you transmit, the system will intelligently discern the format used and accordingly parse your messages. This intelligent processing ensures a seamless experience regardless of your chosen approach.

Section A (PineScript™ Strategy Users)

The following specifications are specifically tailored for users who compose their algorithms using PineScript™ strategies and mainly with strategy.* function. This format is dedicated to accommodating strategy placeholder values, ensuring seamless adaptability. For a deeper understanding of strategy scripts and the process of sending alerts using strategy placeholder variables, you can find additional information at this link.

If this concept is unfamiliar to you, Section B provides an alternative approach for constructing your alerts, applicable to a broader range of scenarios.

Overview of AlertMsg Specifications

1. AlertMsg Specification - id

id - The order identifier

{{strategy.order.id}} - returns the ID of the executed order (the string used as the first parameter in one of the function calls generating orders: strategy.entry, strategy.exit or strategy.order).

2. AlertMsg Specification - action

action - Buy or Sell?

{{strategy.order.action}} - returns the string "buy" or "sell" for the executed order.

3. AlertMsg Specification - marketPosition

marketPosition - Intended position state (upon order execution)

{{strategy.market_position}} - returns the current position of the strategy in string form: "long", "flat", or "short".

4. AlertMsg Specification - prevMarketPosition

prevMarketPosition - Previous position state (before order execution)

{{strategy.prev_market_position}} - returns the previous position of the strategy in string form: "long", "flat", or "short".

5. AlertMsg Specification - instrument

Format 1: ticker - TradingView placeholder values

A 'standard placeholder'* is a literal piece of text surrounded by double braces and included inside an alert message.

"{{ticker}}" will return the Ticker of the instrument the alert generated on.

For example: "BTCUSDT.P", "ETHUSDT.P".

* Standard Placeholder to access variables in PineScript™. Learn more here.

Format 2: OKX Instrument Format

Instrument ID, or "instId" in OKX API. More details can be found in this link

For example: "BTC-USDT-SWAP", "ETH-USDT-SWAP"

6. AlertMsg Specification - signalToken

signalToken -- Authentication for Signal

The token is a security measure to ensure that the incoming requests are legitimate and authorized. This signalToken will be generated automatically when the user successfully creates a new signal on our platform, and it needs to be copied to TradingView Alert Message.

How to locate your signalToken for an already active signal?

1. Check out the Details section of your signal

2. Locate your signalToken in the recommended alert messages section

7. AlertMsg Specification - timestamp

timenow - TradingView placeholder values

A 'standard placeholder'* is a literal piece of text surrounded by double braces and included inside an alert message.

"{{timenow}}" will return the current and exacttime of when the alert generated, in UTC and the yyyy-MM-ddTHH: mm: ssZ format.

For example: "2023-06-01T17:38:10Z"

* Standard Placeholder to access variables in PineScript. Learn more here.

8. AlertMsg Specification - maxLag

maxLag - Maximum Acceptable Delay

The term "maxLag" pertains to the utmost permissible delay or latency, measured in seconds, prior to a trading signal being considered void. This calculation of maxLag involves determining the time difference between the moment the signal was dispatched from TradingView (using the "timestamp" field within the alert message) and the instant it was received on OKX for the purpose of executing an order.

By default, it is set to be 60 seconds. Setting a maxLag value helps ensure that the Signal Bot operates in a timely manner, avoiding acting on outdated or potentially inaccurate signals that may no longer reflect the current market conditions.

9. AlertMsg Specification - investmentType & amount

Important Note: To ensure optimal compatibility with your TradingView strategy, we highly recommend configuring the investmentType as "base" and setting the amount to "{{strategy.order.contracts}}". By following this approach, the order quantities on OKX will align with the order quantities specified in your TradingView strategy.

investmentType and Amount

(FOR ENTER SIGNALS ONLY)

• base: Amount in base currency (Recommended choice)
• margin: Invested margin in quote currency
• contract: A fixed number of contracts
• percentage_balance: Based on the % of Available Balance (i.e., the margin available for opening new orders)
• percentage_investment: Based on the % of Active Investment in your bot. Active Investment will typically be your initial invested margin at the time of bot creation and stays fixed until you top up more margin and choose to increase this value. For instance, if you create a bot with an initial invested margin of 1000 USDT, your Active Investment will be set to 1000 USDT. For any incoming signals, this is the value that will be used for your order size calculations. Let's say after a few days of running your bot, you decide it's performing well and reinvest another 1000 USDT margin and add it to your Active Investment. Thereafter, your Active Investment will increase to 2000 USDT and this is the new value that will be used for your order size calculations. If you are unsure what your bot's current Active Investment value is, you can always check this under your Bot Details section.

(FOR EXIT SIGNALS ONLY)

• base: Amount in base currency (Recommended choice)
• percentage_position: Based on the % of open position

Section B (Universally Compatible)

The specifications provided below are versatile and can be tailored to suit any scenario. Whether you're utilizing PineScript™ for crafting strategy or indicator (study) scripts, or manually inputting alerts into TradingView's Alert user interface, these specifications remain adaptable and customizable.

Overview of AlertMsg Specifications

1. AlertMsg Specification - action

Position Mode:

The Signal Bot operates in One-way (i.e., Buy/Sell) mode, meaning bot will only hold positions in one direction for a given instrument.

Open Orders

• ENTER_LONG: Open a Long position with the expectation that its price will rise.
• ENTER_SHORT: Open a Short position with the expectation that its price will decline.

Close Orders

• EXIT_LONG: Close a Long position partially or fully via selling the holding positions.
• EXIT_SHORT: Close a Short position partially or fully via buying back the contracts.

2. AlertMsg Specification - instrument

Format 1: ticker - TradingView placeholder values

A 'standard placeholder'* is a literal piece of text surrounded by double braces and included inside an alert message.

"{{ticker}}" will return the Ticker of the instrument the alert generated on.

For example: "BTCUSDT.P", "ETHUSDT.P".

* Standard Placeholder to access variables in PineScript. Learn more here.

Format 2: OKX Instrument Format

Instrument ID, or "instId" in OKX API. More details can be found in this link

For example: "BTC-USDT-SWAP", "ETH-USDT-SWAP"

3. AlertMsg Specification - signalToken

signalToken - Authentication for Signal

The token is a security measure to ensure that the incoming requests are legitimate and authorized. This signalToken will be generated automatically when the user successfully creates a new signal on our platform, and it needs to be copied toTradingView Alert Message.

4. AlertMsg Specification - timestamp

timenow - TradingView placeholder values

A 'standard placeholder'* is a literal piece of text surrounded by double braces and included inside an alert message.

"{{timenow}}" will return the current and exacttime of when the alert generated, in UTC and the yyyy-MM-ddTHH: mm: ssZ format.

Possible Formatting (UTC time, ISO 8061 format)

• yyyy-MM-ddTHH:mm:ssZ format For example: "2023-06-01T17:38:10Z"
• yyyy-MM-ddTHH:mm:ss.SSSZ format For example: "2023-06-01T17:38:10.836Z"
• yyyy-MM-ddTHH:mm:ss+0000 format For example: "2023-06-01T17:38:10+0000"

For example: "2023-06-01T17:38:10Z"

* Standard Placeholder to access variables in PineScript. Learn more here.

5. AlertMsg Specification - maxLag

maxLag - Maximum Acceptable Delay

The term "maxLag" pertains to the utmost permissible delay or latency, measured in seconds, prior to a trading signal being considered void. This calculation of maxLag involves determining the time difference between the moment the signal was dispatched from TradingView (using the "timestamp" field within the alert message) and the instant it was received on OKX for the purpose of executing an order.

By default, it is set to be 60 seconds. Setting a maxLag value helps ensure that the SignalBot operates in a timely manner, avoiding acting on outdated or potentially inaccurate signals that may no longer reflect the current market conditions.

6. AlertMsg Specification - order

orderType

• Market: Place a market order to Open (if action =ENTER_XX) or Close (if action = EXIT_XX) a position. No need to provide orderPriceOffset
• Limit: Place a limit order to Open (if action =ENTER_XX) or Close (if action = EXIT_XX) a position.

orderPriceOffset (ONLY applicable with LIMIT order)

• ENTER_LONG: [1-(orderPriceOffset/100)] * Bid-1
• ENTER_SHORT: [1+(orderPriceOffset/100)] * Ask-1
• EXIT_LONG: [1+(orderPriceOffset/100)] * Ask-1
• EXIT_SHORT: [1-(orderPriceOffset/100)] * Bid-1

7. AlertMsg Specification - investmentType & amount

investmentType and Amount

(FOR ENTER SIGNALS ONLY)

• margin: Invested margin in quote currency
• contract: A fixed number of contracts
• percentage_balance: Based on the % of Available Balance (i.e., the margin available for opening new orders)
• percentage_investment: Based on the % of Active Investment in your bot. Active Investment will typically be your initial invested margin at the time of bot creation and stays fixed until you top up more margin and choose to increase this value. E.g. If you create a bot with an initial invested margin of 1000 USDT, your Active Investment will be set to 1000 USDT. For any incoming signals, this is the value that will be used for your order size calculations. Let's say after a few days of running your bot, you decide it's performing well and reinvest another 1000 USDT margin and add it to your Active Investment. Thereafter, your Active Investment will increase to 2000 USDT and this is the new value that will be used for your order size calculations. If you are unsure what your bot's current Active Investment value is, you can always check this under your Bot Details section.

(FOR EXIT SIGNALS ONLY)

• Percentage_position: Based on the % of open positions

Section B Working Examples

Example 1: Long Entry -> Long Exit (Full Close) without Multi-Entry

Example 2: Long Entry -> Short Entry (One-Step Reversal) without Multi-Entry

Example 3: Long Entry -> Long Exit (Partially) -> Long Exit (Full Close)

Example 4: Using Multi-Entry

Multi-Entry is a feature in Signal Bot that allows the execution of multiple entry points for a given instrument. Traders can optimize their trading approach by diversifying entry points (i.e., Dollar-Cost Averaging), potentially increasing the chances of capturing profitable trades in a dynamic market environment.

Example 5: Using Trigger Signal Only (Without Order-related Fields)

For signal providers, they may exclude certain optional parameters given the user has already configured them in the bot.This is particularly useful for providers who focus on offering Buy/Sell trigger signals ONLY, and up to each subscriber to decide how much to invest.

Example 6: Using Trigger Signal Only (Without Order-related Fields)

If both signal and bot configuration do not specify order details, default values will be used.

• For ENTER signals, by default it will open X%* investment using market order.
• For EXIT signals, by default it will close 100% open positions upon receiving the signal.

*** X = 100 for Single-Pair. X = 50 for Multi-Pair

Example 7: Field Order Precedence

Bot Parameters take precedence over Signal Parameters. There are two rules to take note of:

1. Rule 1: Both the Bot and Signal define the field

2. Rule 2: One of the Bot/Signal defines the field

FAQs

Should you have any questions pertaining to Signal Bot, you may review some of the most commonly asked questions by our users in this article.