> ## Documentation Index
> Fetch the complete documentation index at: https://docs.monochrome.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# 接口

> 第三方 OAuth API：接口。

## 用户注册

如果您没有 Monochrome 账号，请提前注册，注册地址：`http(s)://{URL}/{language}/accounts/register?client_id={clientId}`\
**参数说明**\
**1. URL**\
Monochrome授权页面域名，正式环境为: [www.monochrome.exchange](http://www.monochrome.exchange)\
**2. language**\
授权页面语言，当前支持的内容如下：\
en：英语\
ja：日本语\
hi：印地语\
id：印尼语\
ru：俄语\
es：西班牙语\
tr：土耳其语\
zh-HK：繁体中文\
zh-CN：简体中文\
vi：越南语\
th：泰语\
**3. clientId**\
机构唯一标识，请提前向 Monochrome 申请\
**例如:**\
[http://www.monochrome.exchange/en/accounts/register?client\_id=DDJ7BLK49YUCL97S](http://www.monochrome.exchange/en/accounts/register?client_id=DDJ7BLK49YUCL97S)\
通过该url注册的用户将属于机构:DDJ7BLK49YUCL97S

## 跳转说明

当第三方平台需要 Monochrome 用户授权某些操作时，请从第三方平台页面跳转到`http(s)://{URL}/{language}/accounts/oauth2?response_type=code&client_id={clientId}&redirect_uri={redirectUri}&scope={scope}`\
**参数说明**\
**1. URL**\
Monochrome授权页面域名，正式环境为: [www.monochrome.exchange](http://www.monochrome.exchange)\
**2. language**\
授权页面语言，当前支持的内容如下：\
en：英语\
ja：日本语\
hi：印地语\
id：印尼语\
ru：俄语\
es：西班牙语\
tr：土耳其语\
zh-HK：繁体中文\
zh-CN：简体中文\
vi：越南语\
th：泰语\
**3. clientId**\
机构唯一标识，请提前向 Monochrome 申请\
**4. redirectUri**\
授权成功后的跳转到的地址\
**5. scope**\
授权作用域，和clientId一同向 Monochrome 获取\
**例如:**\
[http://www.monochrome.exchange/zh-CN/accounts/oauth2?response\_type=code\&client\_id=DDJ7BLK49YUCL97S\&redirect\_uri=https%3A%2F%2Fwww.baidu.com\&scope=userinfo](http://www.monochrome.exchange/zh-CN/accounts/oauth2?response_type=code\&client_id=DDJ7BLK49YUCL97S\&redirect_uri=https%3A%2F%2Fwww.baidu.com\&scope=userinfo)

## 申请Token

`GET` `/public/uaa/oauth2/token?client_id={client_id}&client_secret=${client_secret}&grant_type={grant_type}&code={code}`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| client\_id | string | true | | 机构标识 | 请向 Monochrome 申请 |
| client\_secret | string | true | | 机构Secret Key | 请向 Monochrome 申请 |
| grant\_type | string | true | | 授权类型，固定值 | authorization\_code |
| code | string | true | | 用户授权后重定向到机构页面，会在url中携带code字段 | |

```json Response theme={null}
{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {
        "user_id":"12345678",
        "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5MTU2MTA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.vkSTiFLcQuO0qJqdm21MfmoLKb38wwhsKPCJI3x1xmOxYouH5GtmcYglk0XRxPeOMVZ-6E6tM3HGn1yMQdqTgHOVeAbtLSBBIqyUh6y-8j_MF8GyBwcEaRK2hfWBNOHw06B-0jLO_mKEduUWZXYHjNiAN2jenbj7Ba6MX7rcENk",//用于访问授权接口的token，默认有效期1天
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5NDE1MzA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.UIeGGDiiybfEUEPFAteN3TtCxz5PyZxGDIULaNJjO3mCck7s28nRpXWSxONMGYMXG03XxJVUJs5WfdpNEmKUmmoQQuy-UOCuvV7zLdFmwUHd5e5tDMA7mgTCxbCeyxYE4L8Vr8StEEhxwWbDFxG_-2wdNEgEIvlgg9bI87Qcy9s",//用于刷新access token的token，默认有效期180天
        "expires_in": 15551999,//access_token距离过期的毫秒数
        "refresh_expires_in": 18143999,//refresh_token距离过期的毫秒数
        "client_id": "35LF2FSLHX5IRQA4",//机构标识
        "scope": "userinfo"//授权的scope
    }
}
```

## 刷新Token

`GET` `/public/uaa/oauth2/token?client_id={client_id}&client_secret=${client_secret}&grant_type={grant_type}&refresh_token={refresh_token}`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| client\_id | string | true | | 机构标识 | |
| client\_secret | string | true | | 机构Secret Key | |
| grant\_type | string | true | | 授权类型，固定值 | refresh\_token |
| refresh\_token | string | true | | 申请token时返回的refresh\_token字段 | |

```json Response theme={null}
{
    "rc": 0,
    "mc": "SUCCESS",
    "ma": [],
    "result": {
        "user_id":"12345678",
        "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5MTU2MTA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.vkSTiFLcQuO0qJqdm21MfmoLKb38wwhsKPCJI3x1xmOxYouH5GtmcYglk0XRxPeOMVZ-6E6tM3HGn1yMQdqTgHOVeAbtLSBBIqyUh6y-8j_MF8GyBwcEaRK2hfWBNOHw06B-0jLO_mKEduUWZXYHjNiAN2jenbj7Ba6MX7rcENk",//用于访问授权接口的token
        "refresh_token": "eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiIxIiwidXNlci1pZCI6MSwic2NvcGUiOiJ1c2VyaW5mbyIsImlzcyI6Inh0LmNvbSIsImV4cCI6MTY5NDE1MzA3NiwiY2xpZW50X2lkIjoiMzVMRjJGU0xIWDVJUlFBNCJ9.UIeGGDiiybfEUEPFAteN3TtCxz5PyZxGDIULaNJjO3mCck7s28nRpXWSxONMGYMXG03XxJVUJs5WfdpNEmKUmmoQQuy-UOCuvV7zLdFmwUHd5e5tDMA7mgTCxbCeyxYE4L8Vr8StEEhxwWbDFxG_-2wdNEgEIvlgg9bI87Qcy9s",//用于刷新access token的token
        "expires_in": 15551999,//access_token距离过期的毫秒数
        "refresh_expires_in": 18143999,//refresh_token距离过期的毫秒数
        "client_id": "35LF2FSLHX5IRQA4",//机构标识
        "scope": "userinfo"//授权的scope
    }
}
```

## 创建apiKey

`POST` `/user/account/api-key`

```json Response theme={null}
{
  "rc": 0,
  "mc": "SUCCESS",
  "ma": [
    {}
  ],
  "result": {
     "userId": 12345678,                                       //user id
     "accessKey": "99258227-f053-46a2-9b10-66c155eb705c",      //加密key
     "secretKey": "4b1839e11bf7a1c6de5f078bd9f4b6e0850da3cf"   //加密串
  }
}
```

## 单笔获取

`GET` `/spot/v4/order/{orderId}`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| orderId | number | true | | 订单ID | |

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "symbol": "BTC_USDT",                   //交易对
    "orderId": "6216559590087220004",       //订单号
    "clientOrderId": "16559590087220001",   //客户端订单号
    "baseCurrency": "string",               //标的币种
    "quoteCurrency": "string",              //报价币种
    "side": "BUY",                          //订单方向 BUY-买,SELL-卖
    "type": "LIMIT",                        //订单类型  LIMIT-限价,MARKET-市价 
    "timeInForce": "GTC",                   //有效方式  GTC,IOC,FOK,GTX
    "price": "40000",                       //价格
    "origQty": "2",                         //原始数量
    "origQuoteQty": "48000",                //原始金额
    "executedQty": "1.2",                   //已执行数量
    "leavingQty": "string",                 //待执行数量（若撤单或下单拒绝，该值为0）
    "tradeBase": "2",                       //成交标的(成交数量)
    "tradeQuote": "48000",                  //成交报价(成交金额)
    "avgPrice": "42350",                    //成交均价
    "fee": "string",                        //手续费
    "feeCurrency": "string",                //手续费币种
    "state": "NEW",                         //订单状态 NEW-新建,PARTIALLY_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time_in_force撤单或溢价撤单)
    "time": 1655958915583,                  //订单时间
    "updatedTime": 1655958915583            //订单更新时间
  }
}
```

## 单笔查询

`GET` `/spot/v4/order`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| orderId | number | false | | 订单ID | |
| clientOrderId | string | false | | 客户端订单号 | |

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "symbol": "BTC_USDT",                   //交易对
    "orderId": "6216559590087220004",       //订单号
    "clientOrderId": "16559590087220001",   //客户端订单号
    "baseCurrency": "string",               //标的币种
    "quoteCurrency": "string",              //报价币种
    "side": "BUY",                          //订单方向 BUY-买,SELL-卖
    "type": "LIMIT",                        //订单类型  LIMIT-限价,MARKET-市价 
    "timeInForce": "GTC",                   //有效方式  GTC,IOC,FOK,GTX
    "price": "40000",                       //价格
    "origQty": "2",                         //原始数量
    "origQuoteQty": "48000",                //原始金额
    "executedQty": "1.2",                   //已执行数量
    "leavingQty": "string",                 //待执行数量（若撤单或下单拒绝，该值为0）
    "tradeBase": "2",                       //成交标的(成交数量)
    "tradeQuote": "48000",                  //成交报价(成交金额)
    "avgPrice": "42350",                    //成交均价
    "fee": "string",                        //手续费
    "feeCurrency": "string",                //手续费币种
    "state": "NEW",                         //订单状态 NEW-新建,PARTIALLY_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time_in_force撤单或溢价撤单)
    "time": 1655958915583,                  //订单时间
    "updatedTime": 1655958915583            //订单更新时间
  }
}
```

## 单笔下单

`POST` `/spot/v4/order`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| symbol | string | true | | 交易对 | |
| clientOrderId | string | false | | 客户端ID正则：^\[a-zA-Z0-9\_]\{4,32}\$ | |
| side | string | true | | 买卖方向  BUY-买,SELL-卖 | |
| type | string | true | | 订单类型  LIMIT-限价,MARKET-市价 | |
| timeInForce | string | true | | 有效方式 GTC, FOK, IOC, GTX | |
| bizType | string | true | | 业务类型  SPOT-现货, LEVER-杠杆 | |
| price | number | false | | 价格。限价必填; 市价不填 | |
| quantity | number | false | | 数量。限价必填；市价按数量下单时必填 | |
| quoteQty | number | false | | 金额。限价不填；市价按金额下单时必填 | |

### 备注

按照市价创建BUY订单时，quantity为空，quoteQty必填；按照市价创建SELL订单时，quoteQty为空，quantity必填。

### 限流规则

20/s/apikey

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "orderId": "6216559590087220004"   //订单ID
  }
}
```

## 单笔撤单

`DELETE` `/spot/v4/order/{orderId}`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| orderId | number | true | | 订单ID | |

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "cancelId": "6216559590087220004"
  }
}
```

## 批量获取

`GET` `/spot/v4/batch-order`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| orderIds | string | true | | 订单ID集合，逗号分割 eg:  6216559590087220004,6216559590087220004 | |

reponse 字段信息参考单笔订单获取接口

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [
    {
      "symbol": "BTC_USDT",
      "orderId": "6216559590087220004",
      "clientOrderId": "16559590087220001",
      "baseCurrency": "string",
      "quoteCurrency": "string",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "GTC",
      "price": "40000",
      "origQty": "2",
      "origQuoteQty": "48000",
      "executedQty": "1.2",
      "leavingQty": "string",
      "tradeBase": "2",
      "tradeQuote": "48000",
      "avgPrice": "42350",
      "fee": "string",
      "feeCurrency": "string",
      "state": "NEW",
      "time": 1655958915583,
      "updatedTime": 1655958915583
    }
  ]
}
```

## 批量撤单

`DELETE` `/spot/v4/batch-order`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| clientBatchId | string | false | | 客户端批次号 | |
| orderIds | array | true | | 集合\[6216559590087220004,6216559590087220005] | |

注意：参数以json形式放在body中

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {}
}
```

## 查询当前挂单

`GET` `/spot/v4/open-order`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| symbol | string | false | | 交易对，不传代表所有 | |
| bizType | string | false | | 业务类型  SPOT-现货, LEVER-杠杆 | |
| side | string | false | | BUY-买,SELL-卖 | |

### 限流规则

10/s/apikey

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": [      //字段信息参考单笔订单获取接口
    {
      "symbol": "BTC_USDT",
      "orderId": "6216559590087220004",
      "clientOrderId": "16559590087220001",
      "baseCurrency": "string",
      "quoteCurrency": "string",
      "side": "BUY",
      "type": "LIMIT",
      "timeInForce": "GTC",
      "price": "40000",
      "origQty": "2",
      "origQuoteQty": "48000",
      "executedQty": "1.2",
      "leavingQty": "string",
      "tradeBase": "2",
      "tradeQuote": "48000",
      "avgPrice": "42350",
      "fee": "string",
      "feeCurrency": "string",
      "state": "NEW",
      "time": 1655958915583,
      "updatedTime": 1655958915583
    }
  ]
}
```

## 撤销当前挂单

`DELETE` `/spot/v4/open-order`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| symbol | string | true | | 交易对，不传代表所有 | |
| bizType | string | true | | 业务类型  SPOT-现货, LEVER-杠杆 | |
| side | string | true | | BUY-买,SELL-卖 | |

### 限流规则

10/s/apikey\
注意：参数以json形式放在body中

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {}
}
```

## 历史订单查询

`GET` `/spot/v4/history-order`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| symbol | string | false | | 交易对，不传代表所有 | |
| bizType | string | false | | 业务类型  SPOT-现货, LEVER-杠杆 | |
| side | string | false | | BUY-买,SELL-卖 | |
| type | string | false | | 订单类型   LIMIT-限价, MARKET-市价 | |
| state | string | false | | 订单状态 NEW-新建,PARTIALLY\_FILLED-部分成交,FILLED-全部成交,CANCELED-用户撤单,REJECTED-下单失败,EXPIRED-过期(time\_in\_force撤单或溢价撤单) | |
| fromId | number | false | | 起始ID | |
| direction | string | false | | 查询方向:PREV, NEXT | |
| limit | number | false | 20 | 限制数量,最大100 | |
| startTime | number | false | | 开始时间 eg:1657682804112 | |
| endTime | number | false | | 结束时间 | |
| hiddenCanceled | bool | false | | 隐藏已取消 | |

### 限流规则

10/s/apikey

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "hasPrev": true,
    "hasNext": true,
    "items": [   //内容信息参考单笔获取订单接口
      {
        "symbol": "BTC_USDT",
        "orderId": "6216559590087220004",
        "clientOrderId": "16559590087220001",
        "baseCurrency": "string",
        "quoteCurrency": "string",
        "side": "BUY",
        "type": "LIMIT",
        "timeInForce": "GTC",
        "price": "40000",
        "origQty": "2",
        "origQuoteQty": "48000",
        "executedQty": "1.2",
        "leavingQty": "string",
        "tradeBase": "2",
        "tradeQuote": "48000",
        "avgPrice": "42350",
        "fee": "string",
        "feeCurrency": "string",
        "state": "NEW",
        "time": 1655958915583,
        "updatedTime": 1655958915583
      }
    ]
  }
}
```

## 成交查询

`GET` `/spot/v4/trade`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| symbol | string | false | | 交易对，不传代表所有 | |
| bizType | string | false | | 业务类型  SPOT-现货, LEVER-杠杆 | |
| orderSide | string | false | | BUY-买,SELL-卖 | |
| orderType | string | false | | 订单类型   LIMIT-限价, MARKET-市价 | |
| orderId | number | false | | 订单号 | |
| fromId | number | false | | 分页起始ID | |
| direction | string | false | | 查询方向:PREV, NEXT | |
| limit | number | false | 20 | 限制数量,最大100 | |
| startTime | number | false | | 开始时间 eg:1657682804112 | |
| endTime | number | false | | 结束时间 | |

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "hasPrev": true,
    "hasNext": true,
    "items": [
      {
        "symbol": "BTC_USDT",               //交易对
        "tradeId": "6316559590087222001",   //成交单号
        "orderId": "6216559590087220004",   //订单号
        "orderSide": "BUY",                 //订单方向
        "orderType": "LIMIT",               //订单类型
        "bizType": "SPOT",                  //业务类型
        "time": 1655958915583,              //成交时间
        "price": "40000",                   //成交价格
        "quantity": "1.2",                  //成交数量
        "quoteQty": "48000",                //成交金额
        "baseCurrency": "BTC",              //标的币种类型
        "quoteCurrency": "USDT",            //报价币种类型
        "fee": "0.5",                       //手续费资产金额
        "feeCurrency": "USDT",              //手续费资产类型
        "takerMaker": "taker"               //takerMaker
      }
    ]
  }
}
```

## 获取单个币种资产

`GET` `/spot/v4/balance`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| currency | string | true | | eg:usdt | |

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "currency": "usdt",     //币种
    "currencyId": 0,        //币种ID
    "frozenAmount": 0,      //冻结数量
    "availableAmount": 0,   //可用数量
    "totalAmount": 0,       //总数量
    "convertBtcAmount": 0   //折算BTC数量
  }
}
```

## 获取币种资产列表

`GET` `/spot/v4/balances`

**Parameters**

| 参数 | 数据类型 | 是否必须 | 默认值 | 描述 | 取值范围 |
| - | - | - | - | - | - |
| currencies | string | false | | 币种列表,逗号分隔，eg:  usdt,btc | |

### 限流规则

10/s/apikey

```json Response theme={null}
{
  "rc": 0,
  "mc": "string",
  "ma": [
    {}
  ],
  "result": {
    "totalBtcAmount": 0,
    "assets": [    //参数内容参考获取单个币种资产接口
      {        
        "currency": "string",
        "currencyId": 0,
        "frozenAmount": 0,
        "availableAmount": 0,
        "totalAmount": 0,
        "convertBtcAmount": 0
      }
    ]
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.