> For the complete documentation index, see [llms.txt](https://docs.durian.win/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durian.win/dev/api-documentation.md).

# API documentation

### Overview

The durian API is a RESTful interface designed for programmatic access to core trading functions on the durian platform. It enables developers to automate account management, position handling, and market data retrieval in a secure and efficient manner.

### Purpose

This guide is intended for developers, traders, and integration partners who wish to build on top of durian's infrastructure. It covers authentication, available endpoints, request/response schemas, and usage examples for both real-time trading operations and portfolio tracking.

***

Base URLs: `https://api.durian.win`

## Authentication

* HTTP Authentication, scheme: bearer

## Open API

### POST Login

POST /api/v3/register

> Body Parameters

```json
{
  "email": "string",
  "type": "string",
  "secret": "string"
}
```

***

#### Params

| Name     | Location | Type   | Required | Title | Description        |
| -------- | -------- | ------ | -------- | ----- | ------------------ |
| body     | body     | object | no       |       | none               |
| » email  | body     | string | yes      |       | email              |
| » type   | body     | string | yes      |       | 1: login by secret |
| » secret | body     | string | yes      |       | secret key         |

> Response Example

```json
{
  "msg": "success",
  "code": 200,
  "data": {
    "isInvite": false,
    "userId": 10,
    "token": "eyJhbGciOiJIUzUxMiJ9.eyJsb2dpbl91c2VyX2tleSI6IjIwNTY1NGJkLTU5ZTctNDIzNS04MzQ2LTAzODQ1NzQ1MGM5ZiJ9.LVj7AY9WLfI5fo6e3kIyA6CEFaLy2KCcpOohtXaoeNcv6k4tJWId1pxQEYw1PluFKmUABeUojJwWSi8bnlYUMg",
    "isFirst": true
  }
}
```

#### Responses

| HTTP Status Code | Meaning | Description | Data schema |
| ---------------- | ------- | ----------- | ----------- |
| 200              | OK      |             | Inline      |

#### Response Data Schema

| Name        | Type    | Required | Description                     |
| ----------- | ------- | -------- | ------------------------------- |
| » msg       | string  | true     |                                 |
| » code      | integer | true     |                                 |
| » data      | object  | true     |                                 |
| »» isInvite | boolean | true     |                                 |
| »» userId   | integer | true     |                                 |
| »» token    | string  | true     |                                 |
| »» isFirst  | boolean | true     | true is the first time to login |

***

### POST Logout

POST /api/v3/logout

> Response Example

```json
{
  "msg": "success",
  "code": 200
}
```

#### Responses

| HTTP Status Code | Meaning | Description | Data schema |
| ---------------- | ------- | ----------- | ----------- |
| 200              | OK      |             | Inline      |

#### Response Data Schema

| Name   | Type    | Required |
| ------ | ------- | -------- |
| » msg  | string  | true     |
| » code | integer | true     |

***

### GET Coin List

GET /api/v3/coins/list

#### Params

| Name          | Location | Type   | Required | Description                            |
| ------------- | -------- | ------ | -------- | -------------------------------------- |
| orderByColumn | query    | string | no       | marketCap、gainers、losers、tradingVolume |
| isAsc         | query    | string | no       | desc、asc                               |

> Response Example

```json
{
  "msg": "success",
  "code": 200,
  "data": [
    {
      "id": "3",
      "symbol": "BT_PERP_DOGE_USD",
      "name": "DOGE",
      "logo": "https://pbs.twimg.com/profile_images/378800000857919980/lHqPIZza_400x400.png",
      "fullName": "dogecoin",
      "minAmount": 250,
      "maxAmount": 250000,
      "priceChargePercent": "-0.022462",
      "tickerInfo": "{...}",
      "instrumentsInfo": "{...}",
      "maxLeverage": 50,
      "price": 2.174,
      "pointRadio": 0.1,
      "minLeverage": 1
    }
  ]
}
```

#### Responses

| HTTP Status Code | Meaning | Description | Data schema |
| ---------------- | ------- | ----------- | ----------- |
| 200              | OK      |             | Inline      |

#### Response Data Schema

| Name   | Type             | Required |
| ------ | ---------------- | -------- |
| » msg  | string           | true     |
| » code | integer          | true     |
| » data | array of objects | true     |

***

Here’s **Part 2** of the Durian API documentation in copyable markdown text, covering **Open/Close Position, Set Leverage, and Get Open Positions**:

***

### POST Open Position

POST /api/v3/account/open/position

> Body Parameters

```json
{
  "side": "string",
  "orderQty": "string",
  "leverage": 0,
  "positionSide": "string",
  "symbol": "string"
}
```

#### Params

| Name           | Location | Type    | Required | Description                    |
| -------------- | -------- | ------- | -------- | ------------------------------ |
| » side         | body     | string  | yes      | BUY, SELL                      |
| » orderQty     | body     | string  | yes      | order quantity, max 4 decimals |
| » leverage     | body     | integer | yes      | leverage                       |
| » positionSide | body     | string  | yes      | LONG, SHORT                    |
| » symbol       | body     | string  | yes      | e.g. BT\_PERP\_DOGE\_USD       |

> Response Example

```json
{
  "msg": "success",
  "code": 200,
  "data": {
    "positionId": "1234564123",
    "avgPrice": "1234564123",
    "leverage": "20",
    "orderQty": "0.03",
    "symbolName": "BTC",
    "positionSide": "LONG"
  }
}
```

***

### POST Close A Position

POST /api/v3/account/close/position

> Body Parameters

```json
{
  "orderQty": "string",
  "positionId": "string"
}
```

#### Params

| Name         | Location | Type   | Required | Description    |
| ------------ | -------- | ------ | -------- | -------------- |
| » orderQty   | body     | string | yes      | order quantity |
| » positionId | body     | string | yes      | position ID    |

> Response Example

```json
{
  "msg": "success",
  "code": 200
}
```

***

### POST Close All Positions

POST /api/v3/account/close/all/position

> Response Example

```json
{
  "msg": "string",
  "code": 0
}
```

***

### POST Set Leverage

POST /api/v3/account/set/leverage

> Body Parameters

```json
{
  "symbol": "string",
  "leverage": "string"
}
```

#### Params

| Name       | Location | Type   | Required | Description              |
| ---------- | -------- | ------ | -------- | ------------------------ |
| » symbol   | body     | string | yes      | e.g. BT\_PERP\_DOGE\_USD |
| » leverage | body     | string | yes      | leverage value           |

> Response Example

```json
{
  "msg": "success",
  "code": 200
}
```

***

### GET Opening Positions

GET /api/v3/account/portfolio/position

#### Params

| Name   | Location | Type   | Required | Description                 |
| ------ | -------- | ------ | -------- | --------------------------- |
| symbol | query    | string | no       | Filter by symbol (optional) |

> Response Example

```json
{
  "msg": "success",
  "code": 200,
  "data": [
    {
      "symbol": "BT_PERP_ACT_USD",
      "leverage": "50",
      "positionQty": "0",
      "avgPrice": "0",
      "positionSide": "NET",
      "fee": "0",
      "liqPrice": "0",
      "updateTime": "1733398963953",
      "fundingFee": "0",
      "positionValue": "0",
      "maxLeverage": "50",
      "accountId": "1729856849619000",
      "markPrice": "0.43943",
      "positionId": "1732447562612001",
      "createTime": "1732447562612",
      "unrealizedPnl": "0",
      "unrealizedPnlRate": "0",
      "positionMM": "0",
      "logo": "https://pbs.twimg.com/profile_images/1703137294159425536/AeO5_363_400x400.jpg",
      "symbolName": "ACT",
      "positionMargin": "0"
    }
  ]
}
```

***

### GET Position History

GET /api/v3/account/portfolio/position/history

#### Params

| Name      | Location | Type    | Required | Description                                                                |
| --------- | -------- | ------- | -------- | -------------------------------------------------------------------------- |
| symbol    | query    | string  | no       | e.g. BT\_PERP\_DOGE\_USD                                                   |
| pageNum   | query    | integer | no       | Page number                                                                |
| pageSize  | query    | integer | no       | Page size                                                                  |
| isClose   | query    | integer | no       | 0 = only closed positions (COMPLETE\_CLOSED, LIQUIDATION, PARTIAL\_CLOSED) |
| startTime | query    | string  | yes      | Start time in ms or ISO8601                                                |
| endTime   | query    | string  | yes      | End time in ms or ISO8601                                                  |

> Response Example

```json
{
  "msg": "success",
  "code": 200,
  "data": {
    "total": 2,
    "list": [
      {
        "symbol": "BT_PERP_ETH_USD",
        "leverage": "20",
        "positionQty": "0.1",
        "orderId": "1734451355149000",
        "closeCommission": 0.00148154,
        "avgPrice": "3930.01",
        "openDurianProfit": 0.00294751,
        "estLiqPrice": "1866.345778054359049985",
        "closedAvgPrice": "3950.56",
        "closeFee": 0.0592614,
        "points": 0.1,
        "closedType": "COMPLETE_CLOSED",
        "openCommisson": 0.00294751,
        "logo": "https://assets.coingecko.com/coins/images/279/standard/ethereum.png?1696501628",
        "openLeverage": 20,
        "id": 14076,
        "inviteUser": 77,
        "autoCloseDuration": 60,
        "openCommissionsRatio": 0.5,
        "side": "BUY",
        "amount": 0.1,
        "closedPnl": 2.055,
        "positionSide": "LONG",
        "clientOrderId": "1734451355149000",
        "openFee": 0.1179003,
        "commissionsRatio": 0.5,
        "openBrokerFee": 0.07860021,
        "updateTime": "2024-12-17 16:12:44",
        "executedAmount": 393.001,
        "userId": 75,
        "closeTs": 1734451962843,
        "positionId": "1734451065177001",
        "createTime": "2024-12-18 00:02:36",
        "ts": 1734451355149,
        "liqFee": 0
      },
      {
        "symbol": "BT_PERP_ETH_USD",
        "leverage": "20",
        "positionQty": "0.1",
        "orderId": "1734451962824000",
        "closeCommission": 0.00275425,
        "avgPrice": "3675.45",
        "openDurianProfit": 0.00148153,
        "estLiqPrice": "1596.837842854359049985",
        "closedAvgPrice": "3673.83",
        "closeFee": 0.11016964,
        "points": 18.724,
        "closedType": "COMPLETE_CLOSED",
        "openCommisson": 0.00148154,
        "logo": "https://assets.coingecko.com/coins/images/279/standard/ethereum.png?1696501628",
        "openLeverage": 20,
        "id": 14078,
        "inviteUser": 77,
        "autoCloseDuration": 60,
        "openCommissionsRatio": 0.5,
        "side": "BUY",
        "amount": 18.4,
        "closedPnl": -0.324,
        "positionSide": "LONG",
        "clientOrderId": "1734451962824000",
        "openFee": 0.0592614,
        "commissionsRatio": 0.5,
        "openBrokerFee": 0.039507600197538,
        "updateTime": "2024-12-19 09:32:16",
        "executedAmount": 197.538,
        "userId": 75,
        "closeTs": 1734600735036,
        "positionId": "1734451962843001",
        "createTime": "2024-12-18 00:12:44",
        "ts": 1734451962824,
        "liqFee": 0
      }
    ]
  }
}
```