Create SmartTrade

Description: Creates a new SmartTrade

This endpoint supports creating SmartTrade is available for accounts where the parameter smart_trading_supported is true.

Permission: SMART_TRADES_WRITE Security: SIGNED

POST

/v2/smart_trades

Request Parameters

Name	Type	Mandatory	Values	Description
account_id	integer	Yes		ID of the exchange account entity
pair	string	Yes		Trading pair in 3Commas format
instant	boolean	No	false true	Use for creating Simple Buy or Simple Sell. One of the values can be specified: false or true for creating Simple Buy and Simple Sell
skip_enter_step	boolean	No	false true	Use true to create simple_buy and simple_sell by skipping the step opening position
leverage[enabled]	boolean	Yes	false true	Sets leverage settings for a futures account. Default: false
leverage[type]	string	No	cros isolated	Leverage type for the futures account. Default: false
leverage[value]	integer	No		Sets leverage settings for a futures account. Default: false
position[type]	string	Yes	buy sell	The side of order to enter in position
position[order_type]	string	Yes	market limit conditional	Type order for this SmartTrade
position[units][value]	number	Yes		Amount of units for order. It should be based on the rules of the exchange regarding currency rates, limits, and leverage data.
position[price][value]	number	Yes		Price for limit or conditional type order. It should be based on the rules of the exchange regarding currency rates, limits, and leverage data
position[conditional][price][value]	number	No		Conditional trigger price. Used with order type conditional. This parameter is required when position[order_type] is set to conditional.
position[conditional][price][type]	string	No	bid ask last	By default ask for long, bid for short. This parameter is required when position[order_type] is set to conditional.
position[conditional][order_type]	string	No	market limit	Type of conditional order. This parameter is required when position[order_type] is set to conditional
position[conditional][trailing][enabled]	boolean	No	false	Set a trailing price settings for a conditional order. This parameter is required when position[order_type] is set to conditional
position[conditional][trailing][percent]	number	No	Minimum: 0 Maximum: 99	Percentage value of the trailing price for a conditional order. This parameter is required when position[order_type] is set to conditional
take_profit[enabled]	boolean	Yes	false true	Set Take Profit settings for this SmartTrade. Use true to activate the parameter group. Default: false
take_profit[steps][order_type]	string	No	market limit	Take Profit order type for this SmartTrade. This parameter is required when take_profit[enabled] is set to true.
take_profit[steps][volume]	number	No		Take Profit order volume. This parameter is required when take_profit[enabled] is set to true
take_profit[steps][price][type]	string	No	bid ask last	Type of Take Profit price
take_profit[steps][price][value]	number	No		Price value for Take Profit. Applies only if position has no trailing or position trailing is finished
take_profit[steps][price][percent]	number	No		The percentage price level for Take Profit. Applies only if position has no trailing or position trailing is finished
take_profit[steps][trailing][enabled]	boolean	No	false true	Set the trailing price settings for a conditional order. Applies only to the last step of Take Profit. Default: false
take_profit[steps][][trailing][percent]	number	No	Minimum: 0,01, Maximum: 100	Trailing percentage for Take Profit orders. This parameter is required when take_profit[steps][trailing][enabled] is set to true.
stop_loss[enabled]	boolean	Yes	false true	Set Stop Loss settings for this SmartTrade. Use true to activate the parameter group. Default: false
stop_loss[breakeven]	boolean	No	false true	Enables the Move to Breakeven feature in SmartTrades. To use this feature, you must have at least two Take Profit steps. Default: false
stop_loss[order_type]	string	No	market limit	Stop Loss order type for this SmartTrade. This parameter is required when stop_loss[enabled] is set to true
stop_loss[price][value]	number	No		A price for limit Stop Loss order for this SmartTrade. This parameter is required when stop_loss[enabled] is set to true
stop_loss[conditional][price][type]	string	No	bid ask last	Type price of Stop Loss for this the SmartTrade. This parameter is required when stop_loss[enabled] is set to true
stop_loss[conditional][price][value]	number	No		A price conditional Stop Loss order when the position has no trailing or the trailing has finished
stop_loss[conditional][price][percent]	number	No		Represents a percentage-based Stop Loss condition that is part of a more complex stop-loss order setup. Only if position has trailing and position trailing is not finished.
stop_loss[conditional][trailing][enabled]	boolean	Yes	false	Set a trailing price settings for a conditional Stop Loss order
stop_loss[timeout][enabled]	boolean	No	false true	Set timeout settings for Stop Loss order. Default: false
stop_loss[timeout][value]	integer	No		Value timeout (s). This parameter is required when stop_loss[timeout][enabled] is set to true
note	string	No	minlength: 1 maxlength: 300	Short note for this SmarTrade. Shows in the 3Commas web app

Parameters response

Name	Type	Description
id	integer	Unique 3Commas ID for this SmartTrade entity
account[id]	integer	Unique 3Commas ID of this exchange account entity where this SmartTrade was created
account[type]	string	The exchange types where this SmartTrade was created
account[name]	string	The name for the exchange account defined by the user
account[market]	string	The name of this exchange account
account[link]	string	The URL of the account where this SmartTrade was created
pair	string	Trading pair in 3Commas format
instant	string	Indicates that a simple buy or sale of an asset has been made
status[basic_type]	string	3Commas status for this SmartTrade entity
status[title]	string	Brief description of this status
status[error]	string	Description of the error for this SmartTrade if it fails
leverage[enabled]	boolean	Information about this leverage for a futures account. false if editing is not available
leverage[type]	string	Shows the leverage type that was set when creating a SmartTrade on a futures account
leverage[value]	string	Shows the leverage value that was set when creating a SmartTrade on a futures account
leverage[type_editable]	boolean	Indicates whether the user can modify leverage[type] settings when editing a SmartTrade. true if editing is available
position[type]	string	The side of the order to be created by this trade
position[editable]	boolean	Indicates whether the user can modify the settings of position when editing a SmartTrade. true if editing is available
position[units][value]	string	Amount of units for position trade
position[units][editable]	boolean	Indicates whether the user can modify the group of unit settings parameters when editing a SmartTrade
position[price][value]	number	The price of the position order, including commission
position[price][value_without_commission]	number	The price of the position order, excluding commission
position[price][editable]	boolean	Indicates whether the user can modify the group of price settings parameters when editing a SmartTrade.
position[total]	number	The total value of the position, including all relevant factors such as price and quantity
position[order_type]	string	The type of order used to open the position (e.g., market, limit, conditional)
position[conditional][editable]	boolean	Indicates whether the user can modify the settings of conditional of position when editing a SmartTrade
position[conditional][price][value]	number	The specific price value set for the conditional order trigger
position[conditional][price][type]	string	The type of price for the conditional order used to open the position
position[conditional][order_type]	string	The type of conditional order used to open the position (e.g., market, limit, conditional)
position[conditional][trailing][editable]	boolean	Indicates whether the trailing stop settings for the conditional order can be edited
position[conditional][trailing][percent]	number	The trailing stop percentage for the conditional order, specifying the distance from the market price at which the trailing stop is triggered
position[status][type]	boolean	The status type of the position trade for this SmartTrade
position[status][basic_type]	string	3Commas status for this Position trade
position[status][title]	string	Brief description of this status for this position trade
position[status][error]	string	Description of the error for this conditional trade if it fails
take_profit[enabled]	boolean	Indicates whether the take profit settings for this SmartTrade can be edited
take_profit[price_type]	string	The price type for the take profit trade(s) that was set when creating the SmartTrade. Can be either value or percentage
take_profit[steps][][id]	integer	Unique 3Commas trade ID for this SmartTrade entity
take_profit[steps][][order_type]	string	The type of order for this trade's take profit
take_profit[steps][][editable]	boolean	Indicates whether the step of take profit settings for this SmartTrade can be edited
take_profit[steps][][units][value]	number	Amount of units for this trade
take_profit[steps][][price][type]	integer	The type of price for the take profit order used to open the position
take_profit[steps][][price][value]	number	The specific price value set to trigger the take profit order
take_profit[steps][][price][percent]	number	The specific percentage of the price set to trigger this take profit trade
take_profit[steps][][trailing][editable]	boolean	Indicates whether the trailing settings for the take profit in this SmartTrade can be edited
take_profit[steps][][trailing][percent]	number	The specific trailing percentage applied to the price for this take profit trade
take_profit[steps][][status][basic_type]	string	3Commas status for this Take Profit trade
take_profit[steps][][status][title]	string	Brief description of this status for this trade
take_profit[steps][][status][error]	string	Error description for this take profit trade if it fails
take_profit[steps][][data][cancelable]	integer	Indicates whether the take profit trade can be canceled
take_profit[steps][][data][panic_sell_available]	boolean	Indicates whether the one step of Take Profit can be closed at market based on its current status
take_profit[steps][][position]	string	Indicates the position of this take profit step for this SmartTrade
stop_loss[enabled]	boolean	Indicates whether the stop loss settings for this SmartTrade can be edited
stop_loss[price_type]	string	The price type for the stop loss trade(s) that was set when creating the SmartTrade. Can be either value or percentage
stop_loss[breakeven]	boolean	Indicates whether the stop loss has been set at the breakeven point
stop_loss[order_type]	string	The type of order for this trade's stop loss
stop_loss[editable]	boolean	Indicates whether the stop loss settings for this SmartTrade can be edited
stop_loss[status][type]	string	The status type of the stop loss trade for this SmartTrade
stop_loss[status][basic_type]	string	3Commas status for this stop loss trade
stop_loss[status][title]	string	Brief description of this status for this trade
stop_loss[status][error]	string	Error description for this stop loss trade if it fails
stop_loss[units][value]	number	The specific price value set for the stope loss order trigger
stop_loss[total][value]	number	The total value of the stop loss trade
stop_loss[price][value]	number	[TBD]
stop_loss[conditional][price][value]	number	The specific price value set to trigger the stop loss order
`stop_loss[conditional][price][type]	string	The type of price for the stop loss order used to close the position
stop_loss[conditional][price][percent]	number	The specific percentage of the price set to trigger this stop loss trade
stop_loss[conditional][trailing][enabled]	boolean	Indicates whether trailing is enabled for the conditional stop loss
stop_loss[conditional][trailing][percent]	number	The trailing percentage for the conditional stop loss
stop_loss[timeout][enabled]	boolean	Indicates whether the timeout setting for the stop loss is enabled
stop_loss[timeout][value]	integer	The value of the timeout setting for the stop loss trade
reduce_funds[steps][][id]	integer	Unique 3Commas trade ID for this market close trade in the SmartTrade
reduce_funds[steps][][type]	string	The order type for this reduce funds trade
reduce_funds[steps][][status][basic_type]	string	3Commas status for this Redice Funds trade
reduce_funds[steps][][status][title]	string	Brief description of this status for this trade
reduce_funds[steps][][status][error]	string	Error description for this reduce funds trade if it fails
reduce_funds[steps][][units][value]	number	Amount of units for this reduce funds trade
reduce_funds[steps][][price][value]	number	The price of the Reduce Funds trade, including the commission
reduce_funds[steps][][price][value_without_commission]	number	The price of the reduce funds trade, excluding commission
reduce_funds[steps][][total][value]	integer	The total value of the reduce funds trade, including all relevant factors such as price and quantity
reduce_funds[steps][][data][cancelable]	boolean	Indicates whether the reduce funds trade can be canceled
reduce_funds[steps][][data][panic_sell_available]	boolean	Indicates whether a drawdown transaction can be closed at market
market_close[id]	integer	Unique 3Commas trade ID for this market close trade in the SmartTrade
market_close[status][basic_type]	string	3Commas status for this Market Close trade
market_close[status][title]	string	3Commas status for this market close trade
market_close[status][error]	string	Error description for this market close trade if it fails
market_close[units][value]	number	Amount of units for position trade
market_close[price][value]	number	The price of the market close trade, including commission
market_close[price][value_without_commission]	number	The price of the market close trade, excluding commission
market_close[total][value]	number	Indicates whether the reduce funds trade can be closed at market
note	string	Optional user-defined note for this SmartTrade
note_raw		[TBD]
skip_enter_step	boolean	Shows whether the position opening step was skipped
data[editable]	boolean	Indicates whether the user can modify the settings this SmartTrade. true if editing is available
data[current_price][bid]	number	The current highest bid price of the asset
data[current_price][ask]	number	The current lowest ask price of the asset
data[current_price][last]	number	The last traded price of the asset
data[current_price][quote_volume]	number	[TBD]
data[current_price][day_change_percent]	number	Percentage price change for the asset over the last 24 hours
data[target_price_type]		[TBD]
data[orderbook_price_currency]		[TBD]
data[base_order_finished]		[TBD]
data[missing_funds_to_close]	number	[TBD]
data[liquidation_price]	number	The liquidation price of the asset on the futures exchange
data[average_enter_price]	number	The average entering price of the asset with fees
data[average_close_price]	number	The average closing price of the asset with fees
data[average_enter_price_without_commission]	number	The average entering price of the asset without accounting for any fees
data[average_close_price_without_commission]	number	The average closing price of the asset without accounting for any fees
data[panic_sell_available]	boolean	Indicates whether the SmartTrade can be closed at market based on its current status. This option is available for SmartTrades with the following statuses: waiting_targets, stop_loss_in_progress, reduce_funds_in_progress, and pending_reduce_funds
data[add_funds_available]	boolean	Indicates whether adding funds is available for this SmartTrade based on its current status. This option is not available for SmartTrades if: status[basic_type] is waiting_position; data[type] is simple_sell or simple_buy; position[conditional][trailing][editable] is false
data[reduce_funds_available]	boolean	Indicates whether reducing funds is available for this SmartTrade based on its current status. This option is available for SmartTrades with only the status: waiting_targets
data[force_start_available]	boolean	Indicates whether the option to force a market entry for the SmartTrade is available based on its current status. This option is available for SmartTrades when position[status][basic_type] are to_process, order_placed, trailing_activated
data[force_process_available]	boolean	Indicates whether the SmartTrade can be force.
data[cancel_available]	boolean	Indicates whether the SmartTrade can be canceled. Available for SmartTrades where the parameter basic_type is one of the following: waiting_position, waiting_targets, stop_loss_in_progress, reduce_funds_in_progress, or pending_reduce_funds
data[finished]	boolean	Indicates whether the SmartTrade has been completed or finished. true is SmartTrade finished
data[base_position_step_finished]	boolean	Shows whether entry into the position has been completed. true means the entry process is finished
data[entered_amount]	number	The total amount of funds used to enter the position for this SmartTrade, including all additional funds trades, specified in base
data[entered_total]	number	Total amount of funds used to enter the position for this SmartTrade, specified in quota
data[closed_amount]	number	Total amount of SmartTrade closing volume in base
data[closed_total]	number	Total amount of SmartTrade closing volume in quota
data[commission]	number	The trading fee of exchange for transaction
data[created_at]	string <date-time>	ISO 8601 datetime string of when this SmartTrade entity was created
data[updated_at]	string <date-time> or null	ISO 8601 datetime string of when this SmartTrade entity was updated
data[type]	string	Type of SmartTrade
profit[volume]	number	The total profit volume generated by this SmartTrade in quote
profit[usd]	number	The total profit volume generated by this SmartTrade in USD
profit[percent]	number	The total profit volume generated by this SmartTrade in percent
profit[roe]	number or null	The return on equity (ROE) for this SmartTrade's profit, applicable only for futures accounts
margin[amount]	number or null	The total margin amount required for this SmartTrade ()
margin[total]	number or null	The total margin value for this SmartTrade (quote)
is_position_not_filled	boolean	Indicates whether a position has been successfully entered for this SmartTrade

Example request

Example Response and errors

Status: 200 OK

Status: 422 Unprocessable Entity

{
    "error": "record_invalid",
    "error_description": "Invalid parameters",
    "error_attributes": {
        "position": [
            "is invalid"
        ],
        "position.total": [
            "must be less than or equal to 9000000.0"
        ],
        "units_to_buy": [
            "must be less than or equal to 9000.0"
        ]
    }

Status: 403 Forbidden

{
    "error": "Forbidden",
    "error_description": "Account not owned by current user."
}