Quick Start

Preparation

Before using the API, you need to log in to the website and create an API key with the proper permissions.

You can manage your API keys by clicking here.

Each user account can create up to 10 API keys, each with two permissions:

• Read permission: used to query data, e.g. quotation data.

• Trade permission: used to create orders, cancel orders, and perform transfers.

Please remember below information after creation:

• APIKey this key is included in API requests to identify the origin of the request.

• Secretkey used to generate the signature (visible only once after creation).

• Passphrase used to further secure your API access. Note that the passphrase cannot be recovered if lost, so a new API key would need to be generated.

When creating an API key, you have the option to bind it to a specific IP address. For security reasons, it is highly recommended to bind an IP address to your API key. This adds an extra layer of security and ensures that your API key can only be used from the designated IP address.

Risk Note: API key, secret key, and passphrase are crucial to account security. Keep passphrase safe and do not reveal keys. Loss of keys may result in asset loss. If API key is compromised, delete immediately.

Endpoint Security Type

This section mainly divides the endpoint type into two aspects:：

• Public endpoint Endpoints can be accessed freely.

• Private endpoint Endpoints require authentication using your API Key.

Limits

Rest API will return 429 status when access exceeds the frequency limit: too frequent requests.

Rest API

If a valid API Key is provided, frequency will be limited by API Key, otherwise it will be limited by public IP. Frequency limit rules vary per endpoint, with a general limit of 10 requests/s.

The Base Endpoint

You can use The Base Endpoint access method to operate by yourself.

Name	The Base Endpoint	Suggestion
Domain1	https://contract-openapi.weex.com	International

Endpoints Authentication

Making Requests

All REST requests must include the following headers:

• ACCESS-KEY：Your API Key as a string.

• ACCESS-SIGN：Base64 encoded signatures (see Signing messages).。

• ACCESS-TIMESTAMP：The timestamp of your request.

• ACCESS-PASSPHRASE：The passphrase you set when creating the API Key.

• Content-Type：Always set to"application/json"。

• locale: Supports multiple languages such as Chinese (zh-CN) and English (en-US).

The Signature

ACCESS-SIGN The request header is correct timestamp + method.toUpperCase() + requestPath + "?" + queryString + body String (+ represents string concatenation) is used HMAC SHA256 Method encrypt and pass*BASE64* Produced by encoding the output.

Signature field

• timestamp: matches the "access-Timestamp" header

• method: uppercase request method (POST/GET)

• requestPath: path of the requested endpoint

• queryString: query string in the URL after the "?" symbol

• body: string representation of request body, can be omitted if no body in request (usually GET requests).

When the queryString is empty, the signature format

timestamp + method.toUpperCase() + requestPath + body

Signature format when queryString is not empty

timestamp + method.toUpperCase() + requestPath + "?" + queryString + body

For example

Get the depth information of the contract. Take cmt_btcusdt as an example:

• Timestamp = 1591089508404

• Method = "GET"

• requestPath = "/api/swap/v3/market/depth"

• queryString= "?symbol=cmt_btcusdt&limit=20"

Generate the string to be signed:

'1591089508404GET/api/swap/v1/market/depth?symbol=cmt_btcusdt&limit=20'

Order by contract, take cmt_btcusdt as an example:

• Timestamp = 1561022985382

• Method = "POST"

• requestPath = "/api/swap/v3/order/placeOrder"

• body = {"symbol":"cmt_btcusdt","size":"8","type":"1","match_price":"1","order_type":"1","client_oid":"ww#123456"}

Generate the string to be signed:

'1561022985382POST/api/swap/v3/order/placeOrder{"symbol":"cmt_btcusdt","size":"8","type":"1","match_price":"1","order_type":"1","client_oid":"ww#123456"}'

The steps to generate the final signature

Step 1, encrypt the string to be signed with hmac sha256 using the private key secretkey

Signature = hmac_sha256(secretkey, Message)

Step 2, Base64 encoding for Signature

Signature = base64.encode(Signature)

Request interaction

All requests are based on the Https protocol, and the Content-Type in the request header should be set to: 'application/json'.

Request interaction specification

• Request parameters: Parameter encapsulation according to the interface request parameter

• Submit request parameters: The encapsulated request parameters are submitted to the server via GET/POST.

• Server response: The server first checks the user request data for parameter security, and after passing the check, the response data is sent as JSON format is returned to the user.。

• Data processing: Processing of server response data.

Successful

The HTTP status code 200 indicates a successful response and may contain content. If the response contains content, it is displayed in the corresponding return content.

Common Error Code

• 400 Bad Request – Invalid request format

• 401 Unauthorized – Invalid API Key

• 403 Forbidden – You do not have access to the requested resource

• 404 Not Found

• 429 Too Many Requests

• 500 Internal Server Error – We had a problem with our server

• If you fail, the body has an error description

Standard Specification

The Timestamp

This is a security measure to validate the timeliness of a client request in a web application. The request signature includes an access-Timestamp in milliseconds and the request is considered expired and rejected if it is more than 30 seconds away from the API service time. To avoid rejection due to time deviation, it's recommended to update the HTTP header by querying the API server time.

Limited Frequency Rules

This is rate limiting, where excessive requests are restricted and the client receives a "429 Too Many Requests" HTTP status code.

• Public endpoint such as the quotation endpoint, uniform frequency limit of up to 20 requests/second.

• Private endpoint Limits calls to authorization interfaces through apiKey, referring to frequency limiting rules for each endpoint.

The Request Format

Currently there are only two formats of request methods: GET and POST

• GET: The parameters are passed to the server in the path via the queryString.

• POST: The parameter is sent in JSON format to the body for transfer to the server.