# 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
      }
    ]
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.durian.win/dev/api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.