> For the complete documentation index, see [llms.txt](https://naviprotocol.gitbook.io/astros/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://naviprotocol.gitbook.io/astros/astros-perpetual/astros-api/rest-api.md).

# REST API

Base URL: `https://api.astros.ag`

Unless noted otherwise, private endpoints require:

| Header      | Required | Description                       |
| ----------- | -------- | --------------------------------- |
| `APIKEY`    | Yes      | Your API key                      |
| `signature` | Yes      | HMAC-SHA256 of the string to sign |

### Complete request walkthrough

Example: create a market order.

1. Endpoint: `POST /api/third/hot/order/create`
2. Build parameters, then sort by key:

```
clientOrderId=1711176054830&isLong=false&isMarket=true&lever=20&matchType=2&pairName=ETH-USD&positionType=3&price=3500&quantity=0.2&timestamp=1711176054830
```

3. Sign with HMAC-SHA256 → lowercase hex.
4. Send the request:

```bash
curl --location --request POST \
  'https://api.astros.ag/api/third/hot/order/create?clientOrderId=1711176054830&isLong=false&isMarket=true&lever=20&matchType=2&pairName=ETH-USD&positionType=3&price=3500&quantity=0.2&timestamp=1711176054830' \
  --header 'APIKEY: xx' \
  --header 'signature: bf95dc1b92b4e5b334fbd7a55138163a90df8d862d7ec74981afc017552ff631' \
  --header 'Content-Type: text/plain' \
  --data ''
```

5. Response:

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "pairName": "ETH-USD",
    "orderId": 39172288,
    "corderId": "1711176054830"
  },
  "sid": "1794298144005844993"
}
```

***

### Order operations

Private write endpoints.

#### Create order

`POST` `/api/third/hot/order/create`

**Content-Type:** `application/x-www-form-urlencoded`\
**Signature required:** Yes

**Parameters**

| Name            | Type            | Required | Description                                               |
| --------------- | --------------- | -------- | --------------------------------------------------------- |
| `pairName`      | String          | Yes      | Trading pair, e.g. `ETH-USD`                              |
| `isLong`        | Boolean         | Yes      | `true` long, `false` short                                |
| `isMarket`      | Boolean         | Yes      | `true` market, `false` limit                              |
| `matchType`     | Number          | Yes      | Match type                                                |
| `price`         | String / Number | Yes      | Order price (required for limits; still sent for markets) |
| `quantity`      | String / Number | Yes      | Order size                                                |
| `lever`         | Number          | Yes      | Leverage                                                  |
| `positionType`  | Number          | Yes      | Position mode / type                                      |
| `clientOrderId` | String          | Yes      | Client order id                                           |
| `timestamp`     | Number          | Yes      | Unix time in milliseconds                                 |

**Example**

```bash
curl --location --request POST \
  'https://api.astros.ag/api/third/hot/order/create?isLong=false&isMarket=true&matchType=2&pairName=ETH-USD&price=3500&quantity=0.02&timestamp=1714967864706&clientOrderId=1714967864706&lever=20&positionType=3' \
  --header 'APIKEY: xx' \
  --header 'signature: 51f2657e1ba608e9794ad686302004c007605f1c46abd0b4cbe90bbf6ddbff4d' \
  --header 'Content-Type: text/plain' \
  --data ''
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "pairName": "ETH-USD",
    "orderId": 65685755,
    "corderId": "1714967864706"
  },
  "sid": "1798274145222492161"
}
```

#### Batch create orders

`POST` `/api/third/hot/order/batchCreate`

**Content-Type:** `application/json`\
**Signature required:** Yes (sign the exact JSON body)

**Request body**

| Name        | Type            | Required | Description                                 |
| ----------- | --------------- | -------- | ------------------------------------------- |
| `orders`    | Array           | Yes      | Order objects (same fields as create order) |
| `timestamp` | Number / String | Yes      | Unix time in milliseconds                   |

**Example**

String to sign (no spaces):

```
{"orders":[{"clientOrderId":1714981600002,"isLong":true,"isMarket":true,"lever":20,"matchType":2,"pairName":"ETH-USD","positionType":3,"price":"3100","quantity":"0.02"}],"timestamp":1714981600002}
```

```bash
curl --location 'https://api.astros.ag/api/third/hot/order/batchCreate' \
  --header 'APIKEY: xx' \
  --header 'signature: 8e90d89e687736e18057ddd93f325aac4a843e215eb9b5cf59c182ad0c58061b' \
  --header 'Content-Type: application/json' \
  --data '{"orders":[{"clientOrderId":1714981600002,"isLong":true,"isMarket":true,"lever":20,"matchType":2,"pairName":"ETH-USD","positionType":3,"price":"3100","quantity":"0.02"}],"timestamp":1714981600002}'
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "pairName": "ETH-USD",
      "orderId": 65783238,
      "corderId": "1714981600002"
    }
  ],
  "sid": "1798288548790632449"
}
```

#### Batch create orders with per-order results

`POST` `/api/third/hot/order/batchCreateWithRes`

**Content-Type:** `application/json`\
**Signature required:** Yes

Same request shape as batch create. Response returns a result per order.

```json
{
  "code": 200,
  "data": [
    {
      "corderId": "17157696929891",
      "orderId": 72485870,
      "pairName": "ETH-USD",
      "resultCode": 200,
      "resultMsg": "SUCCESS"
    },
    {
      "corderId": "17157696929892",
      "orderId": null,
      "pairName": "ETH-USD",
      "resultCode": 2001,
      "resultMsg": "Illegal parameter:lever"
    }
  ],
  "error": false,
  "msg": "SUCCESS",
  "sid": "1799115133265612801"
}
```

#### Cancel order

`POST` `/api/third/order/cancelEntrust`

**Content-Type:** `application/x-www-form-urlencoded`\
**Signature required:** Yes

**Parameters**

| Name        | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `entrustId` | Number | Yes      | Exchange order id         |
| `timestamp` | Number | Yes      | Unix time in milliseconds |

**Example**

```bash
curl --location --request POST \
  'https://api.astros.ag/api/third/order/cancelEntrust?entrustId=65785693&timestamp=1714981969885' \
  --header 'APIKEY: xx' \
  --header 'signature: 8b1ae2f28347db1d44d484f24de50551bf29b74297d4aba32aece8b5e9b59030' \
  --header 'Content-Type: text/plain' \
  --data ''
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": true,
  "sid": "1798288937146482689"
}
```

#### Cancel order by client order id

`POST` `/api/third/order/cancelEntrustByCli`

**Content-Type:** `application/x-www-form-urlencoded`\
**Signature required:** Yes

**Parameters**

| Name            | Type   | Required | Description               |
| --------------- | ------ | -------- | ------------------------- |
| `clientOrderId` | String | Yes      | Client order id           |
| `timestamp`     | Number | Yes      | Unix time in milliseconds |

#### Batch cancel orders

`POST` `/api/third/order/batchCancelEntrust`

Cancels orders one by one and **stops on the first failure**.

**Parameters**

| Name         | Type   | Required | Description               |
| ------------ | ------ | -------- | ------------------------- |
| `entrustIds` | String | Yes      | Comma-separated order ids |
| `timestamp`  | Number | Yes      | Unix time in milliseconds |

#### Batch cancel orders with results

`POST` `/api/third/order/batchCancelWithRes`

Cancels orders one by one, **skips failures**, and returns a result per id.

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "orderId": 65799887,
      "clientOrderId": "1714983859195",
      "pairName": "ETH-USD",
      "isLong": true,
      "resultCode": 1,
      "resultMsg": "canceled: cancel success from book"
    }
  ],
  "sid": "1798291036118810625"
}
```

***

### Position operations

#### Add or reduce margin

`POST` `/api/third/order/callMarginAmount`

**Content-Type:** `application/x-www-form-urlencoded`\
**Signature required:** Yes

**Parameters**

| Name           | Type            | Required | Description                       |
| -------------- | --------------- | -------- | --------------------------------- |
| `positionId`   | Number          | Yes      | Position id                       |
| `call`         | Boolean         | Yes      | `true` add margin, `false` reduce |
| `marginAmount` | String / Number | Yes      | Margin delta                      |
| `timestamp`    | Number          | Yes      | Unix time in milliseconds         |

**Example**

```bash
curl --location --request POST \
  'https://api.astros.ag/api/third/order/callMarginAmount?positionId=348455&call=true&marginAmount=0.01&timestamp=1714984795896' \
  --header 'APIKEY: xx' \
  --header 'signature: c542ebd69dbeba438af11cc6b13fcbe668a1cac500e91cf02509a3fcb156628d' \
  --header 'Content-Type: text/plain' \
  --data ''
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": true,
  "sid": "1798291898375438337"
}
```

#### Set user leverage

`POST` `/api/third/v1/trade/setUserLever`

**Content-Type:** `application/json`\
**Signature required:** Yes

**Request body**

| Name             | Type   | Required | Description               |
| ---------------- | ------ | -------- | ------------------------- |
| `contractPairId` | Number | Yes      | Pair id                   |
| `lever`          | Number | Yes      | Leverage                  |
| `positionType`   | Number | Yes      | Position type             |
| `timestamp`      | Number | Yes      | Unix time in milliseconds |

```bash
curl --location 'https://api.astros.ag/api/third/v1/trade/setUserLever' \
  --header 'APIKEY: xx' \
  --header 'Content-Type: application/json' \
  --header 'signature: 5a6ecd7d0b321dd657046612c3870c327ccaed5853cca28a416a1af820f65b3b' \
  --data '{"contractPairId":2,"lever":1,"positionType":3,"timestamp":1752217984828}'
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": true,
  "sid": "1811061846213328897"
}
```

***

### Account, order, position, and trade queries

Private read endpoints.

#### Query account balance

`POST` `/api/third/hot/order/balance`

**Parameters**

| Name        | Type   | Required | Description                 |
| ----------- | ------ | -------- | --------------------------- |
| `symbol`    | String | Yes      | Settlement coin, e.g. `USD` |
| `timestamp` | Number | Yes      | Unix time in milliseconds   |

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "userId": 42348,
    "coinId": 4,
    "availableAmount": "709.738786",
    "frozenAmount": "1680.032305",
    "symbol": "USD"
  },
  "sid": "1798293168648716289"
}
```

#### Query current open orders

`POST` `/api/third/order/selectContractCurrentEntrustList`

**Parameters**

| Name        | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| `pairName`  | String | Yes      | Trading pair                                            |
| `pageNo`    | Number | No       | Optional. Uses the API default page number              |
| `pageSize`  | Number | No       | Optional. Uses the API default page size; maximum `100` |
| `timestamp` | Number | Yes      | Unix time in milliseconds                               |

#### Query order by id

`POST` `/api/third/order/queryOrder`

Query a current or completed order by exchange order id.

**Parameters**

| Name        | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `entrustId` | Number | Yes      | Exchange order id         |
| `timestamp` | Number | Yes      | Unix time in milliseconds |

#### Query match / fill list

`POST` `/api/third/order/selectContractMatchPairList`

**Parameters**

| Name        | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| `pairName`  | String | Yes      | Trading pair                                            |
| `pageNo`    | Number | No       | Optional. Uses the API default page number              |
| `pageSize`  | Number | No       | Optional. Uses the API default page size; maximum `100` |
| `matchId`   | Number | No       | Cursor / filter match id                                |
| `timestamp` | Number | Yes      | Unix time in milliseconds                               |

#### Query position list

`POST` `/api/third/hot/order/selectContractPositionList`

**Parameters**

| Name        | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| `pairName`  | String | No       | Trading pair. Omit for all pairs                        |
| `pageNo`    | Number | No       | Optional. Uses the API default page number              |
| `pageSize`  | Number | No       | Optional. Uses the API default page size; maximum `100` |
| `timestamp` | Number | Yes      | Unix time in milliseconds                               |

#### Get trade history

`GET` `/api/third/v1/trade/fillHistory`

**Parameters**

| Name        | Type    | Required | Description               |
| ----------- | ------- | -------- | ------------------------- |
| `pairName`  | String  | Yes      | Trading pair              |
| `timestamp` | Number  | Yes      | Unix time in milliseconds |
| `orderId`   | Number  | No       | Filter by order id        |
| `limit`     | Number  | No       | Max rows                  |
| `idLe`      | Number  | No       | Return ids ≤ this value   |
| `idGe`      | Number  | No       | Return ids ≥ this value   |
| `beginTime` | Number  | No       | Start time (ms)           |
| `endTime`   | Number  | No       | End time (ms)             |
| `isAsc`     | Boolean | No       | Ascending id order        |

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "tradeId": 14986811,
      "symbol": "ETH-USD",
      "orderId": 94000213,
      "clOrdId": "satethswapXDKX62197e7d9b9c1",
      "isMarket": false,
      "isClose": false,
      "isLong": false,
      "isTaker": true,
      "fillPrice": "2296.66",
      "fillQty": "1.111",
      "fillAmt": "2551.58926",
      "feeCurrency": "USD",
      "feeRate": "0.02",
      "fillFee": "0.510317",
      "fillPnl": "10.13481",
      "tradeTime": 1725786173000
    }
  ],
  "sid": "1811133316739301377"
}
```

#### Get maker earning trade history

`GET` `/api/third/v1/rebates/maker/earnings/trade`

**Parameters**

| Name        | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `pairName`  | String | Yes      | Trading pair              |
| `timestamp` | Number | Yes      | Unix time in milliseconds |
| `beginTime` | Number | No       | Start time (ms)           |
| `endTime`   | Number | No       | End time (ms)             |
| `idLe`      | Number | No       | Cursor                    |
| `limit`     | Number | No       | Max rows                  |

#### Get maker earning info

`GET` `/api/third/v1/rebates/maker/earningsInfo`

**Parameters**

| Name        | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `pairName`  | String | Yes      | Trading pair              |
| `timestamp` | Number | Yes      | Unix time in milliseconds |
| `idLe`      | Number | No       | Cursor                    |
| `limit`     | Number | No       | Max rows                  |

#### Query order history

`GET` `/api/third/v1/orders/histories`

**Parameters**

| Name        | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `symbol`    | String | Yes      | Trading pair              |
| `timestamp` | Number | Yes      | Unix time in milliseconds |
| `beginTime` | Number | No       | Start time (ms)           |
| `limit`     | Number | No       | Max rows                  |

#### Get user leverage

`GET` `/api/third/v1/trade/getUserLever`

**Parameters**

| Name             | Type   | Required | Description               |
| ---------------- | ------ | -------- | ------------------------- |
| `contractPairId` | Number | Yes      | Pair id                   |
| `timestamp`      | Number | Yes      | Unix time in milliseconds |

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "contractPairId": 1,
    "positionType": 4,
    "lever": 4
  },
  "sid": "1752217984637-f6da"
}
```

#### Query trade config list

`POST` `/api/third/hot/order/tradeConfigList`

**Parameters**

| Name        | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `timestamp` | Number | Yes      | Unix time in milliseconds |

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "pairId": 18,
      "takerFeeRate": "0",
      "makerFeeRate": "0",
      "quantityMin": "1.2",
      "quantityMax": "2000000",
      "amountMin": "5",
      "amountMax": "5000000"
    }
  ],
  "sid": "1843666924729548801",
  "timestamp": 1758257794177
}
```

#### Query funding / tariff history

`POST` `/api/third/hot/order/selectContractTariffList`

**Parameters**

| Name        | Type   | Required | Description                                             |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| `pairName`  | String | No       | Trading pair. Omit for all pairs                        |
| `pageNo`    | Number | No       | Optional. Uses the API default page number              |
| `pageSize`  | Number | No       | Optional. Uses the API default page size; maximum `100` |
| `timestamp` | Number | Yes      | Unix time in milliseconds                               |

***

### Public queries

No API key required unless noted.

#### System time

`GET` `/api/third/info/time`

```bash
curl --location 'https://api.astros.ag/api/third/info/time'
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": 1714988294487,
  "sid": "1798295565880098817"
}
```

#### Index price

`GET` `/api/third/info/indexPrice`

**Parameters**

| Name       | Type   | Required | Description  |
| ---------- | ------ | -------- | ------------ |
| `pairName` | String | Yes      | Trading pair |

```bash
curl --location 'https://api.astros.ag/api/third/info/indexPrice?pairName=ETH-USD'
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": "3200.605",
  "sid": "1798295744456785921"
}
```

#### Mark price

`GET` `/api/third/info/markPrice`

**Parameters**

| Name       | Type   | Required | Description  |
| ---------- | ------ | -------- | ------------ |
| `pairName` | String | Yes      | Trading pair |

#### Last trades

`GET` `/api/third/info/trades`

**Parameters**

| Name       | Type   | Required | Description  |
| ---------- | ------ | -------- | ------------ |
| `pairName` | String | Yes      | Trading pair |
| `limit`    | Number | No       | Max rows     |

#### Pair list

`GET` `/api/third/info/pairs`

```bash
curl --location 'https://api.astros.ag/api/third/info/pairs'
```

#### Order book depth

`GET` `/api/third/info/depth`

**Parameters**

| Name       | Type   | Required | Description  |
| ---------- | ------ | -------- | ------------ |
| `pairName` | String | Yes      | Trading pair |
| `limit`    | Number | No       | Depth levels |

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "bids": [{ "price": "3171.6", "quantity": "13.673" }],
    "asks": [{ "price": "3237.67", "quantity": "13.415" }]
  },
  "sid": "1798296428421939201"
}
```

#### Kline

`GET` `/api/third/info/kline`

Returns candles in reverse chronological order.

**Parameters**

| Name       | Type   | Required | Description   |
| ---------- | ------ | -------- | ------------- |
| `pairName` | String | Yes      | Trading pair  |
| `period`   | String | Yes      | e.g. `1MIN`   |
| `limit`    | Number | No       | Max candles   |
| `endTime`  | Number | No       | End time (ms) |

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "contractPairId": 1,
      "period": "1MIN",
      "time": 1714987920000,
      "open": "3191.42",
      "close": "3194.46",
      "low": "3192.88",
      "hight": "3195.93",
      "count": 5,
      "quantity": "4.796",
      "amount": "15320.42988"
    }
  ],
  "sid": "1798296938930601985"
}
```

#### Historical funding rates

`GET` `/api/third/v1/market/funding/history`

**Parameters**

| Name        | Type   | Required | Description     |
| ----------- | ------ | -------- | --------------- |
| `pairName`  | String | Yes      | Trading pair    |
| `beginTime` | Number | No       | Start time (ms) |
| `endTime`   | Number | No       | End time (ms)   |
| `idLe`      | Number | No       | Cursor          |
| `limit`     | Number | No       | Max rows        |

#### Current funding rate

`GET` `/api/third/v1/market/funding/current`

**Parameters**

| Name       | Type   | Required | Description  |
| ---------- | ------ | -------- | ------------ |
| `pairName` | String | Yes      | Trading pair |

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "symbol": "ETH-USD",
    "fundingRate": "-0.0000625"
  },
  "sid": "1811061846213328897"
}
```

#### 24h ticker

`GET` `/api/third/info/ticker/24hr`

**Parameters**

| Name       | Type   | Required | Description  |
| ---------- | ------ | -------- | ------------ |
| `pairName` | String | Yes      | Trading pair |

```bash
curl --location 'https://api.astros.ag/api/third/info/ticker/24hr?pairName=ETH-USD'
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "contractPairId": 18,
    "period": "1DAY",
    "time": 0,
    "open": "3.7955",
    "close": "3.5895",
    "low": "3.5337",
    "hight": "3.8097",
    "count": 3419,
    "quantity": "789497.3",
    "amount": "2866792.97189"
  },
  "sid": "1843569447395368961",
  "timestamp": 1758164832506
}
```

#### Open interest

`GET` `/api/third/info/oi`

**Parameters**

| Name       | Type   | Required | Description                                   |
| ---------- | ------ | -------- | --------------------------------------------- |
| `pairName` | String | No       | Trading pair. Omit for all pairs if supported |

```bash
curl --location 'https://api.astros.ag/api/third/info/oi?pairName=ETH-USD'
```

```json
{
  "error": false,
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "contractPairId": 18,
      "symbol": "SUI-USD",
      "amount": "16523452.63442271699675688",
      "count": 7892
    }
  ],
  "sid": "1843569447395368961",
  "timestamp": 1758164832506
}
```