OVERVIEW

Introduction

Welcome to HashKey Exchange API Documentation!

HashKey Exchange offers a comprehensive suite of APIs including FIX, REST and Websocket API tailored to cater the needs of institutional-grade clients. Our Exchange API solutions are highly scalable, providing clients with access to real-time market data feeds and insights. Client can easily integrate our Exchange API with their existing systems and applications, enabling them to streamline their workflows.

Exchange offers three types of API Connectivity methods

Rest API

Our REST API offers a simple and secure way to manage orders and monitor your digital asset portfolios. The REST API can be publicly access endpoints via market data endpoints and private authenticated endpoints for trading, funding and account data which require requests to be signed.

Websocket API

Use an asynchronous method (pub/sub) approach to efficiently deliver push notifications for orders, transactions, market and other pertinent information. By subscribing to specific topics of interest, users can receive real-time updates without the need for constant polling.

FIX API

Current available to our Omnibus institutional clients

HashKey Exchange FIX connection is an industry-standard solution for our institutional clients to take advantage of our high availability system. It is specifically engineered to handle large amount of throughput supporting end-to-end order entry, order management and access to our rich liquidity feeds.

Test our sandbox

Please direct any questions or feedback to [[email protected]] to obtain sandbox account.

📘 All 2FA/SMS/Email verification code is defaulted to "123456" in Sandbox environment for ease of use

1. Go to our sandbox website page:

📘 https://hk.sim.hashkeydev.com

2. Go to Settings -> API Management -> Create API

3. Enter API Key name, select API permission and setup IP Access Restriction

Technical Support

General Inquiry

Operating hours: Monday to Friday, 9:00 AM to 6:00 PM HKT

Preferred method of contact： [email protected]

Please provide your inquiry in the following format:

Subject:

Environment: Production / Sandbox Inquiry

Identity: UID / Email

Request Body:

Question:

Emergency Production Trading issue

Operating hours: 7 * 24

For urgent matters during non-office hours, please log in to hashkey.com and contact our online Customer Support team via instant message widget.

UPDATES

2026.02

To meet the demands of institutional users for automated asset management, we have officially launched Earn Channel API support this month. Through a series of new endpoints, users can now programmatically query, subscribe to, and redeem wealth management products, as well as manage related orders, enabling efficient allocation of assets.

Core Features & Earn channel API Overview

Query Available Products

• Endpoint: GET /earn/offers
• Function: Retrieves a list of all available wealth management products for subscription, including key information such as product ID, name, description, estimated APY, currency, subscription limits, and status.
• Use Case: Helps users dynamically discover investable options.

Product Subscription & Management

• Subscribe: POST /earn/purchase
  • Used to subscribe to a specified wealth management product. Required parameters include productId, currency, amount, and a client-defined clOrderId for idempotency.
• Cancel Subscription: DELETE /earn/purchase
  • Cancels a subscription order before it is filled. Requires either the system orderId or the client-defined clOrderId.

Product Redemption & Management

• Redeem: POST /earn/redeem
  • Used to redeem held units of an earn channel product. Supports redemption by specifying either the unit or the percent of the holding. Also requires a clOrderId for idempotency.
• Cancel Redemption: DELETE /earn/redeem
  • Cancels a redemption order before it is filled.

Order & Position Query

• Query Order History: GET /earn/orders
  • Queries historical order records and their detailed status, filterable by product, order type (purchase, redeem, etc.), time range, and more.
• Query Position Overview: GET /earn/balance
  • Fetches the user's current holdings in wealth management products, including comprehensive information such as held units, latest net asset value, and unrealized earnings.

Key Operational Workflow

A typical automated wealth management workflow is as follows:

1. Call GET /earn/offers to check available products.
2. Call POST /earn/purchase to execute a subscription.
3. (Optional) If needed, call DELETE /earn/purchase to cancel the subscription.
4. Call GET /earn/balance to monitor holding values.
5. Call POST /earn/redeem to execute a full or partial redemption.
6. Call GET /earn/orders at any time to verify all operation records.

2026.01

To empower institutional and professional trading clients, we now provide the client-side API integration suite for the Market Place RFQ trading platform. This allows your systems to automate the initiation, monitoring, and management of large, customized trade requests (RFQs) and interact efficiently with Liquidity Providers (LPs). Integration Process & Technical Highlights

Core Operational Workflow

A typical automated RFQ workflow involves the following steps:

• Fetch Tradable Pairs: Call the GET /api/v1/market-place/get-pairs endpoint to confirm if the target trading pair is available and matches your client type.
• Initiate an RFQ: Create an RFQ via the dedicated client-side endpoint (please refer to exclusive technical documentation for specifics Get-MP-Quote-Pairs ). Key required fields include the trading pair, side (buy/sell), quantity (sellAmount), and the RFQ mode (rfqMode).
• Listen to Market & Quote Streams: Subscribe to the public rfqs WebSocket channel for market intelligence. Simultaneously, your system will receive quote notifications for your RFQs via private channels.
• Accept Quote & Track Status: Once a desirable quote is received, accept it via API. You can then track the final status (e.g., SUCCESSFUL, EXPIRED) of that RFQ using the order query endpoints.

Key Data Field Specifications

Pay close attention to the following fields when initiating and managing RFQs:

• rfqId: The unique identifier generated by the system for each RFQ, serving as the index for all subsequent operations.
• buyCcy / sellCcy & sellAmount: Define the trade direction and quantity.
• rfqMode: The RFQ mode (e.g., real-time), which may affect the settlement speed of quotes.
• status: The lifecycle status of the RFQ (e.g., NEW, ACCEPTED, EXPIRED), crucial for determining available actions.
• expireTime: The validity expiry timestamp for the RFQ or a quote. Your system must make decisions before this time.

Real-time Communication (WebSocket)

• Public Channel (rfqs): Subscribing to this channel provides real-time broadcasts of all newly created RFQs across the platform, useful for market analysis.
• Private Channels: You will receive critical real-time events via private channels, such as:
  • Notifications for new quotes from LPs on your RFQs.
  • Confirmation status updates for quotes you have accepted.
  • Final trade execution notices for relevant orders.

Error Handling & Permissions

• Permissions: All related API calls require authentication using your account's API Key and signature.
• Error Codes: Please handle common error codes (e.g., -6100 for insufficient permissions, -6101 for parameter errors) and adjust requests based on API responses. This client-side API suite is designed to help you seamlessly integrate large-volume trading workflows into your own systems, enabling automated and efficient RFQ-based trading.

2025.12

🔐 Core Security Enhancement: Overall API Security Upgrade To build a more robust, proactive defense system, we have completed a comprehensive enhancement of our API security. This upgrade is designed to mitigate potential risks across multiple dimensions, including:

• Introduction of API Key Auto-Expiration: To reduce the security threat posed by idle credentials, any API key that remains unused for 90 consecutive days will be automatically deactivated by the system. Please regularly review your keys to ensure critical ones remain active.
• Mandatory Two-Factor Authentication (2FA) for Critical Operations: If enabled, withdrawals initiated via API now require mandatory 2FA verification. This adds a vital security layer for all fund outflow activities.
• Availability of Custom Risk Control Rules: You can now create personalized monitoring and auto-blocking rules for specific sensitive activities (e.g., large withdrawals), enabling granular control over your account security.

We highly encourage you to leverage these new features. Please find the detailed configuration guide here: Risk Control Rule Configuration Guide

📢 Critical Reminder: API Key Management & Webhook push notification We would like to take this opportunity to reiterate the critical importance of API key security, as they are the core credentials for accessing your account. Please ensure you:

• Establish a regular audit cycle to revoke any unnecessary or idle API keys immediately, and strictly adhere to the "Principle of Least Privilege."
• If a third-party vendor manages your system, please verify that they have implemented stringent security measures, including, but not limited to: encrypting sensitive information, enforcing effective risk isolation, and avoiding hard-coding keys in plain text within code repositories.

Detailed guidance can be found here: General Security Principles for API Key Management

Additionally, institutional clients can subscribe to webhooks to receive notifications for digital currency deposit and withdrawal orders, enabling them to stay updated on the latest movements of digital assets in a more timely manner. Should you have any needs, please contact your account manager for integration details.

2025.11

🔐 Core Features & API Overview

Query Available Products

• Endpoint: GET /api/v1/earn/offers
• Function: Retrieves a list of all available wealth management products for subscription, including key information such as product ID, name, description, estimated APY, currency, subscription limits, and status.
• Use Case: Helps users dynamically discover investable options.

Product Subscription & Management

• Subscribe: POST /api/v1/earn/purchase
  • Used to subscribe to a specified wealth management product. Required parameters include productId, currency, amount, and a client-defined clOrderId for idempotency.
• Cancel Subscription: DELETE /api/v1/earn/purchase
  • Cancels a subscription order before it is filled. Requires either the system orderId or the client-defined clOrderId.

Product Redemption & Management

• Redeem: POST /api/v1/earn/redeem
  • Used to redeem held units of an earn channel product. Supports redemption by specifying either the unit or the percent of the holding. Also requires a clOrderId for idempotency.
• Cancel Redemption: DELETE /api/v1/earn/redeem
  • Cancels a redemption order before it is filled.

Order & Position Query

• Query Order History: GET /api/v1/earn/orders
  • Queries historical order records and their detailed status, filterable by product, order type (purchase, redeem, etc.), time range, and more.
• Query Position Overview: GET /api/v1/earn/balance
  • Fetches the user's current holdings in wealth management products, including comprehensive information such as held units, latest net asset value, and unrealized earnings.

Key Operational Workflow A typical automated wealth management workflow is as follows:

1. Call GET /earn/offers to check available products.
2. Call POST /earn/purchase to execute a subscription.
3. (Optional) If needed, call DELETE /earn/purchase to cancel the subscription.
4. Call GET /earn/balance to monitor holding values.
5. Call POST /earn/redeem to execute a full or partial redemption.
6. Call GET /earn/orders at any time to verify all operation records.

2025.10

🔐 Core Security Enhancement: Overall API Security Upgrade (Effective) To build a more robust, proactive defense system, we have completed a comprehensive enhancement of our API security. This upgrade is designed to mitigate potential risks across multiple dimensions, including:

• Introduction of API Key Auto-Expiration: To reduce the security threat posed by idle credentials, any API key that remains unused for 90 consecutive days will be automatically deactivated by the system. Please regularly review your keys to ensure critical ones remain active.
• Mandatory Two-Factor Authentication (2FA) for Critical Operations: If enabled, withdrawals initiated via API now require mandatory 2FA verification. This adds a vital security layer for all fund outflow activities.
• Availability of Custom Risk Control Rules: You can now create personalized monitoring and auto-blocking rules for specific sensitive activities (e.g., large withdrawals), enabling granular control over your account security. We highly encourage you to leverage these new features. Please find the detailed configuration guide here: Risk Control Rule Configuration Guide

🔄 Service Optimization: API Foreign Exchange Interface Upgrade (Scheduled for November 11, 2025) To provide you with more competitive quotes and a superior service experience, we will be upgrading our Foreign Exchange interface. This upgrade will integrate a new service provider and optimize the interface. Key Changes:

• The Get Quote endpoint /convertCurrency/getQuote now requires the sellAmount as a mandatory parameter. The response also includes a new field: channel (foreign exchange channel).
• The Execute Foreign Exchange endpoint /convertCurrency/transact now only accepts sellAmount as an input parameter and requires the correct channel (returned by the above Get Quote endpoint) to be provided. Please note that this is a breaking change. The request and response fields for initiating quotes (/getQuote) and executing exchanges (/transact) will be modified. Your development team will need to adjust and test the integration code based on the upcoming latest API documentation to ensure a smooth transition.

🔄 API Changes for Multi-Chain Support (Scheduled for Launch on October 27, 2025) Hashkey will soon introduce multi-chain support for a single currency (e.g., for USDT, users can choose different blockchain networks such as ERC20 or TRON for deposits and withdrawals). Correspondingly, the API will introduce a new response field chainType for relevant operations, allowing you to better track the blockchain details of your orders. Please note that the input parameters for all endpoints will remain unchanged. Affected Endpoints:

• /api/v1/whitelist/verify → Returns the new chainType field
• /api/v1/account/depositOrders → Returns the new chainType field
• /api/v1/account/withdrawOrders → Returns the new chainType field
• /api/v1/account/balanceFlow (when Type = deposit/withdraw/refund) → Returns the new vaChainType field
• /api/v1/account/refundOrders → Returns the new chainType field
• Webhook - deposit → Returns the new chainType field
• Webhook - withdrawal → Returns the new chainType field

⚙️ Process Improvement: API-Initiated Refunds for Failed Crypto Deposits (Scheduled for October 28, 2025) To address delays in manual processing for failed deposits, we have automated the refund process. For failed transactions due to specific reasons (e.g., third party wallet address), you can proactively initiate a refund request by calling a dedicated refund API endpoint. The system will then automatically process the refund or route it for manual approval based on predefined rules, significantly improving capital handling efficiency and user experience.

📢 Critical Advisory: API Key Management & Webhook push notification We would like to take this opportunity to reiterate the critical importance of API key security, as they are the core credentials for accessing your account. Please ensure you:

• Establish a regular audit cycle to revoke any unnecessary or idle API keys immediately, and strictly adhere to the "Principle of Least Privilege."
• If a third-party vendor manages your system, please verify that they have implemented stringent security measures, including, but not limited to: encrypting sensitive information, enforcing effective risk isolation, and avoiding hard-coding keys in plain text within code repositories. Detailed guidance can be found here: General Security Principles for API Key Management Additionally, institutional clients can subscribe to webhooks to receive notifications for digital currency deposit and withdrawal orders, enabling them to stay updated on the latest movements of digital assets in a more timely manner. Should you have any needs, please contact your account manager for integration details.

REST API

Get Started

REST Sample

import time
import requests
import hashlib
import hmac
import json
from urllib.parse import urlencode, quote

"""
####################################################################################################################################
# Test REST API
#
# Copyright: Hashkey Trading 2024 All rights reserved.
# Please note the API code is provided "As Is" basis, without warranty of any kind, either express or implied, including
# without limitation, warranties that the API code is free of defects, merchantable, non-infringing or fit for a particular purpose
####################################################################################################################################
"""

class RestAPIClient:
    def __init__(self, base_url, user_key, user_secret):
        """
        Initialize the RestAPIClient with base URL, user key, and user secret.

        Args:
            base_url (str): The base URL of the API.
            user_key (str): The user key for authentication.
            user_secret (str): The user secret for authentication.
        """
        self.base_url = base_url
        self.user_key = user_key
        self.user_secret = user_secret
        self.headers = {
            'X-HK-APIKEY': user_key
        }

    def get_timestamp(self):
        """
        Get the current timestamp in milliseconds.

        Returns:
            int: The current timestamp.
        """
        return int(time.time() * 1000)

    def create_signature(self, content):
        """
        Create HMAC signature for authentication.

        Args:
            content (str): The content to be signed.

        Returns:
            str: The HMAC signature.
        """
        content_bytes = content.encode('utf-8')
        hmac_digest = hmac.new(
            self.user_secret.encode('utf-8'),
            content_bytes,
            hashlib.sha256
        ).hexdigest()
        return hmac_digest

    def place_order(self, symbol, side, order_type, quantity, price=None):
        """
        Place an order.

        Args:
            symbol (str): The trading pair symbol (e.g., ETHUSD).
            side (str): The order side (BUY or SELL).
            order_type (str): The order type (LIMIT or MARKET).
            quantity (str): The order quantity.
            price (str, optional): The order price (required for LIMIT orders).

        Returns:
            dict or None: The JSON response if successful, None otherwise.
        """
        timestamp = self.get_timestamp()
        data = {
            "symbol": symbol,
            "side": side,
            "type": order_type,
            "price": price,
            "quantity": quantity,
            "timestamp": timestamp
        }
        if order_type == 'MARKET':
            del data['price']

        data_string = urlencode(data, quote_via=quote)
        signature = self.create_signature(data_string)
        data['signature'] = signature

        response = requests.post(
            f"{self.base_url}/api/v1/spot/order",
            headers=self.headers,
            data=data
        )

        if response.status_code == 200:
            response_json = response.json()
            print("Response:")
            print(json.dumps(response_json, indent=4))  # Print formatted JSON response
            return response_json
        else:
            try:
                error_json = response.json()
                print("Error:")
                print(json.dumps(error_json, indent=4))  # Print formatted error response
            except json.JSONDecodeError:
                print(f"Error: {response.status_code} - {response.text}")
            return None

if __name__ == '__main__':
    # Example usage:
    # Create an instance of RestAPIClient with your API credentials
    # For Production please use https://api-pro.hashkey.com
    api_client = RestAPIClient(
        base_url="https://api-pro.sim.hashkeydev.com",
        user_key="your_user_key",
        user_secret="your_user_secret"
    )
    # Place an order with the desired parameters
    api_client.place_order("ETHUSDT", "BUY", "LIMIT", "0.01", "3000")

Sandbox Environment

• Restful URL: https://api-pro.sim.hashkeydev.com

• WebSocket: wss://stream-pro.sim.hashkeydev.com

• FIX: fix-gateway.sim.hashkeydev.com

• Website: https://exchange.sim.hashkeydev.com

Production Environment

• Restful URL: https://api-pro.hashkey.com

• WebSocket: wss://stream-pro.hashkey.com

• FIX: fix-gateway.hashkey.com

• Website: https://exchange.hashkey.com

General API Information

• All responses will return a JSON object or array.

• Data is returned in ascending order with the earlier data displayed first and subsequent updates appearing later

• All time or timestamp-related variables are measured in milliseconds (ms)

• HTTP 4XX error code indicate that the request content is invalid. This typically originates from the client's end.

• HTTP 429 error code indicates that the request rate limit has been exceeded.

• HTTP 418 error code when our server have detected the IP address continues to send subsequent requests after receiving 429 error code and is automatically blocked

• HTTP 5XX indicates an internal system error. This signifies that the issue originates within the trading system. When addressing this error, it's important not to immediately categorise it as a failed task. The execution status is uncertain, it could potentially be either successful or unsuccessful.

• For GET endpoints, parameters must be sent as query strings.

• For POST, PUT, and DELETE endpoints, unless explicitly stated otherwise, parameters must be sent as query strings or in the request body with the content type set to application/x-www-form-urlencoded.

• Request Parameters can be sent in any order.

• If there are parameters in both query string and request body, only the parameters of query string will be used.

Access Restrictions

• If any rate limit is violated, a 429 error code will be returned

• Each API endpoint has an associated with a specific weight, and certain endpoints may possess varying weights based on different parameters. Endpoints that consume more resources will have a higher weight assigned to them.

• Upon receiving 429 error code, please take precautionary steps to cease sending requests. API abuse is strictly prohibited

• It is recommended to use Websocket API to obtain corresponding real-time data as much as possible to reduce the traffic of access restrictions caused by frequent API requests.

Order Rate Limiting

• Unless explicitly stated otherwise, each API Key has a default rate limit of 2 requests per second for query-related endpoints, while order-related endpoints allow 10 requests per second.

• When the number of orders exceeds the set limit, a response with an HTTP CODE 429 will be received. Please wait 1 minute for the suspended period to expire.

Endpoint Security Types

• Each endpoint is assigned a security type that determines how you interact with it.

• The API-KEY must be passed in the REST API header as X-APIKEY.

• API-KEY and SECRET-KEY are case-sensitive.

• By default, API-KEY have access to all secure endpoints.

API-KEY Management

• Users have to log in the exchange website and apply for an API-KEY, please make sure to remember the following information when creating an API key:

  • Access key: API access key
  • Secret key: The key used for signature authentication encryption (visible to the application only)

• Users have to assign permissions to API-KEY. There are two kinds of permissions,

  • READ-ONLY PERMISSION: read permission is used for data query interfaces such as order query, transaction query, etc.
  • READ/WRITE PERMISSION:
    • Allow Withdrawal: control whether the API key allow withdrawing VA.
      • /api/v1/account/withdraw
    • Allow Trading: control whether the API key allow trading.
      • /api/v1/spot/order
      • /api/v1.1/spot/order
      • /api/v1/spot/batchOrders
      • /api/v1/spot/openOrders
      • /api/v1/spot/cancelOrderByIds
    • Allow wallet address whitelist: control whether the API key can access endpoints used for the wallet whitelist process.
      • /api/v1/whitelist/walletSigning
      • /api/v1/whitelist/verify
      • /api/v1/account/deposit/address
    • Allow internal transfer: control whether the API key allow internal transfer.
      • /api/v1/account/assetTransfer
    • Allow fiat withdrawal: control whether the API key allow withdrawing fiat.
      • /api/v1/account/fiat/withdraw

Authentication

Endpoint security type

API requests are likely to be tampered during transmission through the internet. To ensure that the request remains unchanged, all private interfaces other than public interfaces (basic information, market data) must be verified by signature authentication via API-KEY to make sure the parameters or configurations are unchanged during transmission.

Each created API-KEY need to be assigned with appropriate permissions in order to access the corresponding interface. Before using the interface, users is required to check the permission type for each interface and confirm there is appropriate permissions.

Signature Authentication

Signature

TRADE & USER_DATA

• The SIGNED (signature required) endpoint needs to send a parameter, signature, in the query string or request body.

• The endpoint is signed with HMAC SHA256. The HMAC SHA256 signature is the result of HMAC SHA256 encryption of the key. Use your secretKey as the key and totalParams as the value to complete this encryption process.

• Signature is not case sensitive.

• totalParams refers to concatenation of the query string and the request body.

All HTTP requests to API endpoints require authentication and authorization. The following headers should be added to all HTTP requests:

Example 1: In queryString

• queryString:

symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000

• HMAC SHA256 signature:

echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"

Shell standard output:

5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6

• curl command:

curl -H "X-HK-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/api/v1/spot/order?symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6'

Example 2: In the request body

• requestBody:

symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000

• HMAC SHA256 signature:

echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"

Shell standard output:

5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6

• curl command:

curl -H "X-HK-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/api/v1/spot/order' -d 'symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6'

Example 3: mixing queryString and request body

• queryString:

symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC

• requestBody:

quantity=1&price=0.1&recvWindow=5000×tamp=1538323200000

• HMAC SHA256 signature:

echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"

Shell standard output:

885c9e3dd89ccd13408b25e6d54c2330703759d7494bea6dd5a3d1fd16ba3afa

• curl command:

curl -H "X-HK-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order?symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=885c9e3dd89ccd13408b25e6d54c2330703759d7494bea6dd5a3d1fd16ba3afa'

Two-Factor Authentication

optional

• Certain API endpoints have been enhanced to support two-factor authentication (2FA) via the twoFaToken field.
• When 2FA is enabled for a user, each relevant request‘s header must include a valid twoFaToken for verification.

The following headers should be added to HTTP requests:

Request Logic

When 2FA is Enabled

• If 2FA is enabled but the request does not include twoFaToken, the API will return an error indicating that 2FA verification is required.
• Each twoFaToken is valid for 30 seconds and can only be used once during its validity period.

When 2FA is Disabled

• The request verification logic remains unchanged.
• If a twoFaToken is provided in the request, it will be ignored.

Affected Endpoints

The following endpoints have options to add the twoFaToken parameter and now invoke the Security Service for 2FA validation:

Time-base security

📘 If your timestamp is ahead of serverTime it needs to be within 1 second + serverTime

The logic of this parameter is as follows:

 if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow)
    // process request
  } else {
    // reject request
  }

📘 A relatively small recvWindow (5000 or less) is recommended!

• For a SIGNED endpoint, an additional parameter "timestamp" needs to be included in the request. This timestamp is in milliseconds and reflect the time when the request was initiated.
• An optional parameter (not mandatory) recvWindow can be used to specify the validity period of the request in milliseconds. If recvWindow is not sent as part of the request, the default value is 5000
• Trading and timeliness are closely interconnected. Network can sometimes be unstable or unreliable, which can lead to inconsistent times when requests are sent to the server.
• With recvWindow, you can specify how many milliseconds the request is valid, otherwise it will be rejected by the server.

Getting Started with Postman

Postman is a popular plug and play API test environment that allows implementing and testing REST and API endpoints.

Postman provides the HTTP networking to connect to the REST API, allows the HTTP header and GET/POST data to be customised and allows for custom code to be executed using Javascript variant.

Pre-request Script

var timestamp = new Date().getTime().toString();
pm.environment.set("timestamp", timestamp);

var api_secret = pm.environment.get("secretKey");
var parameters = pm.request.url.query.toObject(excludeDisabled=true);

var paramsObject = {};

Object.keys(parameters).forEach((paramKey) => {
  var paramValue = parameters[paramKey];
  var disabled = false;

  if (paramKey !== 'signature' && paramValue && !disabled) {
    paramsObject[paramKey] = paramValue;
  }
});

paramsObject.timestamp = timestamp;

var requestString = Object.keys(paramsObject).map((key) => `${key}=${paramsObject[key]}`).join('&');

var signature = CryptoJS.HmacSHA256(requestString, api_secret).toString();
pm.environment.set("signature", signature);

1. Create a new environment and add environment variables
2. Add in the header "X-HK-APIKEY"
3. Add in params for the required endpoint and most important the timestamp and signature
4. Insert the Pre-request script in the above run the API request and press "Send"

Spot Trading

Order Status

• PENDING_NEW - Pending order to be NEW
• NEW - New order, pending to be filled
• PARTIALLY_FILLED - Partially filled
• PARTIALLY_CANCELED - Partially filled and Partially cancelled
• FILLED - Completed filled
• CANCELED - Order cancelled
• REJECTED - Order refers to the rejection of an order during the order matching process.

Order Types

• LIMIT - Limit order
• MARKET - Market order
• LIMIT_MAKER - Maker limit order

Order Direction

• BUY - Buy order
• SELL - Sell Order

TimeInForce

• GTC（Currently only supports limit and limit_maker orders)
• IOC（Currently supports limit and market orders)

Test New Order

POST /api/v1/spot/orderTest

The test endpoint is solely to validate the parameters of the new order, it does not send to matching engine.

Weight: 1

Request Parameters

Response Content

{}

{}

Create Order v1.0

POST /api/v1/spot/order

📘 We provide two endpoints for creating spot trading orders:
1. Legacy Endpoint: /api/v1/spot/order
2. New Endpoint: /api/v1.1/spot/order

• Key Differences:
  • Market Order Support:
    • v1: Supports specifying only the cash amount for market buy orders and the quantity for market sell orders
    • v1.1: Supports specifying both the cash amount and the quantity for market orders, regardless of whether it's a buy or sell order
  • Quantity and Amount:
    • v1: Uses a single 'quantity' parameter for specifying order size
    • v1.1: Splits the order size into separate 'quantity' and 'amount' parameters

Recommendation: For enhanced functionality and flexibility, we strongly recommend using the new v1.1 endpoint (/api/v1.1/spot/order) for all order creations
create-order-v1.1

Certain parameters are mandatory depending on the order type:

Weight: 1

Request Parameters

Response Content

{
  "accountId": "1471090223379184384",
  "symbol": "BTCUSD",
  "symbolName": "BTCUSD",
  "clientOrderId": "1768459741532390",
  "orderId": "2128389008024406016",
  "transactTime": "1768459741535",
  "price": "98001",
  "origQty": "0.01",
  "executedQty": "0",
  "status": "PENDING_NEW",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY",
  "reqAmount": "0",
  "concentration": "",
  "alert": ""
}

Create Order v1.1

POST /api/v1.1/spot/order

Certain parameters are mandatory depending on the order type:

Weight: 1

Request Parameters

Response Content

{
  "accountId": "1471090223379184384",
  "symbol": "BTCUSD",
  "symbolName": "BTCUSD",
  "clientOrderId": "1768459741532390",
  "orderId": "2128389008024406016",
  "transactTime": "1768459741535",
  "price": "98001",
  "origQty": "0.01",
  "executedQty": "0",
  "status": "PENDING_NEW",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY",
  "reqAmount": "0",
  "concentration": "",
  "alert": ""
}

Create Multiple orders by Symbol v1.1

POST /api/v1.1/spot/batchOrders

Create orders in batches up to 20 orders at a time. Currently only support for same symbol.

Weight: 1

Upper Limit: 20 orders/batch

Request Parameters

curl --request POST \
     --url '/api/v1.1/spot/batchOrders?timestamp=1707492562526&signature=f19400b8b39964fd596280bbf03b37d39ff858d97e522a82d4994ecddd961e71' \
     --header 'X-HK-APIKEY: NuVdtBcogpRjyQ6sMMlC6KEB0xuXZbng9zXDPyT0TOWHp64UEkyIJ287bBhaW4vy' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
        [
          {
            "symbol": "BTCUSD",
            "side": "SELL",
            "type": "LIMIT",
            "price": "52000",
            "quantity": "0.01",
            "newClientOrderId": "123456789"
          },
          {
            "symbol": "BTCUSD",
            "side": "BUY",
            "type": "LIMIT",
            "price": "43000",
            "quantity": "0.01",
            "newClientOrderId": "123456790"
          }
        ]
     '

Response Content

{
  "code": 0,
  "result": [
    {
      "code": "0000",
      "order": {
        "accountId": "1471090223379184384",
        "symbol": "BTCUSD",
        "symbolName": "BTCUSD",
        "clientOrderId": "01151450",
        "orderId": "2128390066566072320",
        "transactTime": "1768459867723",
        "price": "98003",
        "origQty": "0.01",
        "executedQty": "0",
        "status": "PENDING_NEW",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "BUY",
        "reqAmount": "0",
        "alert": ""
      }
    },
    {
      "code": "0000",
      "order": {
        "accountId": "1471090223379184384",
        "symbol": "BTCUSD",
        "symbolName": "BTCUSD",
        "clientOrderId": "01151451",
        "orderId": "2128390066574460928",
        "transactTime": "1768459867723",
        "price": "98004",
        "origQty": "0.01",
        "executedQty": "0",
        "status": "PENDING_NEW",
        "timeInForce": "GTC",
        "type": "LIMIT",
        "side": "BUY",
        "reqAmount": "0",
        "alert": ""
      }
    }
  ],
  "concentration": ""
}

Cancel Order

DELETE /api/v1/spot/order

Cancel an existing order. Either orderId or clientOrderId must be sent.

Weight: 1

Request Parameters

Response Content

{
  "accountId": "1464567707961719552",
  "symbol": "ETHUSD",
  "clientOrderId": "99999888912",
  "orderId": "1563291927536863744",
  "transactTime": "1701094920045",
  "price": "1900",
  "origQty": "1",
  "executedQty": "0",
  "status": "NEW",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY"
}

Cancel All Open Orders by Symbol

DELETE /api/v1/spot/openOrders

Cancel all open orders (Same symbol only)

Weight: 1

Upper Limit: 1000 orders/batch

Request Parameters

Response Content

{
  "success": true
}

Cancel Multiple Orders By OrderId

DELETE /api/v1/spot/cancelOrderByIds

Cancel orders in batches according to order IDs (Maximum of 100 orders in a single batch)

Weight: 1

Upper Limit: 100 orders/batch

Request Parameters

Response Content

Success

{
  "code": "0000",
  "result": []
}

Certain error happened

{
  "code": "0000",
  "result": [
    {
      "orderId": "1507155386372816640",
      "code": "0211"
    },
    {
      "orderId": "1507155487740667904",
      "code": "0211"
    }
  ]
}

Query Order

GET /api/v1/spot/order

Check a single order information

Weight: 1

Request Parameters

Response Content

{
  "accountId": "1816094214250944000",
  "exchangeId": "301",
  "symbol": "BTCUSDT",
  "symbolName": "BTCUSDT",
  "clientOrderId": "1753258121083398",
  "orderId": "2000868573824739840",
  "price": "120002",
  "origQty": "0.001",
  "executedQty": "0.001",
  "cummulativeQuoteQty": "120.00101",
  "cumulativeQuoteQty": "120.00101",
  "avgPrice": "120001.01",
  "status": "FILLED",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY",
  "stopPrice": "0.0",
  "icebergQty": "0.0",
  "time": "1753258121171",
  "updateTime": "1753258121278",
  "isWorking": true,
  "reqAmount": "0",
  "feeCoin": "BTC",
  "feeAmount": "0.000002",
  "feeSupplementaryAmount": "0.00000634",
  "sumFeeAmount": "0.000002",
  "platformFeeCoin": "",
  "sumPlatformFeeAmount": "",
  "ordCxlReason": "",
  "stpMode": "EXPIRE_TAKER"
}

Get Current Open Orders

GET /api/v1/spot/openOrders

Query current active orders

Weight: 1

Request Parameters

Response Content

[
  {
    "accountId": "1471090223379184384",
    "exchangeId": "301",
    "symbol": "AAVEUSD",
    "symbolName": "AAVEUSD",
    "clientOrderId": "1766552088727423",
    "orderId": "2112386456560601088",
    "price": "190",
    "origQty": "5",
    "executedQty": "0",
    "cummulativeQuoteQty": "0",
    "cumulativeQuoteQty": "0",
    "avgPrice": "0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "icebergQty": "0.0",
    "time": "1766552088746",
    "updateTime": "1766552088766",
    "isWorking": true,
    "reqAmount": "0",
    "feeSupplementaryAmount": "0",
    "ordCxlReason": "",
    "stpMode": "EXPIRE_TAKER"
  }
]

Get All Traded Orders

GET /api/v1/spot/tradeOrders

Retrieve all traded orders

Weight: 5

Request Parameters

Response Content

[
  {
    "accountId": "1471090223379184384",
    "exchangeId": "301",
    "symbol": "BTCUSD",
    "symbolName": "BTCUSD",
    "clientOrderId": "1766732444548391",
    "orderId": "2113899390835099648",
    "price": "0",
    "origQty": "0.1",
    "executedQty": "0.1",
    "cummulativeQuoteQty": "10000",
    "cumulativeQuoteQty": "10000",
    "avgPrice": "100000",
    "status": "FILLED",
    "timeInForce": "IOC",
    "type": "MARKET",
    "side": "SELL",
    "stopPrice": "0.0",
    "icebergQty": "0.0",
    "time": "1766732444563",
    "updateTime": "1766732444569",
    "isWorking": true,
    "reqAmount": "0",
    "feeSupplementaryAmount": "0",
    "ordCxlReason": "",
    "stpMode": "EXPIRE_TAKER"
  }
]

Futures Trading

Create New Futures Order

POST /api/v2/futures/order

This endpoint allows you to create a new Futures order.

You can get contracts' price, quantity precision configuration data in the Get Exchange Information.

Weight: 1

Request Parameters

{
  "symbol": "BTCUSD-PERPETUAL",
  "side": "BUY",
  "orderType": "LIMIT",
  "baseQty": 0.01,
  "price": 90000,
  "timeInForce": "GTC",
  "clientOrderId": "99999989990119a",
  "timestamp": 1714311403031
}

Response Content

{
  "time": "1768794550630",
  "orderId": "2131197590285846784",
  "clientOrderId": "99999989990119a",
  "symbol": "BTCUSD-PERPETUAL",
  "status": "PENDING_NEW"
}

Query Futures Order

GET /api/v2/futures/order

Weight: 1

Request Parameters

Response Content

{
  "time": "1768812678007",
  "orderId": "2131349653745568000",
  "clientOrderId": "99999989990119c",
  "symbol": "BTCUSD-PERPETUAL",
  "baseAsset": "BTC",
  "quoteAsset": "USD",
  "price": "93000",
  "side": "BUY",
  "orderType": "limit",
  "reduceOnly": false,
  "leverage": "5",
  "originalBaseQty": "0.01",
  "executedBaseQty": "0",
  "originalQuoteQty": "930",
  "executedQuoteQty": "0",
  "avgPrice": "0",
  "timeInForce": "GTC",
  "status": "NEW",
  "stpMode": "EXPIRE_TAKER",
  "ordCxlReason": "",
  "isLiquidationOrder": false,
  "liquidationType": "",
  "slTriggerPrice": "92500",
  "slTriggerBy": "last",
  "tpTriggerPrice": "100000",
  "tpTriggerBy": "last"
}

Cancel Futures Order

DELETE /api/v2/futures/order

Weight: 1

Request Parameters

Response Content

{
  "code": 200,
  "orderId": 2131349653745568000,
  "clientOrderId": "99999989990119c",
  "orderType": "LIMIT"
}

Batch Create New Futures Orders

POST /api/v2/futures/batchOrders

The batchOrders in RequestBody should fill in the order parameters in list of JSON format.
Only support placing orders in same orderType.

Weight: 1

Upper Limit: Max 3 for stop order, Max 20 for all other orderTypes

Request Parameters

curl --request POST \
     --url '/api/v2/futures/batchOrders?timestamp=1714404830102&signature=8c47cf48e****' \
     --header 'X-APIKEY: XAzx6DLW2HNs*******' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
        {
            "symbol":"BTCUSD-PERPETUAL",
            "side":"BUY",
            "orderType":"LIMIT",
            "timeInForce":"GTC",
            "order":[
                {
                    "baseQty":0.01,
                    "price":92561,
                    "clientOrderId":"batchorder0119a"
                },
                {
                    "baseQty":0.05,
                    "price":92562,
                    "clientOrderId":"batchorder0119b"
                }
            ]    
        }
     '

Response Content

{
  "code": "0000",
  "result": [
    {
      "code": "0000",
      "order": {
        "orderId": "2131372568755046656",
        "clientOrderId": "batchorder0119X",
        "symbol": "BTCUSD-PERPETUAL",
        "status": "PENDING_NEW",
        "accountId": "2129188333171126016",
        "transactTime": "1768816219103"
      }
    },
    {
      "code": "0000",
      "order": {
        "orderId": "2131372568763435264",
        "clientOrderId": "batchorder0119Y",
        "symbol": "BTCUSD-PERPETUAL",
        "status": "PENDING_NEW",
        "accountId": "2129188333171126016",
        "transactTime": "1768816225000"
      }
    }
  ]
}

Batch Cancel Futures Orders

DELETE /api/v2/futures/cancelOrders

Weight: 1

Request Parameters

Response Content

{
  "code": "0000",
  "lastOrderId": 0
}

Query Futures Trades

GET /api/v2/futures/userTrades

Weight: 1

Request Parameters

Response Content

[
  {
    "time": "1768921741508",
    "tradeId": "2132264544794839413",
    "orderId": "2132264542060153088",
    "symbol": "BTCUSD-PERPETUAL",
    "price": "87900",
    "quantity": "0.002",
    "commissionAsset": "USD",
    "commission": "0.10548",
    "makerRebate": "0",
    "type": "limit",
    "side": "SELL",
    "realizedPnl": "-9.462854",
    "isMaker": false,
    "ticketId": "4658973823776567335"
  },
  {
    "time": "1768921741508",
    "tradeId": "2132264544794839399",
    "orderId": "2132264542060153088",
    "symbol": "BTCUSD-PERPETUAL",
    "price": "88540.5",
    "quantity": "0.002",
    "commissionAsset": "USD",
    "commission": "0.1062486",
    "makerRebate": "0",
    "type": "limit",
    "side": "SELL",
    "realizedPnl": "-8.181854",
    "isMaker": false,
    "ticketId": "4658973823776567334"
  }
]

Query Futures Open Orders

GET /api/v2/futures/openOrders

Weight: 1

Request Parameters

Response Content

[
  {
    "time": "1768983342494",
    "orderId": "2132781291226532106",
    "clientOrderId": "batchorder0121h",
    "symbol": "BTCUSD-PERPETUAL",
    "baseAsset": "BTC",
    "quoteAsset": "USD",
    "price": "88003",
    "side": "BUY",
    "orderType": "limit",
    "reduceOnly": false,
    "leverage": "5",
    "originalBaseQty": "0.01",
    "executedBaseQty": "0",
    "originalQuoteQty": "880.03",
    "executedQuoteQty": "0",
    "avgPrice": "0",
    "timeInForce": "GTC",
    "status": "NEW",
    "stpMode": "EXPIRE_TAKER",
    "ordCxlReason": "",
    "isLiquidationOrder": false,
    "liquidationType": "",
    "slTriggerPrice": "",
    "slTriggerBy": "",
    "tpTriggerPrice": "",
    "tpTriggerBy": ""
  }
]

Query Futures History Orders

GET /api/v2/futures/historyOrders

Weight: 1

Request Parameters

Response Content

[
  {
    "time": "1768983342494",
    "orderId": "2132781291226532106",
    "clientOrderId": "batchorder0121h",
    "symbol": "BTCUSD-PERPETUAL",
    "baseAsset": "BTC",
    "quoteAsset": "USD",
    "price": "88003",
    "side": "BUY",
    "orderType": "limit",
    "reduceOnly": false,
    "leverage": "5",
    "originalBaseQty": "0.01",
    "executedBaseQty": "0.01",
    "originalQuoteQty": "880.03",
    "executedQuoteQty": "880.03",
    "avgPrice": "88003",
    "timeInForce": "GTC",
    "status": "FILLED",
    "stpMode": "EXPIRE_TAKER",
    "ordCxlReason": "",
    "isLiquidationOrder": false,
    "liquidationType": "",
    "slTriggerPrice": "",
    "slTriggerBy": "",
    "tpTriggerPrice": "",
    "tpTriggerBy": ""
  },
  {
    "time": "1768983342494",
    "orderId": "2132781291226532097",
    "clientOrderId": "batchorder0121g",
    "symbol": "BTCUSD-PERPETUAL",
    "baseAsset": "BTC",
    "quoteAsset": "USD",
    "price": "88002",
    "side": "BUY",
    "orderType": "limit",
    "reduceOnly": false,
    "leverage": "5",
    "originalBaseQty": "0.01",
    "executedBaseQty": "0.01",
    "originalQuoteQty": "880.02",
    "executedQuoteQty": "880.02",
    "avgPrice": "88002",
    "timeInForce": "GTC",
    "status": "FILLED",
    "stpMode": "EXPIRE_TAKER",
    "ordCxlReason": "",
    "isLiquidationOrder": false,
    "liquidationType": "",
    "slTriggerPrice": "",
    "slTriggerBy": "",
    "tpTriggerPrice": "",
    "tpTriggerBy": ""
  }
]

Query Futures Positions

GET /api/v2/futures/positions

Weight: 1

Request Parameters

Response Content

[
  {
    "symbol": "BTCUSD-PERPETUAL",
    "baseAsset": "BTC",
    "quoteAsset": "USD",
    "avgPrice": "91453",
    "leverage": "5",
    "lastPrice": "89897.2",
    "baseQty": "0.195",
    "quoteQty": "17532.0795",
    "markPrice": "89908.1",
    "liquidationPrice": "0",
    "margin": "3506.4163",
    "marginRate": "",
    "profitRate": "-0.0844",
    "unrealizedPnL": "-301.2707",
    "realizedPnL": "-236.7527",
    "marginType": "CROSS",
    "positionMode": "net",
    "positionSide": "LONG"
  }
]

Set Futures Trading Stop

POST /api/v2/futures/position/trading-stop

Weight: 3

Request Parameters

Response Content

{
  "symbolId": "BTCUSD-PERPETUAL",
  "positionSide": "LONG",
  "stopProfitPrice": "95000",
  "stopProfitTriggerConditionType": "MARK_PRICE",
  "stopLossPrice": "85000",
  "stopLossTriggerConditionType": "MARK_PRICE"
}

Query Futures Risk Limit

GET /api/v2/futures/riskLimit

Weight: 1

Request Parameters

Response Content

[
  {
    "riskLimitValue": "125000.00",
    "quoteAsset": "USD",
    "maintainMargin": "0.025",
    "initialMargin": "0.05",
    "quickDeduction": "0.00",
    "positionSide": "BUY"
  },
  {
    "riskLimitValue": "125000.00",
    "quoteAsset": "USD",
    "maintainMargin": "0.025",
    "initialMargin": "0.05",
    "quickDeduction": "0.00",
    "positionSide": "SELL"
  }
]

Query Futures Leverage

GET /api/v2/futures/leverage

Weight: 1

Request Parameters

Response Content

[
  {
    "symbolId": "BTCUSD-PERPETUAL",
    "leverage": "5",
    "marginType": "CROSS"
  }
]

Change Futures Leverage

POST /api/v2/futures/leverage

Weight: 1

Request Parameters

Response Content

{
  "code": "0000",
  "symbolId": "BTCUSD-PERPETUAL",
  "leverage": "5"
}

Query Futures Account Balance

GET /api/v2/futures/balance

Weight: 1

Request Parameters

Response Content

[
  {
    "asset": "USD",
    "balance": "4999769.17379751",
    "availableBalance": "4995106.80365251"
  }
]

Query Futures Funding Rate

GET /api/v2/futures/fundingRate

Weight: 1