交易

委託生命週期

委託從您提交的那一刻起，直到成交、取消或過期，會經歷一組固定的狀態。每個狀態都可透過 API 觀測。

本章節的端點

四個端點涵蓋完整的委託生命週期。所有交易端點都需要驗證和適當的範圍。

動詞	路徑	用途
POST	/orders	提交新委託。
GET	/orders/:id	依 ID 讀取單筆委託。
GET	/orders	列出您的未成交及近期已完成委託。
POST	/orders/:id/cancel	取消未成交委託。

The full async flow from a POST /orders call to a trade event delivered over WebSocket. The 202 Accepted (step 2, dashed) lands BEFORE matching runs — your client must await the trade event on /ws to learn the fill outcome.

委託狀態

每筆委託都帶有以下其中一種狀態值。除部分成交後取消外，狀態轉換為單向。

Transitions are one-way except for the cancel branches: pending, open, and partial can all transition to cancelled by user or admin action. A circuit-breaker halt pauses the market but leaves resting orders intact — cancellation is still your decision. Cancelling a partial order removes only the unfilled remainder.

狀態	含義
pending	在委託簿中靜止等待反向委託。
open	掛單在委託簿中等待反向委託成交。
partial	部分成交；剩餘部分仍在靜止。
filled	完全撮合。份額已進入您的持倉。
cancelled	Cancelled by the user or by an admin action. The circuit breaker halts the market on a 30%+ price move but does not automatically cancel resting orders — they are paused until trading resumes (or you cancel them yourself).

常見拒絕原因

當委託被拒絕時，回應帶有穩定的錯誤代碼，以便您的客戶端可以依此分支。

代碼	符號	含義
3001	ErrInsufficientBalance	您的 USDC 餘額不足以按提案價格下此委託。
5002	ErrInvalidPrice	價格超出市場接受的最小跳動範圍或低於 0 / 高於 1。
5004	ErrInvalidSide	side must be 1 (buy) or 2 (sell) — any other value is rejected.
5007	ErrMarketNotTrading	市場已暫停（熔斷機制、裁決或維護）。
5008	ErrInsufficientPosition	you do not hold enough shares of this outcome to place this sell order.
2025	ErrTwoFactorRequired	2FA is required for trading — enable it in Security settings before placing orders.

請根據數字 `code` 欄位進行分支，而非 message——message 是面向使用者的，會隨語言設定和平台文案變化。

訂閱委託事件而非輪詢

WebSocket 委託頻道即時推送狀態轉換。在任何需要對成交作出反應的機器人中使用它——輪詢對儀表板可接受，但對交易迴圈而言是浪費。