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

# Getting started

> User center API: getting started.

## REST API

**production environment: [https://api.monochrome.exchange](https://api.monochrome.exchange)**

## Basic information of the interface

Due to reasons such as high latency and poor stability, it is not recommended to access the API through a proxy.

GET request parameters are placed in query Params, POST request parameters are placed in request body

Please set the request header information to：Content-Type=application/json

For requests that start other than /public, the request message needs to be signed

## Frequency Limiting Rules

Some interfaces will have limited flow control (the corresponding interface will have a limited flow description). The flow limit is mainly divided into gateway flow limit and WAF flow limit.

If the interface request triggers the gateway flow limit, 429 will be returned, indicating that the access frequency exceeds the limit, and the IP or apiKey will be blocked.

Gateway flow limiting is divided into IP and apiKey flow limiting.

Example description of IP flow limit: 100/s/ip, indicating the limit of the number of requests per second for this interface per IP.

apiKey current limit example description: 50/s/apiKey, indicating the limit of the number of requests per second for the interface per apiKey.

## Signature Instructions

Since Monochrome needs to provide some open interfaces for third-party platforms，therefore, the issue of data security needs to be considered. Such as whether the data has been tampered with, whether the data is outdated, whether the data can be submitted repeatedly, and the access frequency of the interface, and whether data has been tampered with is the most important issue.

1. Please apply for appkey and secretkey in the user center first, each user’s appkey and secretkey are different.
2. Add timestamp, its value should be the unix timestamp (milliseconds) of the time when the request is sent, and the time of the data is calculated based on this value.
3. Add signature, its value is obtained by a certain rule of signature algorithm.
4. Add recvwindow (defining the valid time of the request), the valid time is currently relatively simple and uniformly fixed at a certain value.

When a request is received by the server, the timestamp in the request is checked to ensure it falls between 2 to 60 seconds. Any request with a timestamp older than 5,000 milliseconds is considered invalid.
The time window value can be set using the optional parameter: “recvWindow”. Additionally, if the server determines that the client’s timestamp is more than one second ahead of the server, the request will also be invalid.
Online conditions are not always 100% reliable in terms of the timeliness of trades, resulting in varying levels of latency between your local program and the Monochrome server. This is why we provide the “recvWindow” parameter - if you engage in high-frequency trading and require stricter transaction timeliness, you can adjust the “recvWindow” parameter to better meet your needs.

Recvwindow longer than 5 seconds is not recommended.

5、Added algorithm (signature method/algorithm), the user calculates the signature according to the protocol of the hash, and HmacSHA256 is recommended. For those protocols that are supported, see the table below.

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

| Name | Mandatory | Example | Description |
| - | - | - | - |
| validate-appkey | true | dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83 | |
| validate-timestamp | true | 1641446237201 | |
| validate-signature | true | 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d | |
| validate-recvwindow | true | 5000(millisecond) | |
| validate-algorithms | true | HmacSHA256 | HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512，The default is：HmacSHA256 |
| validate-signversion | false | 1.0 | reserved, signed version number |

## Signature generation

Take [https://sapi.monochrome.exchange/v4/order](https://sapi.monochrome.exchange/v4/order) as an example.

The following is an example appkey and secret for placing an order using a call interface implemented by echo openssl and curl tools in the linux bash environment for demonstration purposes only:

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Header part data：

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

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

validate-recvwindow: 5000

validate-timestamp: 1641446237201

validate-signature: 2b5eb11e18796d12d88f13dc27dbbd02c2cc51ff7059765ed9821957d82bb4d9
```

request data：

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

1.data part

```text theme={null}
method: UpperCase method. eg: GET, POST, DELETE, PUT

path: Concatenate all values in the order in path. The restful path in the form of /test/{var1}/{var2}/ will be spliced according to the actual parameters filled in, for example: /sign/test/bb/aa

query: Sort all key=value according to the lexicographical order of the key. Example: userName=dfdfdf&password=ggg

body:   
    Json: Directly by JSON string without conversion or sorting.

    x-www-form-urlencoded: Sort all key=values according to the lexicographical order of keys, for example: userName=dfdfdf&password=ggg

    form-data：This format is not currently supported.

If there are multiple data forms, re-splicing is performed in the order of path, query, and body to obtain the splicing value of all data.
```

Method example:

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

Path example:

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

The above concatenated value is recorded as path
```

Parameters passed query example:

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

The above concatenated value is recorded as query
```

Parameters via body example

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

    The above concatenated value is recorded as body

json:

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

    The above concatenated value is recorded as body
```

Mixed use of query and body (divided into form and json format)

```text theme={null}
query: 
    symbol=btc_usdt&side=BUY&type=LIMIT
    The above concatenated value is recorded as query

body: 
    {"symbol":"btc_usdt","side":BUY,"type":"LIMIT"}
    The above concatenated value is recorded as body
```

The most concatenated value of the entire data is spliced with method, path, query, and body by the # symbol to form #method, #path, #query, and #body, and the final spliced value is recorded as Y=#method#path#query#body.
Notice：

```text theme={null}
The query has data, but the body has no data: Y=#method#path#query

query has no data, body has data: Y=#method#path#body

query has data, body has data: Y=#method#path#query#body
```

2.request header part
After the keys are in natural ascending alphabetical order, use & to join them together as X. like:

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

3.generate signature

```text theme={null}
Finally, the string that needs to be encrypted is recorded as original=XY

Finally, encrypt the final concatenated value according to the following method to obtain a signature.

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

Put the generated signature singature in the request header, with validate-signature as the key and singature as the value.
```

4.example

```text theme={null}
sample of original signature message:
  
    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}

sample request message:

    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}'    

matters needing attention:

    Pay attention to checking the parameter format of Content Type, signature original message and request message
```

## response code

| httpStatus | description |
| - | - |
| 200 | The request is successful, please check the rc and mc sections further |
| 404 | interface does not exist |
| 429 | The request is too frequent, please control the request rate according to the speed limit requirement |
| 500 | Service exception |
| 502 | Gateway exception |
| 503 | Service unavailable, please try again later |

| rc | return Code |
| - | - |
| 0 | business success |
| 1 | business failure |

| mc | message code |
| - | - |
| SUCCESS | success |
| FAILURE | fail |
| NO\_OPERATION\_PERMISSION | current account does not have permission to operate |
| PERMISSION\_LIMIT | it’s not allowed to operate other user resources, such as: delete other user apiKey or sub-account |
| ACCOUNT\_HAVE\_API | account has an apikey that cannot be deleted |
| ACCOUNT\_NAME\_EXIST | account name already exists |
| SUB\_ACCOUNT\_LIMIT | the number of sub-accounts exceeds the limit |
| MASTER\_ACCOUNT\_REMOVE\_LIMIT | deletion of master account is not allowed |


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