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

正式:

**U本位合约:[https://fapi.monochrome.exchange](https://fapi.monochrome.exchange)**

**币本位合约:[https://dapi.monochrome.exchange](https://dapi.monochrome.exchange)**

## 接口的基本信息

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

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

请求头信息请设置为：Content-Type=application/x-www-form-urlencoded

除了接口本身所需的参数外，还需要在query Params 或 request body中传递 signature, 即签名参数，不需要传递签名参数的接口会额外说明。

## 限频规则

获取资产每秒3次，其他方法单个用户每秒10次，单个IP每分钟1000次，超出锁定账户10分钟。

## 签名说明

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

1、线下分配appkey和secretkey，针对不同的调用，提供不同的appkey和secretkey

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

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

4、加入recvwindow(自定义请求有效时间)，有效时间目前相对简单统一固定为某个值，比如：同api同appid下10分钟内数据都有郊，此处可以再进步优化到具体单个api有效时间都不相同。

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

不推荐使用5秒以上的recvWindow

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

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

## 签名生成

[http://fapi.monochrome.exchange/future/api/v1/public/symbol/detail?symbol=btc\_usdt的示例](http://fapi.monochrome.exchange/future/api/v1/public/symbol/detail?symbol=btc_usdt的示例)

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

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header部分数据：

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

validate-timestamp: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9

validate-algorithms: HmacSHA256

请求数据：

\{
type: ‘LIMIT’,
timeInForce: ‘GTC’,
side: ‘BUY’,
symbol: ‘btc\_usdt’,
price: ‘39000’,
quantity: ‘2’
}

1、数据部分

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

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

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

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

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

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

路径Path示例：

```text theme={null}
      /future/api/v1/public/symbol/detail

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

示例 1: 所有参数通过 query string 发送

```text theme={null}
        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        上述值拼接记作query
```

示例 2: 所有参数通过 request body 发送

x-www-form-urlencoded的request  body string :

```text theme={null}
        symbol=btc_usdt&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1

        上述值拼接记作body
```

json的request body string :

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

        上述值拼接记作body
```

示例 3: 混合使用 query string 与 request body(分为表单与json两种格式)

queryString: symbol=btc\_usdt\&side=BUY\&type=LIMIT\&timeInForce=GTC
上述拼接值记作query

requestBody: \{“quantity”:2,”price”:39000}
上述拼接值记作body

```text theme={null}
    整个数据最且拼接值由#符号分别与path、query、body进行拼接成#path、#query、#body，最终拼接值记作为Y=#path#query#body。

    注意：

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

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

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

2、请求头部分
X=”validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085\&validate-timestamp=1641446237201”

3、生成签名

最终把需要进行加密的字符串，记作为sign=XY

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

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

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

## API 代码库

Java connector

一个轻量级的Java代码库，提供让用户直接调用API的方法。

各个语言的sdk：

```text theme={null}
  java: https://github.com/monochrome-ex/monochrome-java-demo
```

## 返回格式

所有的接口返回都是JSON格式。

```json Response theme={null}
{
    "returnCode": 200,
    "result": {
        "serverTime": 1636612706739
    },
    "msgInfo": "Success."
    "error": null,
}
```

## 错误代码

| 状态码 | 错误信息 |
| - | - |
| 200 | 成功 |
| 401 | 需要登录 |
| 403 | 登录过期 |
| invalid\_params | 参数异常 |
| invalid\_order | 订单异常 |
| invalid\_symbol | 错误的市场 |
| invalid\_price | 错误的价格 |
| invalid\_order\_type | orderType 必传 |
| invalid\_order\_side | orderSide 必传 |
| invalid\_triggerProfitPrice | 止盈价格错误 |
| invalid\_triggerStopPrice | 止损价格错误 |
| invalid\_leader | 交易员不存在 |
| invalid\_accountId | accountId错误 |
| invalid\_leverage | 杠杆倍数错误 |


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