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

> Spot API: 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
```

## 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 |
| SYMBOL\_007 | The trading pair does not support order modification |
| SYMBOL\_010 | This market does not support your trading |
| SYMBOL\_011 | Due to the high-risk nature of this trading pair, the platform has temporarily restricted trading for it. If you wish to trade, please contact our online customer service for approval. |
| 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 |
| ORDER\_F0704 | Liquidation price limit for leveraged limit orders |
| 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 |
| DEPOSIT\_001 | Deposit is not open |
| DEPOSIT\_002 | The current account security level is low, please bind any two security verifications in mobile phone/email/Google Authenticator before deposit |
| DEPOSIT\_003 | The format of address is incorrect, please enter again |
| DEPOSIT\_004 | The address is already exists, please enter again |
| DEPOSIT\_005 | Can not find the address of offline wallet |
| DEPOSIT\_006 | No deposit address, please try it later |
| DEPOSIT\_007 | Address is being generated, please try it later |
| DEPOSIT\_008 | Deposit is not available |
| WITHDRAW\_001 | Withdraw is not open |
| WITHDRAW\_002 | The withdrawal address is invalid |
| WITHDRAW\_003 | The current account security level is low, please bind any two security verifications in mobile phone/email/Google Authenticator before withdraw |
| WITHDRAW\_004 | The withdrawal address is not added |
| WITHDRAW\_005 | The withdrawal address cannot be empty |
| WITHDRAW\_006 | Memo cannot be empty |
| WITHDRAW\_008 | Risk control is triggered, withdraw of this currency is not currently supported |
| WITHDRAW\_009 | Withdraw failed, some assets in this withdraw are restricted by T+1 withdraw |
| WITHDRAW\_010 | The precision of withdrawal is invalid |
| WITHDRAW\_011 | free balance is not enough |
| WITHDRAW\_012 | Withdraw failed, your remaining withdrawal limit today is not enough |
| WITHDRAW\_013 | Withdraw failed, your remaining withdrawal limit today is not enough, the withdrawal amount can be increased by completing a higher level of real-name authentication |
| WITHDRAW\_014 | This withdrawal address cannot be used in the internal transfer function, please cancel the internal transfer function before submitting |
| WITHDRAW\_015 | The withdrawal amount is not enough to deduct the handling fee |
| WITHDRAW\_016 | This withdrawal address is already exists |
| WITHDRAW\_017 | This withdrawal has been processed and cannot be canceled |
| WITHDRAW\_018 | Memo must be a number |
| WITHDRAW\_019 | Memo is incorrect, please enter again |
| WITHDRAW\_020 | Your withdrawal amount has reached the upper limit for today, please try it tomorrow |
| WITHDRAW\_021 | Your withdrawal amount has reached the upper limit for today, you can only withdraw up to \{0} this time |
| WITHDRAW\_022 | Withdrawal amount must be greater than \{0} |
| WITHDRAW\_023 | Withdrawal amount must be less than \{0} |
| WITHDRAW\_024 | Withdraw is not supported |
| WITHDRAW\_025 | Please create a FIO address in the deposit page |
| FUND\_001 | Duplicate request (a bizId can only be requested once) |
| FUND\_002 | Insufficient account balance |
| FUND\_003 | Transfer operations are not supported (for example, sub-accounts do not support financial transfers) |
| FUND\_004 | Unfreeze failed |
| FUND\_005 | Transfer prohibited |
| FUND\_014 | The transfer-in account id and transfer-out account ID cannot be the same |
| FUND\_015 | From and to business types cannot be the same |
| FUND\_016 | Leverage transfer, symbol cannot be empty |
| FUND\_017 | Parameter error |
| FUND\_018 | Invalid freeze record |
| FUND\_019 | Freeze users not equal |
| FUND\_020 | Freeze currency are not equal |
| FUND\_021 | Operation not supported |
| FUND\_022 | Freeze record does not exist |
| FUND\_044 | The maximum length of the amount is 113 and cannot exceed the limit |
| SYMBOL\_001 | Symbol does not exist |
| TRANSFER\_001 | Duplicate request (a bizId can only be requested once) |
| TRANSFER\_002 | Insufficient account balance |
| TRANSFER\_003 | User not registered |
| TRANSFER\_004 | The currency is not allowed to be transferred |
| TRANSFER\_005 | The user’s currency is not allowed to be transferred |
| TRANSFER\_006 | Transfer prohibited |
| TRANSFER\_007 | Request timed out |
| TRANSFER\_008 | Transferring to a leveraged account is abnormal |
| TRANSFER\_009 | Departing from a leveraged account is abnormal |
| TRANSFER\_010 | Leverage cleared, transfer prohibited |
| TRANSFER\_011 | Leverage with borrowing, transfer prohibited |
| TRANSFER\_012 | Currency transfer prohibited |
| GATEWAY\_0001 | Trigger risk control |
| GATEWAY\_0002 | Trigger risk control |
| GATEWAY\_0003 | Trigger risk control |
| GATEWAY\_0004 | Trigger risk control |

## Public module

### Order state

| State | Description |
| - | - |
| NEW | The order has been accepted by the engine. |
| PARTIALLY\_FILLED | A part of the order has been filled. |
| FILLED | The order has been completed. |
| CANCELED | The order has been canceled by the user. |
| REJECTED | The order was not accepted by the engine and not processed. |
| EXPIRED | The order has expired (e.g. Order canceled due to timeout or canceled due to premium) |

### Order type

| Type | Description |
| - | - |
| LIMIT | Limit price order |
| MARKET | Market price order |

### Symbol state

| State | Description |
| - | - |
| ONLINE | The symbol is online |
| OFFLINE | The symbol is offline |
| DELISTED | The symbol has been delisted |

### Time in force

This sets how long an order will be active before expiration.

| TimeInForces | Description |
| - | - |
| GTC | It remains valid until the transaction is concluded. |
| IOC | Cancel the part that cannot be transacted immediately (taking orders) |
| FOK | Cancellation if all transactions cannot be completed immediately |
| GTX | Only pending orders, the triggering of transaction conditions will be cancelled immediately |

### Deposit/Withdraw status

| Status | Description |
| - | - |
| SUBMIT | The withdrawal amount is not frozen. |
| REVIEW | The withdrawal amount has been frozen and is pending review. |
| AUDITED | The withdraw has been reviewed and is ready to on-chaining. |
| AUDITED\_AGAIN | Reexamine |
| PENDING | The deposit or withdraw is already on-chaining. |
| SUCCESS | The deposit or withdraw is success. |
| FAIL | The deposit or withdraw failed. |
| CANCEL | The deposit or withdraw has been canceled by the user. |

### BizType

| Status | Description |
| - | - |
| SPOT | spot account |
| LEVER | Leverage account |
| FINANCE | Financial account |
| FUTURES\_U | USDT-M futures account |
| FUTURES\_C | COIN-M futures account |

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