> For the complete documentation index, see [llms.txt](https://3commas.gitbook.io/3commas-official-api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://3commas.gitbook.io/3commas-official-api-docs/smarttrade/1.-create-smarttrade.md).
# Create SmartTrade
**Description:** Creates a new SmartTrade\
{% hint style="info" %}
This endpoint supports creating SmartTrade is available for accounts where the parameter `smart_trading_supported` is `true`.
{% endhint %}
**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 ` | ISO 8601 datetime string of when this SmartTrade entity was created |
| **data\[updated\_at]** | `string ` 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**
```json
```
\
**Example Response and errors**
Status: 200 OK
```json
```
Status: 422 Unprocessable Entity
```json
{
"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
```json
{
"error": "Forbidden",
"error_description": "Account not owned by current user."
}
```