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

## 签名生成

以[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进行交易 |
| SYMBOL\_007 | 该交易对暂不支持改单 |
| SYMBOL\_010 | 该市场不支持您进行交易 |
| SYMBOL\_011 | 由于该交易币对属于高风险币种，平台暂时限制该交易对的交易，如需交易，请通过在线客服申请 |
| 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 | 触发市价保护滤器 |
| ORDER\_F0704 | 杠杠限价订单爆仓价格限制 |
| COMMON\_001 | 用户不存在 |
| COMMON\_002 | 系统繁忙，请稍后再试 |
| COMMON\_003 | 操作失败，请稍后再试 |
| CURRENCY\_001 | 币种信息异常 |
| DEPOSIT\_001 | 充值暂未开放 |
| DEPOSIT\_002 | 当前账号安全等级较低，请绑定手机/邮箱/谷歌身份验证器中的任意两种安全验证后再进行充值 |
| DEPOSIT\_003 | 地址格式不正确，请重新输入 |
| DEPOSIT\_004 | 地址已存在，请重新输入 |
| DEPOSIT\_005 | 冷钱包地址未找到 |
| DEPOSIT\_006 | 暂无充值地址，请稍后再试 |
| DEPOSIT\_007 | 地址生成中，请稍后再试 |
| DEPOSIT\_008 | 不支持充值 |
| WITHDRAW\_001 | 提现暂未开放 |
| WITHDRAW\_002 | 提币地址不合法 |
| WITHDRAW\_003 | 当前账号安全等级较低，请绑定手机/邮箱/谷歌身份验证器中的任意两种安全验证后再进行提现 |
| WITHDRAW\_004 | 未添加提币地址 |
| WITHDRAW\_005 | 提币地址不能为空 |
| WITHDRAW\_006 | Memo不能为空 |
| WITHDRAW\_008 | 触发风控，暂不支持该币提现 |
| WITHDRAW\_009 | 提现失败，本次提现中部分资产受T+1提币限制 |
| WITHDRAW\_010 | 提币精度不合法 |
| WITHDRAW\_011 | 可用余额不足 |
| WITHDRAW\_012 | 提现失败，您今日剩余提现额度不足 |
| WITHDRAW\_013 | 提现失败，您今日剩余提现额度不足，可通过完成更高等级的实名认证提高额度 |
| WITHDRAW\_014 | 该笔提现地址不能使用内部转账功能，请取消内部转账功能后再提交 |
| WITHDRAW\_015 | 提现金额不足以抵扣手续费 |
| WITHDRAW\_016 | 提币地址已经存在 |
| WITHDRAW\_017 | 本次提币已处理，无法取消 |
| WITHDRAW\_018 | Memo必须为数字 |
| WITHDRAW\_019 | Memo不正确，请重新输入 |
| WITHDRAW\_020 | 您今日提现额度已达上限，请明天再试 |
| WITHDRAW\_021 | 您今日提现额度已达上限，本次最多只能提现\{0} |
| WITHDRAW\_022 | 提现金额必须大于\{0} |
| WITHDRAW\_023 | 提现金额必须小于\{0} |
| WITHDRAW\_024 | 不支持提现 |
| WITHDRAW\_025 | 请前往充值页面创建FIO地址 |
| FUND\_001 | 请求重复（一个bizId请求多次接口） |
| FUND\_002 | 余额不足 |
| FUND\_003 | 划转操作不支持 （比如子账户不支持理财划入划出） |
| FUND\_004 | 解冻失败 |
| FUND\_005 | 划转禁止 |
| FUND\_014 | 划入账户id和划出账户id不可以一样 |
| FUND\_015 | from和to 业务类型不可相同（用户不可以操作自己现货划转到现货） |
| FUND\_016 | 杠杆交易对不可为空 |
| FUND\_017 | 参数错误 |
| FUND\_018 | 冻结记录无效 |
| FUND\_019 | 解冻用户不相等 |
| FUND\_020 | 解冻币种不相等 |
| FUND\_021 | 操作不支持 |
| FUND\_022 | 冻结记录不存在 |
| FUND\_044 | 金额最大长度为113 不可超过限制 |
| SYMBOL\_001 | 交易对不存在 |
| TRANSFER\_001 | 请求重复（一个bizId请求多次接口） |
| TRANSFER\_002 | 余额不足 |
| TRANSFER\_003 | 用户未注册 |
| TRANSFER\_004 | 币种不允许划转 |
| TRANSFER\_005 | 用户币种不允许划转 |
| TRANSFER\_006 | 划转禁止 |
| TRANSFER\_007 | 请求超时 |
| TRANSFER\_008 | 杠杆划入异常 |
| TRANSFER\_009 | 杠杆划出异常 |
| TRANSFER\_010 | 杠杆清零 划出禁止 |
| TRANSFER\_011 | 杠杆有借贷 划出禁止 |
| TRANSFER\_012 | 币种划转禁止 |
| GATEWAY\_0001 | 触发风控 |
| GATEWAY\_0002 | 触发风控 |
| GATEWAY\_0003 | 触发风控 |
| GATEWAY\_0004 | 触发风控 |

## 公共模块

### 订单状态码及含义

| State | 说明 |
| - | - |
| NEW | 新建 |
| PARTIALLY\_FILLED | 部分成交 |
| FILLED | 全部成交 |
| CANCELED | 用户撤单 |
| REJECTED | 下单失败 |
| EXPIRED | 过期(time\_in\_force撤单或溢价撤单) |

### 订单类型及含义

| Type | 说明 |
| - | - |
| LIMIT | 限价单 |
| MARKET | 市价单 |

### 交易对状态及含义

| State | 说明 |
| - | - |
| ONLINE | 上线的 |
| OFFLINE | 下线的 |
| DELISTED | 退市的 |

### 有效方式及含义

这里定义了订单多久能够失效

| TimeInForces | 说明 |
| - | - |
| GTC | 成交为止,一直有效 |
| IOC | 无法立即成交(吃单)的部分就撤销 |
| FOK | 无法全部立即成交就撤销 |
| GTX | 只挂单，触发成交条件会被立即撤销 |

### 充值/提现记录状态码及含义

| Status | 说明 |
| - | - |
| SUBMIT | 提现: 未冻结 |
| REVIEW | 提现: 已冻结,待审核 |
| AUDITED | 提现: 已审核,发送钱包,待上链 |
| AUDITED\_AGAIN | 复审中 |
| PENDING | 充值/提现: 已上链 |
| SUCCESS | 完成 |
| FAIL | 失败 |
| CANCEL | 已取消 |

### BizType

| Status | Description |
| - | - |
| SPOT | 现货 |
| LEVER | 杠杠 |
| FINANCE | 理财 |
| FUTURES\_U | 合约u本位 |
| FUTURES\_C | 合约币本位 |

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