Articles on: Signals and Automation

Webhook Signals: Open, Close, Increase or Reverse a Position

The Webhook Signals described in this section are related to positions on a Signal Bot.
A position can be opened, closed, increased or reversed using a webhook signal.

Types of Position Signals

Open: Open a new position, either short or long
Increase: Increase the size of an existing position (this will add a new entry order at the specified price)
Reverse: (Futures Only). Close the current position and create a new one with the side specified in the Signal
Close: Close current position/s for the specified market and side

Required Settings for all Signal Types

Action The type of signal: open, close, reverse or increase
API key The API key from your Signal Bot
Secret The Secret from your Signal Bot
Exchange: See: Webhooks: Valid values for Exchange and Symbol
Symbol See: Webhooks: Valid values for Exchange and Symbol

Example signal including only Settings required for all signals.

Note that some Action types, have additional required settings.

{
 "api_key": "YOUR_ALTRADY_API_KEY",
 "api_secret": "YOUR_ALTRADY_API_SECRET",
 "action": "close",
 "exchange": "BYBI",
 "symbol": "BYBI_USDT_SOL"
}

Open Signal

The Open signal is used to open a new position for the chosen market.
For the signal to be received and opened, the following criteria must be met:
The API key and Secret must match those in the Bot Settings.
The syntax of the signal must be valid JSON
All filter criteria in the Signal Bot Settings must be matched by the signal.

Minimum Required Settings for an Open Signal

Example of an open signal, including only the minimum required settings:
All other settings will be taken from the Signal Bot Settings.

{
  "api_key": "YOUR_ALTRADY_API_KEY",
  "api_secret": "YOUR_ALTRADY_API_SECRET",
  "exchange": "EXCHANGE CODE",
  "symbol": "MARKET CODE",
  "action": "open",
  "side": "long"
}

Apart from the 5 settings that are required for all Signal Types, (see above), the only additional setting that is required for an Open signal is "side"
For side: valid options are "long" or "short".
Use long for a position that opens with a Buy entry and closes with Sell exit/s.
Use short for a position that opens with a Sell entry and closes with Buy exit/s.
Short positions can be opened on Futures exchanges using the quote currency

Short positions can be opened on Spot exchanges if the coins (base currency) are already owned and available to be sold

Example of an Open signal including all required and optional settings:

{
  "action": "open",
  "api_key": "YOUR_ALTRADY_API_KEY",
  "api_secret": "YOUR_ALTRADY_API_SECRET",
  "exchange": "EXCHANGE CODE",
  "symbol": "MARKET CODE",
  "side": "long",  
  "test": true,
  "quote_amount": 0,
  "signal_id": "string",
  "leverage": 0,
  "signal_price": 0,
  "adjust_fee": true,
  "dca_orders": [
    {
      "price_percentage": 0,
      "quantity_percentage": 0
    }
  ],  
"take_profit": [
    {
      "price_percentage": 0,
      "position_percentage": 0
    }
  ],
  "stop_loss": {
    "stop_percentage": 0,
    "stop_price": 0,
    "cool_down_amount": 0,
    "cool_down_time_frame": "minute",
    "cool_down_type": "TIME",
    "cool_down_candle_resolution": "0",
    "cool_down_cancel_price": 0,
    "cool_down_cancel_percentage": 0
  }
}

Optional Settings for the Open (and Reverse) Signal

Setting	Values	Notes
test	true or false	Defaults to false. When test is true, the Position will open Pending orders instead of Live orders. Use this for testing signals
action	open	Defaults to open
quote_amount OR base_amount	numeric value, optional, if used, overrides the Bot Settings	This is a fixed amount or quote or base currency, not percentage of the account. If both settings (quote and base) are included in the signal, an error will occur
signal_id	If included, must be a unique character string for each signal. If there is not a specific use case for addin ghte signal_ID, it is best to omit it	Generally only used with Pinescript. Can be included in the Open signal if it will be need for updating the position later. If used, it should include a varying value that will ensure it is always unique, such as the TV variable {{time}}. If signal_ID is omitted, Altrady will generate a unique signal_ID.
leverage	numeric value	If included, the leverage value will overwrite leverage included in the Signal Bot Settings
signal_price	numeric value	The special Trading View variable "{{close}}" can be used to substitute the Close price from the candle. If signal_price is omitted, Altrady will substitute the current price. Note that Entry orders are always limit orders. To simulate a Market order, use a positive Entry Price Deviation in the Signal Bot Settings.
adjust_fee	true OR false	Optional: If omitted, defaults to true. If included, adjusts the entry order size to ensure there is enough to pay exchange fees. Recommended when the entry or position size uses 100% of the available balance; this can otherwise cause the order to fail due to an insufficient balance error, after the exchange deducts fees from the wallet.
dca_orders	the DCA settings block can be repeated up to 9 times, for a total of 10 entry orders (see example below)	To use the DCA values from the webhook Signal, select the "DCA from Signal" option in the Signal Bot Settings. Multiple DCAs can be included by repeating the DCA block (see example below).
price_percentage	numeric value	The percentage below the average entry price for the order to be placed.
quantity_percentage	numeric value	The percentage of the initial entry order for this DCA (e.g. 200 represents 200% or 2x the entry order size.
take_profit	the take_profit settings block can be repeated up to 10 times (see example below)	To use the TP values from the webhook Signal, in the Signal Bot Settings, Take Profit from Signal option must be selected.
price_percentage	numeric value	The percentage above/below (long/short) the average entry price for the TP order to be placed.
position_percentage	numeric value	The percentage of the position size for this order.
Stop Loss settings	Optional	Include this block to set a Stop Loss value in the Signal. To use the SL values from the webhook Signal, select the SL from Signal option in the Signal Bot Settings.
stop_percentage OR stop_price	Required if a Stop Loss block is included.	Stop %: The percentage below the signal price for the SL to be placed. Once placed, the Stop Price is fixed, and does not vary with average entry price. More details OR Stop Price: specify a price
Cooldown Settings	Optional with Stop Loss. See: SL cooldown for more details
cool_down_type	Determines which other settings must be included	Choose either Time or Candle Close
TIME	Specify a time_frame type (day, hour, minute). And a duration to combine with the type.	e.g. "cool_down_type": "TIME", "cool_down_time_frame": "minute", "cool_down_amount": 5
CANDLE_CLOSE	Specify the candle resolution (time-frame) in minutes: 1, 2, 3, 5, 10, 15, 30, 60, 120, 240, 360, 720, 1440. Maximum is 1440: 1 day.	e.g. "cool_down_candle_resolution": "30"
Emergency Stop Loss	Optional with cooldown. Specify either a specific SL price, or % from entry price. Like the initial SL, the ESL is fixed once placed.	"cool_down_cancel_price": 101.123 OR "cool_down_cancel_percentage": 25

Including TPs, DCAs or SL in the signal

DCAs, TP/s and SL for your signals can either be:
included in your webhook entry signal (see above). Useful when they will vary with each signal or each market.
specified in the Signal Bot Settings. Useful when they will not vary for each market and signal; or
added manually to your positions once they have opened. Useful for manual intervention, or when these values may vary, and the TV alert does not provide these details.
Choose Custom in the Bot Settings, to specifiy the value in the Bot.
Use Signal in the Bot Settings, to use the values provided in the signal.

Repeating the DCA block for more than one DCA

"dca_orders": [
    {
      "price_percentage": 5,
      "quantity_percentage": 100
    },
    {
      "price_percentage": 10,
      "quantity_percentage": 200
    },
    {
      "price_percentage": 20,
      "quantity_percentage": 400
    }
  ],

Repeating the TP block for more than one TP

TP position_percentages should add to 100. If the sum is less than 100%, the remaining amount will be included in the last TP.

"take_profit": [
    {
      "price_percentage": 2,
      "position_percentage": 50
    },
    {
      "price_percentage": 4,
      "position_percentage": 30
    },
    {
      "price_percentage": 6,
      "position_percentage": 20
    }
  ],

Stop Loss example: Simple Stop Loss

SL 7.5% from entry, with no cooldown

"stop_loss": {
    "stop_percentage": 7.5
  }

Stop Loss example with Candle Close Cooldown

Stop Loss (20% from entry) with 4 hour Candle Close cooldown and Emergency Stop Loss (35% from entry)

"stop_loss": {
    "stop_percentage": 20,
    "cool_down_type": "CANDLE_CLOSE",
    "cool_down_candle_resolution": "240",
    "cool_down_cancel_percentage": 35
  }

Stop Loss example with Timer Cooldown

Fixed price SL at 2.79, with 10 minute Timer Cooldown, and Emergency Stop Loss (at 2.59 fixed price)**

"stop_loss": {
    "stop_price": 2.79,
    "cool_down_amount": 10,
    "cool_down_time_frame": "minute",
    "cool_down_type": "TIME",
    "cool_down_cancel_price": 2.59
  }

Close Signal

The Close signal is used to close running position/s for the specified market, that were opened by the same Signal Bot.

The following criteria must be met:
The API key and Secret must match those in the Bot Settings.
Exchange and Symbol must be specified.
"action": "close" is required

Example Close signal, including only the minimum required settings

This signal would close all open long positions for XBT/USD, that were opened by the Signal Bot.

{
  "action": "close",
  "api_key": "YOUR_ALTRADY_API_KEY",
  "api_secret": "YOUR_ALTRADY_API_SECRET",
  "exchange": "KRKN",
  "symbol": "KRKN_USD_XBT",
  "order_type": "market",
  "side": "ORIGINAL SIDE"
}

Details about the required settings are shown in Required Settings for all Signal Types

Example of a Close signal including all required and optional settings:

{
  "action": "close",
  "api_key": "YOUR_ALTRADY_API_KEY",
  "api_secret": "YOUR_ALTRADY_API_SECRET",
  "exchange": "EXCHANGE CODE",
  "symbol": "MARKET CODE",
  "side": "ORIGINAL SIDE",
  "signal_ID": "ORIGINAL SIGNAL ID",
  "order_type": "limit",
  "price": 99
}

Required Settings specifically for the Close Signal

Details about the settings required for all signals can be found here: Required Settings for all Signal Types
"order_type": "market" or "order_type": "limit" is required for a close signal.
"order_type": "market" cannot be combined with "price". It will close the current position/s using a pseudo-market order (a limit order 10% from the current price).
"order_type": "limit" must be used with "price". It will close the position with a limit order at the specified price.

Optional Settings for the Close Signal

side. If omitted, side will default to "long". The side reders to the side of the original position when it was opened. Either long positions or short positions can be closed with one signal, not both.
signal_ID (this is the signal_ID of the signal that opened the specific position)
When the signal_ID is omitted, all positions for the specified market and side, and that were opened by the Signal Bot, will be closed.
Where there might be more than one position open for the same Symbol and Side, signal_ID is used to specify a specific position to close. Since it must match the signal_ID that opened the position, this is not possible with standard Trading View indicators. It might be possible to code using PineScript.
If a Signal_ID was not specified with the original Signal, Altrady will have created a unique signal_ID for the signal. Trading View will not have access to an Altrady-generated Signal_ID
If your bot has a Setting of "Max per market" = 1 , then only one position will ever be opened at the same time. In that case, the Close signal will close that single position, and the Signal_ID is not needed.

Reverse Signal

The Reverse signal can only be used for Futures markets.

Other than the "action": "reverse", all settings for the reverse signal are identical to the required and optional settings for the Open Signal.
The Reverse signal is like a combination of two signals in one: Close and Open.
close the existing position(s) with a market order and open a new position with the given parameters.
The new position will not be opened until the existing position is closed.
For side: valid options are "long" or "short". This will be the side of the new position created. If omitted, it will defailt to "long".
It will retry up to 5 times with a 3 second delay before failing. This happens asynchronously so the webhook will return immediately, Returns 204 no content when the request is successfully received, otherwise returns the same error messages as the open action.
Use of the Reverse signal is recommended over sending independent close and open signals. With separate signals, the timing of the close is unknown; if the close is not completed on the exchange before the open signal arrives, the Open signal will be ignored. Additionally, only one signal can be sent in a single TV alert message, so a second alert would be needed for the open signal.
If the position is already closed when the reverse action is received, it will just open a new position with the given settings.

Minimim settings for a reverse signal

This will close any existing short positions, and open a new long position for BTC/USDT on Binance.

{
 "action": "reverse",
 "api_key": "YOUR_ALTRADY_API_KEY",
 "api_secret": "YOUR_ALTRADY_API_SECRET",
 "exchange": "BINA",
 "symbol": "BINA_USDT_BTC",
 "side": "long"
}

Further examples for the Reverse signal can be seen in the Open signal section

Increase Signal

The Increase signal is used to increase the position size of one or more open positions for a single market and side

It will increase the size of existing position/s for the specified market and side, that were opened by the Signal Bot.
The following criteria must be met:
The API key and Secret must match those in the Bot Settings.
Exchange and Symbol must be specified.

Example of an Increase signal including all required and optional settings
This example uses the Trading View variable {{ close }} to insert the price at the candle close

{
 "api_key": "YOUR_ALTRADY_API_KEY",
 "api_secret": "YOUR_ALTRADY_API_SECRET",
 "action": "increase",
 "side": "long",
 "exchange": "BINA",
 "symbol": "BINA_USDT_BTC",
 "increase_order": {
   "base_amount": 25.5,
   "price": "{{close}}"
 }
}

Optional Settings for the Increase signal

"side" is optional. If omitted, the side will default to long.

One increase_order block must be included, and only one.
Its two settings are:
"quantity_percentage" OR quote_amount OR base_amount This is a numeric value. Use ONE of these to specify the increase amount. If more than one is included, the signal is rejected.
.. "quantity_percentage"
increases the position size by a percentage of the initial entry order size. For example, set to 100 to increase the position size buy the same amount as the initial entry order.
.. "quote_amount"
increases the position size by the amount of quote currency specified (rounded down to the highest possible order size).
.. "base_amount"
increases the position size by the amount of base currency specified (e.g. 250 would be specified for 250 ADA, for BIFU_USDT_ADA).
"price" is the limit order price for the increase position order. Optional: if the price is omittted., the current price will be used as the signal price. If set, the Entry Price Deviation in the Signal Bot Settings will adjust the signal price. This allows the Increase order to be specvified as a pseudo-market order.

from 20th Dec, 2023, the Entry Price Deviation from the Signal Bot Settings is used to adjust the signal price for Increase signals. This works in the same way as for Open signals, and initial orders.

Webhook and Trading View SIgnals: Overview
Webhook: Setting up the Signal Bot
Webhook Signals: start or stop a Signal Bot
Valid values for Exchange and Symbol](/en/article/webhook-valid-values-for-exchange-and-symbol-1xrzfap/)
Webhook Signals: Trading View Setup
Webhook Signals: Testing and Errors

Updated on: 23/04/2024

Was this article helpful?

Thank you!