> ## 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.

# 快速开始

> 用户中心 API：快速开始。

## REST API

**生产环境: [https://api.monochrome.exchange](https://api.monochrome.exchange)**

## 接口的基本信息

鉴于延迟高和稳定性差等原因，不建议通过代理的方式访问API。

GET请求参数放入query Params中，POST请求参数放入request body中

请求头信息请设置为：Content-Type=application/json

对于/public以外开头的请求，需要对请求报文进行签名

## 限频规则

部分接口会有限流控制(对应接口下会有限流说明)，限流主要分为网关限流和WAF限流。

若接口请求触发了网关限流则会返回429，表示警告访问频次超限，即将被封IP或者apiKey。

网关限流分为针对IP和apiKey限流。

IP限流示例说明：100/s/ip，表示每个IP每秒该接口请求次数限制。

apiKey限流示例说明：50/s/apiKey，表示每个apiKey每秒该接口请求次数限制。

## 签名说明

由于 Monochrome 需要为第三方平台提供一些开放性的接口，所以需要接口的数据安全问题，比如数据是否被篡改，数据是否已过时，数据是否可以重复提交，接口在某个时间内访问频率等问题。其中数据是否被篡改是最重要的。

1、先通过用户中心申请appkey和secretkey，针对不同的调用，提供不同的appkey和secretkey

2、加入timestamp(时间戳)，其值应当是请求发送时刻的unix时间戳(毫秒)，数据的有郊时间根据此值来计算。

3、加入signature(数据签名)，所有数据的签名信息。

4、加入recvwindow(自定义请求有效时间)，有效时间目前相对简单统一固定为某个值。

服务器收到请求时会判断请求中的时间戳，最长60秒，最小为2秒，如果是5000毫秒之前发出的，则请求会被认为无效。这个时间窗口值可以通过发送可选参数recvWindow来设置。
另外，如果服务器计算得出客户端时间戳在服务器时间的‘未来’一秒以上，也会拒绝请求。
关于交易时效性 互联网状况并不100%可靠，不可完全依赖,因此你的程序本地到 Monochrome 服务器的时延会有抖动. 这是我们设置recvwindow的目的所在，如果你从事高频交易，对交易时效性有较高的要求，可以灵活设置recvwindow以达到你的要求。

不推荐使用5秒以上的recvwindow

5、加入algorithms (签名方法/算法)，用户计算签名是基于哈希的协议，推荐使用HmacSHA256。具体支持那些协议，请参见下面表格中所列出。

```text theme={null}
HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256(推荐)、HmacSHA384、HmacSHA512
```

| 字段名 | 是否必须 | 示例 | 说明 |
| - | - | - | - |
| validate-appkey | true | dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83 | |
| validate-timestamp | true | 1641446237201 | |
| validate-signature | true | 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d | |
| validate-recvwindow | true | 5000(毫秒) | |
| validate-algorithms | true | HmacSHA256 | HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512，默认为：HmacSHA256 |
| validate-signversion | false | 1.0 | 保留，签名版本号 |

## 签名生成

以[https://sapi.monochrome.exchange/v4/order为例。](https://sapi.monochrome.exchange/v4/order为例。)

以下是在linux bash环境下使用 echo openssl 和curl工具实现的一个调用接口下单的示例 appkey、secret仅供示范：

appKey: 3976eb88-76d0-4f6e-a6b2-a57980770085

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据：

```text theme={null}
validate-algorithms: HmacSHA256

validate-appkey: 3976eb88-76d0-4f6e-a6b2-a57980770085

validate-recvwindow: 5000

validate-timestamp: 1641446237201

validate-signature: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9
```

请求数据：

```text theme={null}
{
  type: 'LIMIT',
  timeInForce: 'GTC',
  side: 'BUY',
  symbol: 'btc_usdt',
  price: '39000',
  quantity: '2'
}
```

1、数据部分

```text theme={null}
method: 大写的请求方法，例如：GET、POST、DELETE、PUT

path: 按照path中顺序将所有value进行拼接。形如/test/{var1}/{var2}/的restful路径将按填入的实际参数后路径拼接，示例：/sign/test/bb/aa

query: 按照key的字典序排序，将所有key=value进行拼接。示例：userName=dfdfdf&password=ggg

body:   
    Json: 直接按JSON字符串不做转换或排序操作。

    x-www-form-urlencoded: 按照key的字典序排序，将所有key=value进行拼接，示例:userName=dfdfdf&password=ggg　

    form-data：此格式暂不支持。

如果存在多种数据形式，则按照path、query、body的顺序进行再拼接，得到所有数据的拼接值。
```

方法method示例：

```text theme={null}
POST
```

路径path示例:

```text theme={null}
/v4/order

上述拼接值记作为path
```

参数通过query示例:

```text theme={null}
symbol=btc_usdt

上述值拼接记作query
```

参数通过body示例

```text theme={null}
x-www-form-urlencoded:
  
    symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

    上述值拼接记作body

json:

    {"symbol":"btc_usdt","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":2,"price":39000}

    上述值拼接记作body
```

混合使用query与body(分为表单与json两种格式)

```text theme={null}
query: 
    symbol=btc_usdt&side=BUY&type=LIMIT
    上述拼接值记作query

body: 
    {"symbol":"btc_usdt","side":BUY,"type":"LIMIT"}
    上述拼接值记作body
```

整个数据最且拼接值由#符号分别与method、path、query、body进行拼接成#method、#path、#query、#body，最终拼接值记作为Y=#method#path#query#body。
注意：

```text theme={null}
query有数据，body无数据：Y=#method#path#query

query无数据，body有数据：Y=#method#path#body

query有数据，body有数据：Y=#method#path#query#body
```

2、请求头部分
将key按照字母自然升序后，使用&方式拼接在一起，作为X。如：

```text theme={null}
    validate-algorithms=HmacSHA256&validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085&validate-recvwindow=5000&validate-timestamp=1641446237201
```

3、生成签名

```text theme={null}
最终把需要进行加密的字符串，记作为original=XY

最后将最终拼接值按照如下方法进行加密得到签名。

signature=org.apache.commons.codec.digest.HmacUtils.hmacSha256Hex(secretkey, original);

将生成的签名singature放到请求头中，以validate-signature为Key，以singature为值。
```

4、样例

```text theme={null}
签名原始报文样例：

    validate-algorithms=HmacSHA256&validate-appkey=2063495b-85ec-41b3-a810-be84ceb78751&validate-recvwindow=60000&validate-timestamp=1666026215729#POST#/v4/order#{"symbol":"BTC_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}

请求报文样例：
  
    curl --location --request POST 'https://sapi.monochrome.exchange/v4/order' 
    --header 'accept: */*' 
    --header 'Content-Type: application/json' 
    --header 'validate-algorithms: HmacSHA256' 
    --header 'validate-appkey: 10c172ca-d791-4da5-91cd-e74d202dac96' 
    --header 'validate-recvwindow: 60000' 
    --header 'validate-timestamp: 1666026215729' 
    --header 'validate-signature: 4cb36e820f50d2e353e5e0a182dc4a955b1c26efcb4b513d81eec31dd36072ba' 
    --data-raw '{"symbol":"BTC_USDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","bizType":"SPOT","price":3,"quantity":2}'

注意事项：
    注意检查 Content-Type、签名原始报文中的参数格式、请求报文中的参数格式
```

## 响应代码

| httpStatus | 描述 |
| - | - |
| 200 | 请求成功，请进一步查看rc、mc部分 |
| 404 | 接口不存在 |
| 429 | 请求过于频繁，请按照限速要求，控制请求速率 |
| 500 | 服务异常 |
| 502 | 网关异常 |
| 503 | 服务不可用，请稍后重试 |

| rc | return Code |
| - | - |
| 0 | 业务成功 |
| 1 | 业务失败 |

| mc | message code |
| - | - |
| SUCCESS | 成功 |
| FAILURE | 失败 |
| NO\_OPERATION\_PERMISSION | 当前账户无操作权限 |
| PERMISSION\_LIMIT | 不允许操作不属于自己的资源 如:删除别的用户apiKey 或者子账户 |
| ACCOUNT\_HAVE\_API | 该账户存在apikey无法删除 |
| ACCOUNT\_NAME\_EXIST | 账户名已存在 |
| SUB\_ACCOUNT\_LIMIT | 子账户创建超过限制 |
| MASTER\_ACCOUNT\_REMOVE\_LIMIT | 不允许删除主账户 |


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