> ## 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://sapi.monochrome.exchange](https://sapi.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、签名原始报文中的参数格式、请求报文中的参数格式
```

## API 代码库

Java connector

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

各个语言的sdk：

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

## 响应格式

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

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

## 响应代码

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

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

| mc | message code |
| - | - |
| SUCCESS | 成功 |
| FAILURE | 失败 |
| AUTH\_001 | 缺少请求头 validate-appkey |
| AUTH\_002 | 缺少请求头 validate-timestamp |
| AUTH\_003 | 缺少请求头 validate-recvwindow |
| AUTH\_004 | 错误的请求头 validate-recvwindow |
| AUTH\_005 | 缺少请求头 validate-algorithms |
| AUTH\_006 | 错误的请求头 validate-algorithms |
| AUTH\_007 | 缺少请求头 validate-signature |
| AUTH\_101 | ApiKey不存在 |
| AUTH\_102 | ApiKey未激活 |
| AUTH\_103 | 签名错误 |
| AUTH\_104 | 非绑定IP请求 |
| AUTH\_105 | 报文过时 |
| AUTH\_106 | 超出apikey权限 |
| SYMBOL\_001 | 交易对不存在 |
| SYMBOL\_002 | 交易对未开盘 |
| SYMBOL\_003 | 交易对暂停交易 |
| SYMBOL\_004 | 此交易对不支持您所在的国家 |
| SYMBOL\_005 | 该市场不支持通过API进行交易 |
| ORDER\_001 | 平台拒单 |
| ORDER\_002 | 资金不足 |
| ORDER\_003 | 交易对暂停交易 |
| ORDER\_004 | 禁止交易 |
| ORDER\_005 | 订单不存在 |
| ORDER\_006 | 过多的未完成订单 |
| ORDER\_007 | 子账户暂无交易权限 |
| ORDER\_008 | 当前下单价格或数量精度异常 |
| ORDER\_F0101 | 触发价格过滤器-最小值 |
| ORDER\_F0102 | 触发价格过滤器-最大值 |
| ORDER\_F0103 | 触发价格过滤器-步进值 |
| ORDER\_F0201 | 触发数量过滤器-最小值 |
| ORDER\_F0202 | 触发数量过滤器-最大值 |
| ORDER\_F0203 | 触发数量过滤器-步进值 |
| ORDER\_F0301 | 触发金额过滤器-最小值 |
| ORDER\_F0401 | 触发开盘保护滤器或限价保护过滤器 |
| ORDER\_F0501 | 触发限价保护滤器-买单最大偏离度 |
| ORDER\_F0502 | 触发限价保护滤器-卖单最大偏离度 |
| ORDER\_F0503 | 触发限价保护滤器-买单限制系数 |
| ORDER\_F0504 | 触发限价保护滤器-卖单限制系数 |
| ORDER\_F0601 | 触发市价保护滤器 |
| COMMON\_001 | 用户不存在 |
| COMMON\_002 | 系统繁忙，请稍后再试 |
| COMMON\_003 | 操作失败，请稍后再试 |
| CURRENCY\_001 | 币种信息异常 |
| SYMBOL\_001 | 交易对不存在 |
| GATEWAY\_0001 | 触发风控 |
| GATEWAY\_0002 | 触发风控 |
| GATEWAY\_0003 | 触发风控 |
| GATEWAY\_0004 | 触发风控 |
| COPY\_TRADE\_SPOT\_000 | 系统繁忙，请稍后再试 |
| COPY\_TRADE\_SPOT\_001 | 您已经是交易员 |
| COPY\_TRADE\_SPOT\_002 | 您有跟随的交易员 |
| COPY\_TRADE\_SPOT\_003 | 您已提交交易员申请，无须重复申请 |
| COPY\_TRADE\_SPOT\_004 | 您未实名认证或实名认证等级不满足申请规则 |
| COPY\_TRADE\_SPOT\_005 | 您的账户总资产不满足申请规则 |
| COPY\_TRADE\_SPOT\_006 | 带单员不存在 |
| COPY\_TRADE\_SPOT\_007 | 您已提交带单员申请，不支持跟单 |
| COPY\_TRADE\_SPOT\_008 | 跟单保证金超出限制范围 |
| COPY\_TRADE\_SPOT\_009 | 跟单比例超出限制范围 |
| COPY\_TRADE\_SPOT\_010 | 带单员跟随者已满员 |
| COPY\_TRADE\_SPOT\_011 | 超过最大可跟随人数 |
| COPY\_TRADE\_SPOT\_012 | 止盈价格精度异常 |
| COPY\_TRADE\_SPOT\_013 | 止损价格精度异常 |
| COPY\_TRADE\_SPOT\_014 | 止盈触发价需大于最新成交价 |
| COPY\_TRADE\_SPOT\_015 | 止损触发价需小于最新成交价 |
| COPY\_TRADE\_SPOT\_016 | 当前带单员存在现货带单订单，不允许解约 |

## 公共模块

### 查询类型

| Type | 说明 |
| - | - |
| 1 | 请求订单明细信息 |
| 2 | 请求订单汇总信息 |

### 跟单用户类型

| User status | 说明 |
| - | - |
| LEADER | 带单员 |
| FOLLOWER | 跟单员 |
| NONE | 其他 |

### 跟单员类型

| Type | Description |
| - | - |
| 1 | 当前跟随 |
| 2 | 历史跟随 |

### 跟随类型

| Follow type | Description |
| - | - |
| FUND | 按照固定金额跟单. |
| RATE | 按照资金比例跟单. |

### 跟单止损仓位处理

| FollowLossOperate | 说明 |
| - | - |
| MARKET\_SELL | 立即市价全平 |
| LEADER\_CLOSE | 跟随带单员平仓 |
| MANUAL\_PROCESS | 手动处理 |

## FAQ

1.AUTH\_105：服务器在校验请求头参数validate-timestamp(validTimeStamp)、validate-recvwindow（recvwindow）时，
需要符合以下规则：dealTimeStamp（请求被处理时服务器时间,单位毫秒）- validTimeStamp \< recvwindow ，否则就会返回AUTH\_105，为了避免此错误，建议validate-timestamp 设置为请求发出的时间，以毫秒为单位，validate-recvwindow设置的大一点


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