Place Order

This endpoint allows clients to submit a new trade order to the system. It supports placing crypto orders across various markets. The response provides a system-generated order number, and all order updates (e.g., fills, rejection) will be returned via WebSocket. Two order place methods are available:

1. Single Crypto Place Order: Place order for a single crypto
2. Batch Crypto Place Order: Place order for multiple cryptos (up to 5 simultaneous cryptocurrency orders)

All timestamps returned in the response data are represented as UTC seconds by default.

---

Single Crypto Place Order

HTTP Request

POST /trade/v1/orders

Request Parameters

Name	Type	Required	Description
market	ENUM	Yes	Market code. See market enum for supported values.
order_type	ENUM	Yes	Type of order. See order_type enum for supported values.
symbol	STRING	Yes	Code of the product to be traded.
order_side	ENUM	Yes	Order side (buy/sell). See order_side enum for supported values.
price	DECIMAL	Conditionally required	Order price. Required only if order_type is one of: limit_order, enhanced_limit_order, or stop_limit_order. Optional for others.
qty	DECIMAL	Yes	Quantity of the order.
reference_id	STRING	No	Custom client-defined identifier for the order.
portfolio_id	STRING	No	Portfolio ID (which is a user-defined external id ) to distinguish between orders from different portfolios.
trigger_price	DECIMAL	Conditionally required	Trigger price. Required only if order_type is stop_limit_order or stop_market_order. Optional for other types.

⚠️ Important Notice: Both reference_id (for order tracking) and portfolio_id (for user tracking) are user-defined identifiers. Users are responsible for ensuring their uniqueness. If duplicate values are used, users bear full responsibility for any consequences that may arise from such duplicates.

Example cURL Request

curl --location --request POST '{$base_url}/trade/v1/orders' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Signature: YOUR_GENERATED_SIGNATURE' \
--header 'X-API-Timestamp: 1746774142' \
--header 'Content-Type: application/json' \
--data-raw '{
    "market": "hkex",
    "order_type": "enhanced_limit_order",
    "symbol": "00700",
    "order_side": "buy",
    "price": 423.83,
    "qty": 1000
}'

Successful Response

Field	Type	Description
order_no	STRING	System-generated order ID
qty	STRING	Quantity of the order

Example

{
    "code": 0,
    "data": {
        "round_lots": {
            "order_no": "25000000033",
            "qty": 1
        }
    }
}

When the order quantity contains odd lots:

{
    "code": 0,
    "data": {
        "round_lots": {
            "order_no": "25000000035",
            "qty": 1
        },
        "odd_lots": {
            "order_no": "25000000036",
            "qty": 0.2
        }
    }
}

Error Response

Field	Type	Description
code	INT	Error code
message	STRING	Error message
details	STRING	Additional information

Example

{
	"code": 030108,
	"message": "Insufficient available funds",
	"details": ""
}

---

Batch Crypto Place Order

HTTP Request

POST /trade/v1/orders/batch

Request Parameters

Name	Type	Required	Description
market	ENUM	Yes	Market code. See market enum for supported values.
order_type	ENUM	Yes	Type of order. See order_type enum for supported values.
symbol	STRING	Yes	Code of the product to be traded.
order_side	ENUM	Yes	Order side (buy/sell). See order_side enum for supported values.
price	DECIMAL	Conditionally required	Order price. Required only if order_type is one of: limit_order, enhanced_limit_order, or stop_limit_order. Optional for others.
qty	DECIMAL	Yes	Quantity of the order.
reference_id	STRING	No	Custom client-defined identifier for the order.
portfolio_id	STRING	No	Portfolio ID (which is a user-defined external id ) to distinguish between orders from different portfolios.
trigger_price	DECIMAL	Conditionally required	Trigger price. Required only if order_type is stop_limit_order or stop_market_order. Optional for other types.

⚠️ Important Notice: Both reference_id (for order tracking) and portfolio_id (for user tracking) are user-defined identifiers. Users are responsible for ensuring their uniqueness. If duplicate values are used, users bear full responsibility for any consequences that may arise from such duplicates.

Example cURL Request

curl --location --request POST '{$base_url}/trade/v1/orders/batch' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'X-API-Signature: YOUR_GENERATED_SIGNATURE' \
--header 'X-API-Timestamp: 1746774142' \
--header 'Content-Type: application/json' \
--data-raw '[{
    "market": "hkex",
    "order_type": "enhanced_limit_order",
    "symbol": "00700",
    "order_side": "buy",
    "price": 423.83,
    "qty": 1000
},{
    "market": "hkex",
    "order_type": "enhanced_limit_order",
    "symbol": "09988",
    "order_side": "buy",
    "price": 42.83,
    "qty": 200
},{
    "market": "hkex",
    "order_type": "enhanced_limit_order",
    "symbol": "01810",
    "order_side": "buy",
    "price": 23.83,
    "qty": 300
},{
    "market": "hkex",
    "order_type": "enhanced_limit_order",
    "symbol": "03388",
    "order_side": "sell",
    "price": 23.83,
    "qty": 600
}]'

Successful Response

Field	Type	Description
reference_id	STRING	Custom client-defined identifier for the order.
round_lots	OBJECT	Order results.
odd_lots	OBJECT	Order results when odd lots are included.
result	OBJECT	Order delivery results.

OBJECT field description:

Field	Type	Description
order_no	STRING	System-generated order ID
qty	STRING	Quantity of the order
code	INT	Error code
message	STRING	Error message
details	STRING	Additional information

Example

{
    "code": 0,
    "data": [
        {
            "reference_id": "S250905155348",
            "round_lots": {
                "order_no": "25000000131",
                "qty": 1
            },
            "odd_lots": {
                "order_no": "25000000132",
                "qty": 0.23
            },
            "result": {
                "code": 0
            }
        },
        {
            "reference_id": "S250905155349",
            "round_lots": {
                "order_no": "25000000134",
                "qty": 1
            },
            "result": {
                "code": 0
            }
        },
        {
            "reference_id": "S250905155350",
            "result": {
                "code": 11030112,
                "message": "Market Limit",
                "details": "Invalid Parameter Type"
            }
        }
    ]
}

Error Response

Field	Type	Description
code	INT	Error code
message	STRING	Error message
details	STRING	Additional information

Example

{
	"code": 030108,
	"message": "Insufficient available funds",
	"details": ""
}

---

Order Status Tracking After Placement

After successfully placing an order, users may want to track updates to the order's status in real time.

To receive order status notifications, you should use a WebSocket connection. This allows your system to stay updated on changes such as order submission, partial fills, full fills, cancellations, or rejections.

WebSocket Endpoint for Order Status

To subscribe to order status updates, connect to the following WebSocket endpoint:

Copy

wss://{{base_url}}/ws/trade/v1

Once connected and authenticated, the server will push real-time updates regarding your active orders directly through this WebSocket channel.

WebSocket Order Callback

The following fields will be sent via WebSocket when the order status is updated (e.g., filled, rejected, partially filled):

Field	Type	Description
market	ENUM	Market code
order_type	ENUM	Order type
symbol	STRING	Product code
name	STRING	Product name
order_side	ENUM	Buy or sell
account_code	STRING	Trading account code
order_no	STRING	System order ID
order_status	ENUM	Order status. See order_status enum.
price	DECIMAL	Order price
qty	DECIMAL	Order quantity
outstand_qty	DECIMAL	Remaining quantity
execute_qty	DECIMAL	Executed quantity
execute_price	DECIMAL	Execution price
execute_amount	DECIMAL	Execution amount
charge	DECIMAL	Commission fee
charge_base_currency	STRING	Currency of the fee
base_currency	STRING	Settlement currency
reference_id	STRING	Client reference ID for tracking the order.
portfolio_id	STRING	Portfolio ID to distinguish between orders from different portfolios.
reject_reason	STRING	Rejection reason, if any
update_time	LONG	Timestamp of last update
create_time	LONG	Order creation timestamp

---

Full Fill Example (WebSocket Callback)

{
	"type": "order",
	"data": {
		"market": "hkex",
		"order_type": "enhanced_limit_order",
		"symbol": "00700",
		"name": "TENCENT",
		"order_side": "buy",
		"account_code": "80114138",
		"order_no": "22000000021",
		"order_status": "fex",
		"price": 423.83,
		"qty": 1000,
		"outstand_qty": 0,
		"execute_qty": 1000,
		"execute_amount": 423.83,
		"charge": 20.03,
		"charge_base_currency": "HKD",
		"base_currency": "HKD",
		"reference_id": "",
		"portfolio_id": "",
		"reject_reason": "",
		"update_time": 1746775317,
		"create_time": 1746775257
	}
}