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

> Third-party OAuth API: getting started.

## REST API

Official:

**[https://oapi.monochrome.exchange](https://oapi.monochrome.exchange)**

## Basic Information of the Interface

Due to the reasons of high latency and poor stability, it is not recommend to access the Monochrome API through a proxy.

GET request parameters are put in query Params, POST request parameters are put in request body.

The request header information is set to: Content-Type=application/x-www-form-urlencoded

In addition to the parameters required by the interface itself, signature, which is the signature parameter, needs to be passed in the query Params or request body. The interface that does not need to pass the signature parameter will be additionally explained.

## Frequency Limiting Rules

Get assets 3 times per second, other methods 10 times per second for each single user, 1000 times per minute for each single IP, exceeding the requested times, account will be locked for 10 minutes.

## Token Instructions

If the third-party platform is accessible to the user-authorized interface, you need to add an additional access-token field to the interface Header, how to get access-token please refer to [here](https://doc.monochrome.exchange/#third_party_oauth2_cngetToken)

## Signature Statement

Since Monochrome needs to provide some open interfaces for third-party platforms, it requires data security issues of the interface, such as whether the data has been tampered with, whether the data is outdated, whether the data can be submitted repeatedly, and the frequency of access to the interface within a certain period of time. Among them, whether the data has been tampered with is most important.

1. Offline distribution of appkey and secretkey, for different calls, provide different appkey and secretkey.
2. Add timestamp, the value of which should be the unix timestamp (milliseconds) of the time when the request is sent, and the valid time of the data is calculated according to this value.
3. Add signature information for all data.
4. Add recvwindow, the valid time is relatively simple and fixed to a certain value. For example, the data is valid within 10 minutes under the same api and appid. Here, it can be further optimized to the valid time of a single api is different.

The server determines the timestamp when it receives a request. Up to 60 seconds, and the default is 5 seconds. If it was sent 5000 milliseconds ago, the request will be considered invalid. This time window value can be customized by sending the optional parameter recvWindow. In addition, the server will also reject the request if it calculates that the client timestamp is more than one second ‘in the future’ of server time. Regarding the transaction timeliness, the Internet is not 100% reliable and cannot be completely relied upon, so your application’s local time delay to the Monochrome server may be jitter.This is the purpose of setting recvWindow. If you are engaged in high-frequency trading and have high requirements for trading timeliness, you can flexibly set recvWindow to meet your requirements.

RecvWindow for more than 5 seconds is not recommended.

5、5. Add algorithms (signature method/algorithm). User’s signature calculation is a HSC-based protocol, where HmacSHA256 is used by default. See the specific supported protocols listed in the table below.

| Name | Mandatory | Example | Description |
| - | - | - | - |
| validate-appkey | true | dbefbc809e3e83c283a984c3a1459732ea7db1360ca80c5c2c8867408d28cc83 | |
| validate-timestamp | true | 1641446237201 | |
| validate-signature | true | 0a7d0b5e802eb5e52ac0cfcd6311b0faba6e2503a9a8d1e2364b38617877574d | |
| validate-recvwindow | false | 5000(millisecond) | |
| validate-algorithms | false | HmacSHA256 | HmacMD5、HmacSHA1、HmacSHA224、HmacSHA256、HmacSHA384、HmacSHA512，默认为：HmacSHA256 |
| api-version | false | 1.0 | Reserved, API version number |
| validate-signversion | false | 1.0 | Reserved, signature version number |

## Obtain Signature

Example for [http://oapi.monochrome.exchange/api/v1/public/symbol/detail?symbol=btc\_usdt](http://oapi.monochrome.exchange/api/v1/public/symbol/detail?symbol=btc_usdt)

The following is an example of an order placed in a call interface using echo openssl and curl tools in a Linux bash environment. Appkey, secret for demonstration purposes only:

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

secretKey: bc6630d0231fda5cd98794f52c4998659beda290

Partial data of Header：

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

validate-timestamp: 1641446237201

validate-algorithms: HmacSHA256

Request data：

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

1、Data

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: Sorted by lexicographic order of key, concatenate all key=value. Example: userName=dfdfdf\&password=ggg

body: Json: Operate as JSON string is not converted or sorted.

```text theme={null}
      x-www-form-urlencoded: Sorted by lexicographic order of key, concatenate all key=value. Example: userName=dfdfdf&password=ggg　

      form-data：Not supported.
```

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

Example of Path:

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

      The above concatenated value is recorded as path
```

Example 1: All parameters sent via query string

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

        The above concatenate value is recorded as query
```

Example 2: All parameters send X-www-form-urlencoded request body string via the request body

Request body string of json

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

        The above concatenate value is recorded as body
```

Request body string of www-form-urlencoded

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

        The above concatenate value is recorded as body
```

Example 3: Mix to use query string and request body (form and json format)

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

requestBody: \{“quantity”:2,”price”:39000}
The above concatenate value is recorded as query

```text theme={null}
    The final concatenate value of the entire data is # concatenated with path, query, and body and form #path, #query, and #body. The finalconcatenate value is recorded asY=#path#query#body。

    Note:

        query without data, body with data:Y=#path#body

        query with data, body without data:Y=#path#query

        query with data, body with data:Y=#path#query#body
```

2:Request header
X=”validate-appkey=3976eb88-76d0-4f6e-a6b2-a57980770085\&validate-timestamp=1641446237201”

3:Obtain Signature

Finally, record the string that needs to be encrypted as sign=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, sign);

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

## How to Apply for API Key

The interface may require the user’s API Key,How to create API-KEY please contact the operator.

## API Library

Java connector

A lightweight Java codebase that provides methods that allow users to directly call the API。
Sdks for each language:

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

## Return Format

All interfaces’ returns are in JSON format.

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

## Error 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 |
| AUTH\_001 | missing request header validate-appkey |
| AUTH\_002 | missing request header validate-timestamp |
| AUTH\_003 | missing request header validate-recvwindow |
| AUTH\_004 | bad request header validate-recvwindow |
| AUTH\_005 | missing request header validate-algorithms |
| AUTH\_006 | bad request header validate-algorithms |
| AUTH\_007 | missing request header validate-signature |
| AUTH\_101 | ApiKey does not exist |
| AUTH\_102 | ApiKey is not activated |
| AUTH\_103 | Signature error |
| AUTH\_104 | Unbound IP request |
| AUTH\_105 | outdated message |
| AUTH\_106 | Exceeded apikey permission |


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