# APIs & Payloads

## APIs

The following API endpoints allow users to interact with the trading bot to place orders, liquidate positions, and set market trends. Each endpoint is designed to facilitate seamless execution of trading actions, ensuring speed, accuracy, and validation checks where necessary.

The **trend-related endpoints** allow for setting market trends in **DynamoDB**, ensuring trades align with predefined strategies. The **order placement endpoints** allow traders to execute trades efficiently, including a version with trend validation.

Below is a table summarizing the key API endpoints and their functionality:

| **Endpoint**             | **Method** | **Usage**                                                                                                                                                              |
| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/ts/place-order`        | `POST`     | Places an order to Tradovate without trend validation.                                                                                                                 |
| `/ts/liquidate-position` | `POST`     | Liquidates all open positions in Tradovate for a particular instrument                                                                                                 |
| `/ts/set-trend`          | `POST`     | Sets the market trend (`BULL` or `BEAR`) along with an optional trend duration in AWS DynamoDB, This can be used in combination with the `place-order-trend endpoint`  |
| `/ts/place-order-trend`  | `POST`     | Places an order with trend validation to ensure alignment with the defined market trend.                                                                               |

Each of these endpoints is designed to streamline trading actions, allowing for automation while maintaining control over execution logic. Let me know if you need additional details or modifications!



## Payloads

#### **Place Order (`/ts/place-order`)**

**Payload Example:**

```json
{
  "accountSpecs": ["PRACTICEFEB310430043"],
  "action": "Buy",
  "orderType": "Limit",
  "symbol": "MNQ1!",
  "orderQty": 3,
  "limitPrice": 22222,
  "stopPrice": 15,
  "takeProfit": 15,
  "trailingOffset": 2.0,
  "tradeTimeRanges": [""],
  "avoidTradeTimeRanges": [""]
}
```

**Field Descriptions:**

| **Field**              | **Description**                                        | **Possible Values**                                                                                                                                                                                                        | **Required**                 |
| ---------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `accountSpecs`         | List of account identifiers for placing the order.     | <p>Example: <code>["PRACTICEFEB310430043"]</code><br><br><br><code>Multiple accounts can also be provided</code><br><code>as shown below</code><br><br><br><code>["YOURAccount1","YOURAccount2","YOURAccount3"]</code></p> | ✅ Yes                        |
| `action`               | The type of order action to perform.                   | `"Buy"`, `"Sell"`                                                                                                                                                                                                          | ✅ Yes                        |
| `orderType`            | The type of order being placed.                        | `"Market"`, `"Limit"`, `"Protect"`, `"Bracket"`                                                                                                                                                                            | ✅ Yes                        |
|                        |                                                        |                                                                                                                                                                                                                            |                              |
| `symbol`               | The ticker symbol of the asset being traded.           | <p>Example: <code>"MNQ1!"</code>, <code>"ES!"</code>  <br><br><code>If setting alerts from Trading view, then this should be  "{{ticker}}"</code></p>                                                                      | ✅ Yes                        |
|                        |                                                        |                                                                                                                                                                                                                            |                              |
| `orderQty`             | The quantity of contracts/shares to trade.             | Any positive integer                                                                                                                                                                                                       | ✅ Yes                        |
| `limitPrice`           | The price at which the limit order should be placed.   | Numeric value (Required for limit orders)                                                                                                                                                                                  | ❌ No (Only for Limit Orders) |
| `stopPrice`            | The price at which the stop order should be triggered. | Eg: 10                                                                                                                                                                                                                     | ❌ No                         |
| `takeProfit`           | The price at which the trade should take profit.       | Eg: 10                                                                                                                                                                                                                     | ❌ No                         |
| `trailingOffset`       | The distance from the price for a trailing stop.       | Eg: 5.0                                                                                                                                                                                                                    | ❌ No                         |
| `tradeTimeRanges`      | Specifies time ranges where trading is allowed.        | Example: `["09:30-16:00"]`                                                                                                                                                                                                 |                              |
| `avoidTradeTimeRanges` | Specifies time ranges where trading is not allowed.    | Example: `["12:00-13:00"]`                                                                                                                                                                                                 |                              |



#### **Liquidate Open Positions (`/ts/liquidate-position`)**

**Payload Example:**

```json
{
  "symbol": "MNQZ4",
  "accountSpecs": ["PRACTICEDEC209166971"]
}
```

**Field Descriptions:**

| **Field**      | **Description**                              | **Possible Values**                                                                                                                                                                                                            | **Required** |
| -------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------ |
| `symbol`       | The ticker symbol of the asset to liquidate. | Example: `"MNQZ4"`, `"ES!"`                                                                                                                                                                                                    | ✅ Yes        |
| `accountSpecs` | List of account identifiers for liquidation. | <p>Example: <code>["PRACTICEDEC20XXXX"]</code><br><br><br><br><br><code>Multiple accounts can also be provided</code><br><code>as shown below</code><br><br><br><code>["YOURAccount1","YOURAccount2","YOURAccount3"</code></p> | ✅ Yes        |

#### **Set Market Trend (`/ts/set-trend`)**

**Payload Example:**

```json
{
  "trend": "BULL",
  "trend_duration": "24Brick",
  "trend_ticker": "NQ1!"
}
```

**Field Descriptions:**

| **Field**        | **Description**                                   | **Possible Values**             | **Required** |
| ---------------- | ------------------------------------------------- | ------------------------------- | ------------ |
| `trend`          | Defines the market trend direction.               | `"BULL"`, `"BEAR"`              | ✅ Yes        |
| `trend_duration` | The duration for which the trend should be valid. | Example: `"24Brick"`, `"30Min"` | ❌ No         |
| `trend_ticker`   | The ticker symbol associated with the trend.      | Example: `"NQ1!"`, `"ES!"`      | ✅ Yes        |



#### **. Place Order with Trend Validation (`/ts/place-order-trend`)**

**Payload Example:**

```json
{
  "accountSpecs": ["PRACTICEFEB310430043"],
  "action": "Buy",
  "orderType": "Bracket",
  "symbol": "NQ1!",
  "orderQty": 1,
  "trailingOffset": 5.0,
  "limitPrice": 10,
  "stopPrice": 10,
  "closeOnTrendReversal": "True",
  "tradeTimeRanges": [""],
  "avoidTradeTimeRanges": [""]
}
```

**Field Descriptions:**

<table data-header-hidden><thead><tr><th></th><th></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Field</strong></td><td><strong>Description</strong></td><td><strong>Possible Values</strong></td><td><strong>Required</strong></td></tr><tr><td><pre><code>accountSpecs
</code></pre></td><td>List of account identifiers for placing the order.</td><td>Example: <code>["PRACTICEFEB310430043"]</code><br><br><br><code>Multiple accounts can also be provided</code><br><code>as shown below</code><br><br><br><code>["YOURAccount1","YOURAccount2","YOURAccount3"]</code></td><td>✅ Yes</td></tr><tr><td><code>action</code></td><td>The type of order action to perform.</td><td><code>"Buy"</code>, <code>"Sell"</code></td><td>✅ Yes</td></tr><tr><td><code>orderType</code></td><td>The type of order being placed.</td><td><code>"Market"</code>, <code>"Limit"</code>, <code>"Stop"</code>, <code>"Bracket"</code></td><td>✅ Yes</td></tr><tr><td><code>symbol</code></td><td>The ticker symbol of the asset being traded.</td><td>Example: <code>"NQ1!"</code>, <code>"ES!"</code></td><td>✅ Yes</td></tr><tr><td><code>orderQty</code></td><td>The quantity of contracts/shares to trade.</td><td>Any positive integer</td><td>✅ Yes</td></tr><tr><td><code>limitPrice</code></td><td>The price at which the limit order should be placed.</td><td>Numeric value (Required for limit orders)</td><td>❌ No (Only for Limit Orders)</td></tr><tr><td><code>stopPrice</code></td><td>The price at which the stop order should be triggered.</td><td>Numeric value</td><td>❌ No</td></tr><tr><td><code>trailingOffset</code></td><td>The distance from the price for a trailing stop.</td><td>Numeric value</td><td>❌ No</td></tr><tr><td><code>closeOnTrendReversal</code></td><td>Whether to close the trade if the trend reverses.</td><td><code>"True"</code>, <code>"False"</code></td><td>❌ No</td></tr><tr><td><code>tradeTimeRanges</code></td><td>Specifies time ranges where trading is allowed.</td><td>Example: <code>["09:30-16:00"]</code></td><td>❌ No</td></tr><tr><td><code>avoidTradeTimeRanges</code></td><td>Specifies time ranges where trading is not allowed.</td><td>Example: <code>["12:00-13:00"]</code></td><td>❌ No</td></tr></tbody></table>
