Trading Signal Bot Alert Message Specifications – Help Center

Introduction

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

With the launch of Signal Bots, TradingView users can now publish their signals and create a Signal Bot on BlockFin. In this guide, we will walk through the various alert message specifications that BlockFin 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.

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 format. 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.

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 on TradingView.

Overview of AlertMsg Specifications

Parameter	Required	Values
id	Required	{{strategy.order.id}} from TradingView
action	Required	{{strategy.order.action}} from TradingView
marketposition	Required	{{strategy.market_position}} from TradingView
prevMarketPosition	Required	{{strategy.prev_market_position}} from TradingView
instrument	Required	{{ticker}} from TradingView Instld format from BlockFin
signalToken	Required	Provided by BlockFin upon signal creation
timestamp	Required	{{timenow}} from TradingView
maxLag	Optional	Non-negative integer value between [1, 3600]. Default to 60.
investmentType	Optional*	base (FOR ENTER AND EXIT SIGNALS) Amount in base currency margin (FOR ENTER SIGNALS ONLY) Invested margin in quote currency contract (FOR ENTER SIGNALS ONLY) Fixed number of contracts percentage_balance (FOR ENTER SIGNALS ONLY) Based on the % of Available Balance (i.e., the margin available for opening new orders) percentage_investment (FOR ENTER SIGNALS ONLY) Based on the % of Initial Invested Margin upon bot creation percentage_position (FOR EXIT SIGNALS ONLY) Based on the % of open position
amount	Required	base (positive floating number) margin (positive floating number) contract (positive integer) percentage_balance (floating value between [0.01, 100] in %) percentage_investment (floating value between [0.01, 100] in %) percentage_position (floating value between [0.01, 100] in %)

InvestmentType will be defaulted to "percentage_investment" if the signal is deemed to be an entry signal and "percentage_position" if the signal is deemed to be an exit signal. It is, however, strongly recommended for this value to be set to "base" and the amount to be set to "{{strategy.order.contracts}}" for maximal compatibility with your TradingView strategy.

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).

AlertMsg Specification - action

action - Buy or Sell?

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

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".

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".

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: BlockFin Instrument Format

Instrument ID, or "instId" in BlockFin API.

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

AlertMsg Specification - signalToken

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?

Check out the Details section of your signal

Locate your signalToken in the recommended alert messages section.

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.

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 BlockFin 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.

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 BlockFin will align with the order quantities specified in your TradingView strategy.

Investment type 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 Initial Invested Margin upon bot creation. Additional margin added afterwards will not be counted

(FOR EXIT SIGNALS ONLY)

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