# Trade Bots API

### Base URL

The base URL for all the API endpoints is \*\*<https://api.vela.exchange/trade-bots**.\\>
\
Common Headers

All API requests must include the following headers:

* `Content-Type: application/json`

Depending on the endpoint and its purpose, you might also need to include:

* `vela-api-key: {Your_Api_Key}` (for bot authenticated endpoints)
* `vela-key-id: {Your_Key_Id}` (for bot authenticated endpoints)

Replace `{Your_Token}`, `{Your_Api_Key}`, and `{Your_Key_Id}` with your actual token, API key, and key ID, respectively.

### Errors

In case of an error, the API returns a response with HTTP status code `500` and a body like the following:

```json
{
  "error": "Something went wrong"
}
```

### Rate Limiting

As of the current version of the API, there is no rate limiting.

***

### How to Create an API Key on the Vela App

Here are the steps to generate your API key and key ID:

**Step 1:** Sign into the Vela App

<figure><img src="https://1356357463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrN46BgyysObtNusDYaGn%2Fuploads%2FwjTDbrkpMmX7TNC1oKu1%2F1.jpeg?alt=media&#x26;token=87f98199-ee9e-4ec0-bc54-87a8219f3f92" alt=""><figcaption></figcaption></figure>

**Step 2:** Once you're signed in, navigate to "Settings".

<figure><img src="https://1356357463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrN46BgyysObtNusDYaGn%2Fuploads%2FulXoqMX849PFmuoozBQd%2F2.jpeg?alt=media&#x26;token=5aae483c-0206-4d98-89c3-a7a50fc13f15" alt=""><figcaption></figcaption></figure>

**Step 3:** Inside "Settings", find and select "API keys".

<figure><img src="https://1356357463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrN46BgyysObtNusDYaGn%2Fuploads%2FN9giKUa0QmLaccRkzYNK%2F3.jpeg?alt=media&#x26;token=6bdb43e4-ac3b-4445-9c41-d58b687f5f7e" alt=""><figcaption></figcaption></figure>

**Step 4:** Click on "Create API Key".

<figure><img src="https://1356357463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrN46BgyysObtNusDYaGn%2Fuploads%2FasKHa5qIsCIlVvmv2a7o%2F4.jpeg?alt=media&#x26;token=1f271921-9c0b-47ca-98a3-6cdda16d4912" alt=""><figcaption></figcaption></figure>

**Step 5:** You have now created an API key and Key ID. Keep these credentials safe as you will need them for future API calls.

<figure><img src="https://1356357463-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FrN46BgyysObtNusDYaGn%2Fuploads%2FJiI78u64KIJj2WMlXj6k%2F5.jpeg?alt=media&#x26;token=797c1773-028b-4c89-8c00-03e54864c5af" alt=""><figcaption></figcaption></figure>

**Remember, don't share your API key and Key ID with anyone. Keep them confidential to ensure your account's security.**

***

### Endpoints

**GET /trade-bots/data/{data\_type}/:chainId**

This endpoint allows you to fetch different types of data. Replace `{data_type}` with the type of data you wish to fetch (deposits, withdraws, open\_orders, open\_positions, closed\_positions, portfolios). The endpoint should also contain your chainId.

**Headers**

vela-api-key: {Your\_Api\_Key}\
vela-key-id: {Your\_Key\_Id}

**Path Parameters**

The path parameter should be your chainId. Replace `:chainId` in the URL with your actual Chain ID.

#### Request Example

For instance, if you want to fetch open orders, your request would look something like this:

```http
GET /trade-bots/data/open_orders/{Your_Chain_Id}
```

With the headers:

```http
vela-api-key: {Your_Api_Key}
vela-key-id: {Your_Key_Id}
```

### GET Function Examples:

**Get Deposits:**

```json
"getDeposits": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/deposits/:chainId",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        }        
},
```

**Get Withdrawals:**

```json
"getWithdraws": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/withdraws/:chainId",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        },       
},
```

**Get Open Orders:**

```json
"getOpenOrders": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/open_orders/:chainId?paginate=0",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        }        
},
```

**Get Open Positions:**

```json
"getOpenPositions": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/open_positions/:chainId?paginate=0",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        }        
},
```

**Get Closed Positions:**

```json
"getClosedPositions": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/closed_positions/:chainId?paginate=0",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        }
},
```

**Get Portfolios:**

```json
"getPortfolios": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/portfolios/:chainId",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        }
}
```

**Get Balances:**

```json
"getBalances": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/balances/:chainId",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        }
}
```

**Get Pair Info:**

You can find *velaId* [here](https://docs.vela.exchange/vela-knowledge-base/developers/asset-pairs-and-velaid)

```json
"pairInfo": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/pairInfo/:chainId/:velaId",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        }
}
```

**Get Referrals:**

```
"getReferrals": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/referrals/:account"       
}
```

**Check Referrals:**

```
"checkReferrals": {
        "method": "GET",
        "endpoint": "https://api.vela.exchange/trade-bots/data/check_referrals",
        "headers": {
            "VELA-API-KEY": "Your API Key",
            "VELA-KEY-ID": "Your Key ID"
        }      
}
```

**Pair Info Result:**

```json
velaId               : 1
assetSymbol          : BTC/USD
fundingRate          : -34315308077 // Divisor is 1000000000000000 (Multiply by 100 to get percentage)
borrowRateForLong    : 50 // Divisor is 10000 (Multiply by 100 to get percentage)
borrowRateForShort   : 2 // Divisor is 1000000 (Multiply by 100 to get percentage)
longOpenInterest     : 59184915236162755974461601376533508 // 30 decimals
shortOpenInterest    : 110511987612749582110504884622059762 // 30 decimals
maxLongOpenInterest  : 1000000000000000000000000000000000000 // 30 decimals
maxShortOpenInterest : 1000000000000000000000000000000000000 // 30 decimals
longTradingFee       : 800000000000000000000000000 // 30 Decimals
shortTradingFee      : 800000000000000000000000000 // 30 Decimals
```

Remember to replace `{Your_Api_Key}`, `{Your_Key_Id}` and `{Your_Chain_Id}` with your actual API Key, Key ID, and Chain ID.

#### POST /trade-bots/execute

This endpoint allows you to execute a function. The request body should contain `name`, `chainId`, and `params` attributes.

**Headers**

* `vela-api-key: {Your_Api_Key}`
* `vela-key-id: {Your_Key_Id}`

**Request Body**

The request body should be a JSON object with the following structure:

```json
{
  "name": "{function_name}",
  "chainId": "{chain_id}",
  "params": {function_parameters}
}
```

### POST Function Examples:

**Deposit**

* `depositSelf` or `depositSelfUSDC`

```json
{
  "name": "depositSelf",
  "chainId": "42161",
  "params": {
    "amount": "10" // required
  }
}
```

`depositSelfAllUSDC`

```json
{
  "name": "depositSelfAllUSDC",
  "chainId": "42161",
  "params": {}
}
```

**Create Order&#x20;*****without*****&#x20;TPSL**

* `newPositionOrder` or `newPositionOrderPacked`

```json
{
  "name": "newPositionOrder",
  "chainId": "42161",
  "params": {
    "tokenId": "2", // required,
    "isLong": true, // required,
    "positionType": "Market", // required, Enum:  "Market" "Limit" "Stop Market" "Stop Limit", 
    "lmtPrice": "1912.5", //Optional,  price for "Limit", "Stop Limit"
    "slippage": "0.3", // Optional, percentage for "Market", 0.3%
    "stpPrice": "1910.2", // Optional, price for "Stop Market" and "Stop Limit"
    "collateral": "20.0", // required, it should be at least 20
    "size": "20.0" // required
  }
}

```

**Create Order&#x20;*****with*****&#x20;TPSL**

* `newPositionOrderWithTPSL`

```json
{
  "name": "newPositionOrderWithTPSL",
  "chainId": "42161",
  "params": {
    "tokenId": "2", // required,
    "isLong": true, // required,
    "positionType": "Market", // required, Enum:  "Market" "Limit" "Stop Market" "Stop Limit", 
    "lmtPrice": "1912.5", //Optional,  price for "Limit", "Stop Limit"
    "slippage": "0.3", // Optional, percentage for "Market", 0.3%
    "stpPrice": "1910.2", // Optional, price for "Stop Market" and "Stop Limit"
    "collateral": "20.0", // required, it should be at least 20
    "size": "20.0" // required
    "takeProfit": "1920.2", // Optional, If you want to place TP, then pass TP Price, if or not, dont pass
    "stopLoss": "1812.5" // Optional, if you want to place SL, then pass SL Price, if or not, dont pass SL Price
  }
}
```

**Decrease or Close Position**

* `decreasePosition` or `decreasePositionPacked`

```json
{
  "name": "decreasePosition",
  "chainId": "1",
  "params": {
    "posId": "10", // required
    "size": "10.0", // required,
    "isLong": true, // required,
    "tokenId": "1", // required,
  }
}
```

**Add Position**

* `addPosition` or `addPositionPacked`

```json
{
  "name": "addPosition",
  "chainId": "1",
  "params": {
    "posId": "10", // required
    "isLong": true, // required,
    "tokenId": "1", // required,
    "collateral": "10", // required
    "size": "20.0" // required
  }
}
```

**Increase Collateral**

* `addCollateral`

```json
{
  "name": "addCollateral",
  "chainId": "42161",
  "params": {
    "posId": "10", // required
    "amount": "10" // required
  }
}
```

**Increase Leverage**

* `removeCollateral`

```json
{
  "name": "removeCollateral",
  "chainId": "42161",
  "params": {
    "posId": "10", // required
    "amount": "10" // required
  }
}
```

**Add TPSL**

* `addTPSL` or `addTPSLPacked`

```json
{
  "name": "addTPSL",
  "chainId": "42161",
  "params": {
    "posId": "10",
    "tpPrice": "1812.2",  // Only for TP
    "tpAmountPercent": "100.0", // percentage, Only for TP
    "slPrice": "1812.2", // Only for SL
    "slAmountPercent": "100.0", // percentage, Only for SL
  }
}
```

**Cancel Pending Order or TPSL**

* `cancelPendingOrder`

```json
{
  "name": "cancelPendingOrder",
  "chainId": "42161",
  "params": {
    "posId": "10" // required
  }
}
```

* `cancelTPSL`

```
{
  "name": "cancelTriggerOrder",
  "chainId": "42161",
  "params": {
    "posId": "10" // required
    "orderId": "0", // required
  }
}
```

**Add Trailing Stop**

* `addTrailingStop`

```json
{
  "name": "addTrailingStop",
  "chainId": "42161",
  "params": {
    "posId": "10", // required
    "collateral": "10.0", // required
    "size": "20.0", // required
    "amountPercent": "100", //required percentage
    "trailType": "PERCENT", //required Enum: "PERCENT" "AMOUNT"
    "stopLossPrice": "1920.0",// required
    "trailingAmount": "0.2" //required if trailType is "PERCENT", this is 0.2%, if it is "AMOUNT", then 0.2 
  }
}
```

**Associate customer with your trade bot**

If you are a bot builder, please reach out to the Vela team to have your trade bot platform address registered

* setPlatformUsed

```json
{
  "name": "setPlatformUsed",
  "chainId": "42161",
  "params": {
    "platform": "0x...", // platform address, required
  }
}
```

**Charts**

`getCryptoChart`

This endpoint is part of the Trade-Bots module and it provides candle chart data for a given cryptocurrency pair, during a specified time period.

```json
"getCryptoChart": {
        "method": "POST",
        "endpoint": "https://api.vela.exchange/trade-bots/charts",
        "headers": {
            "Content-Type": "application/json",
            "vela-api-key": "{Your_Api_Key}",
            "vela-key-id": "{Your_Key_Id}"
        },
        "body": {
            "pair": "crypto_pair",
            "time": "time_period",
            "from": "start_date",
            "to": "end_date"
        }        
}
```

### Response

The response will be a JSON object with the result of the execution. The structure of this object will depend on the function that was executed.