下單

此端點允許客戶端向系統提交新交易訂單。支援下達加密貨幣訂單，回應會返回系統產生的訂單編號，所有訂單狀態更新（如成交、拒單）將通過 WebSocket 返回。提供兩種下單方式：

1. 單一加密貨幣下單：單一加密貨幣的下單
2. 批量加密貨幣下單：批量加密貨幣的下單（最多同時 5 筆加密貨幣訂單）

所有回應資料中的時間戳預設以 UTC 秒為單位表示。

---

單一加密貨幣下單

HTTP 請求

POST /trade/v1/orders

請求參數

參數名稱	類型	是否必填	說明
market	ENUM	是	市場代碼。詳見 market 列舉支援值。
order_type	ENUM	是	訂單型態。詳見 order_type 列舉支援值。
symbol	STRING	是	交易產品代碼。
order_side	ENUM	是	買賣方向（買/賣）。詳見 order_side 列舉支援值。
price	DECIMAL	條件必填	下單價格。 僅當 order_type 為下列其中一種時需傳入：limit_order、enhanced_limit_order、stop_limit_order。其餘類型可省略。
qty	DECIMAL	是	下單數量。
reference_id	STRING	否	客戶自訂追蹤訂單 ID。
portfolio_id	STRING	否	投資組合 ID（自訂外部用戶ID，可區分不同投資組合的訂單）。
trigger_price	DECIMAL	條件必填	觸發價格。僅當 order_type 為下列其中一種時需傳入：stop_limit_order、stop_market_order。其餘類型可省略。

⚠️ 重要提醒：reference_id（用於追蹤訂單）和 portfolio_id（用於追蹤用戶）都是用戶自訂的識別碼。用戶需自行確保其唯一性。如果使用重複值，用戶需自行承擔重複識別碼所可能產生的任何後果。

cURL 請求範例

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
}'

成功回應

欄位名稱	類型	說明
order_no	STRING	系統產生的訂單編號
qty	STRING	下單數量

範例

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

當下單數量含有零股時：

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

錯誤回應

欄位名稱	類型	說明
code	INT	錯誤代碼
message	STRING	錯誤訊息
details	STRING	補充說明

範例

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

---

批量加密貨幣下單

HTTP 請求

POST /trade/v1/orders/batch

請求參數

參數名稱	類型	是否必填	說明
market	ENUM	是	市場代碼。詳見 market 列舉支援值。
order_type	ENUM	是	訂單型態。詳見 order_type 列舉支援值。
symbol	STRING	是	交易產品代碼。
order_side	ENUM	是	買賣方向（買/賣）。詳見 order_side 列舉支援值。
price	DECIMAL	條件必填	下單價格。 僅當 order_type 為下列其中一種時需傳入：limit_order、enhanced_limit_order、stop_limit_order。其餘類型可省略。
qty	DECIMAL	是	下單數量。
reference_id	STRING	否	客戶自訂追蹤訂單 ID。
portfolio_id	STRING	否	投資組合 ID（自訂外部用戶ID，可區分不同投資組合的訂單）。
trigger_price	DECIMAL	條件必填	觸發價格。僅當 order_type 為下列其中一種時需傳入：stop_limit_order、stop_market_order。其餘類型可省略。

⚠️ 重要提醒：reference_id（用於追蹤訂單）和 portfolio_id（用於追蹤用戶）都是用戶自訂的識別碼。用戶需自行確保其唯一性。如果使用重複值，用戶需自行承擔重複識別碼所可能產生的任何後果。

cURL 請求範例

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
}]'

成功回應

欄位名稱	類型	說明
reference_id	STRING	客戶自訂追蹤訂單ID
round_lots	OBJECT	訂單結果
odd_lots	OBJECT	含碎股時的訂單結果
result	OBJECT	訂單投遞結果

OBJECT對象字段描述：

欄位名稱	類型	說明
order_no	STRING	系統產生的訂單編號
qty	STRING	下單數量
code	INT	錯誤代碼
message	STRING	錯誤訊息
details	STRING	補充說明

範例

{
    "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"
            }
        }
    ]
}

錯誤回應

欄位名稱	類型	說明
code	INT	錯誤代碼
message	STRING	錯誤訊息
details	STRING	補充說明

範例

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

---

下單後訂單狀態追蹤

下單成功後，使用者可即時追蹤訂單狀態更新。

如需接收訂單狀態通知，請使用WebSocket 連線。這可讓您的系統即時獲取訂單提交、部分成交、全部成交、撤單或拒單等狀態變化。

訂單狀態 WebSocket 端點

如需訂閱訂單狀態更新，請連接以下 WebSocket 端點：

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

連線並通過認證後，伺服器會即時推送您有效訂單的狀態更新。

WebSocket 訂單回調

當訂單狀態更新（如成交、拒單、部分成交）時，WebSocket 會推送以下欄位：

欄位名稱	類型	說明
market	ENUM	市場代碼
order_type	ENUM	訂單型態
symbol	STRING	股票代碼
name	STRING	股票名稱
order_side	ENUM	買或賣
account_code	STRING	交易帳戶代碼
order_no	STRING	系統訂單編號
order_status	ENUM	訂單狀態。詳見 order_status 列舉。
price	DECIMAL	下單價格
qty	DECIMAL	下單數量
outstand_qty	DECIMAL	剩餘未成交數量
execute_qty	DECIMAL	已成交數量
execute_price	DECIMAL	成交價格
execute_amount	DECIMAL	成交金額
charge	DECIMAL	交易手續費
charge_base_currency	STRING	手續費幣別
base_currency	STRING	結算幣別
reference_id	STRING	客戶自訂追蹤 ID
portfolio_id	STRING	投資組合 ID
reject_reason	STRING	拒單原因（如有）
update_time	LONG	最後更新時間戳
create_time	LONG	訂單建立時間戳

---

全部成交範例（WebSocket 回調）

{
	"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
	}
}