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

# Spot: getting started

> Copy trading API: spot: getting started.

## REST API

**production environment: [https://sapi.monochrome.exchange](https://sapi.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
```

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

## response format

All interface returns are in JSON format.

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

## 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 |
| 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 |
| SYMBOL\_001 | Symbol not exist |
| SYMBOL\_002 | Symbol offline |
| SYMBOL\_003 | Symbol suspend trading |
| SYMBOL\_004 | Symbol country disallow trading |
| SYMBOL\_005 | The symbol does not support trading via API |
| ORDER\_001 | Platform rejection |
| ORDER\_002 | insufficient funds |
| ORDER\_003 | Trading Pair Suspended |
| ORDER\_004 | no transaction |
| ORDER\_005 | Order not exist |
| ORDER\_006 | Too many open orders |
| ORDER\_007 | The sub-account has no transaction authority |
| ORDER\_008 | The order price or quantity precision is abnormal |
| ORDER\_F0101 | Trigger Price Filter - Min |
| ORDER\_F0102 | Trigger Price Filter - Max |
| ORDER\_F0103 | Trigger Price Filter - Step Value |
| ORDER\_F0201 | Trigger Quantity Filter - Min |
| ORDER\_F0202 | Trigger Quantity Filter - Max |
| ORDER\_F0203 | Trigger Quantity Filter - Step Value |
| ORDER\_F0301 | Trigger QUOTE\_QTY Filter - Min Value |
| ORDER\_F0401 | Trigger PROTECTION\_ONLINE Filter or PROTECTION\_LIMIT Filter |
| ORDER\_F0501 | Trigger PROTECTION\_LIMIT Filter - Buy Max Deviation |
| ORDER\_F0502 | Trigger PROTECTION\_LIMIT Filter - Sell Max Deviation |
| ORDER\_F0503 | Trigger PROTECTION\_LIMIT Filter - Buy Limit Coefficient |
| ORDER\_F0504 | Trigger PROTECTION\_LIMIT Filter - Sell Limit Coefficient |
| ORDER\_F0601 | Trigger PROTECTION\_MARKET Filter |
| COMMON\_001 | The user does not exist |
| COMMON\_002 | System busy, please try it later |
| COMMON\_003 | Operation failed, please try it later |
| CURRENCY\_001 | Information of currency is abnormal |
| SYMBOL\_001 | Symbol does not exist |
| GATEWAY\_0001 | Trigger risk control |
| GATEWAY\_0002 | Trigger risk control |
| GATEWAY\_0003 | Trigger risk control |
| GATEWAY\_0004 | Trigger risk control |
| COPY\_TRADE\_SPOT\_000 | The system is busy, please try again later |
| COPY\_TRADE\_SPOT\_001 | You are already a leader |
| COPY\_TRADE\_SPOT\_002 | You already have a leader |
| COPY\_TRADE\_SPOT\_003 | You have already submitted your leader application |
| COPY\_TRADE\_SPOT\_004 | You have not completed real-name authentication or your real-name authentication level does not meet the application requirements |
| COPY\_TRADE\_SPOT\_005 | Your account total assets do not meet the application requirements |
| COPY\_TRADE\_SPOT\_006 | The leader does not exist |
| COPY\_TRADE\_SPOT\_007 | You have already submitted your leader application, follow order is not supported |
| COPY\_TRADE\_SPOT\_008 | The copy margin exceeds the limit |
| COPY\_TRADE\_SPOT\_009 | The copy order ratio exceeds the limit |
| COPY\_TRADE\_SPOT\_010 | The number of followers is full |
| COPY\_TRADE\_SPOT\_011 | Exceeded the maximum number of followers |
| COPY\_TRADE\_SPOT\_012 | The precision of the take-profit price is abnormal |
| COPY\_TRADE\_SPOT\_013 | The precision of the stop-loss price is abnormal |
| COPY\_TRADE\_SPOT\_014 | The take-profit trigger price must be greater than the latest transaction price |
| COPY\_TRADE\_SPOT\_015 | The stop-loss trigger price must be less than the latest transaction price |
| COPY\_TRADE\_SPOT\_016 | The leader has spot orders and is not allowed to cancel the termination |

## Public module

### Leader order request type

| Type | Description |
| - | - |
| 1 | Query order details. |
| 2 | Query order summary information. |

### Copy trade user status

| User status | Description |
| - | - |
| LEADER | Copy trade leader |
| FOLLOWER | Copy trade follower |
| NONE | None |

### Leader type

| Type | Description |
| - | - |
| 1 | Current follow |
| 2 | History follow |

### Copy trade follow type

| Follow type | Description |
| - | - |
| FUND | Copy trading according to fixed amount. |
| RATE | Copy trading according to fund ratio. |

### Copy stop loss position processing

| FollowLossOperate | Description |
| - | - |
| MARKET\_SELL | Immediately settle at market price |
| LEADER\_CLOSE | Follow the lead to close the position |
| MANUAL\_PROCESS | Manual Processing |

## FAQ

1.AUTH\_ 105: The server verifies the request header parameters validate-timestamp (validTimeStamp) and validate-recvwindow (recvwindow)
The following rules must be followed: dealTimeStamp (server time when the request is processed, in milliseconds) - validTimeStamp \< recvwindow, otherwise AUTH\_105 will be returned.
To avoid this error, validate-timestamp recommends using the time when the request was sent, and it is measured in milliseconds. The validate-recvwindow is set a little larger


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