接單方 (Taker) API 接口
接口介紹
接單方 API 接口面向認證的券商或股票託管機構提供，支持鎖定訂單、成交訂單、查詢成交記錄等功能，通過 API Key 認證接入平台完成鏈下股票訂單交易。
快速開始
基礎信息
- 測試環境:
https://api-qa.proto.stove.finance - 生產環境:
https://proto.stove.finance - Content-Type:
application/json - 數據格式: JSON (snake_case 命名風格)
- 鑑權方式: API Key
說明：接口示例中顯示相對路徑（如 /api/v1/orders），實際請求時請在路徑前添加環境地址。
統一響應格式
所有接口都遵循統一的響應結構：
| 字段 | 類型 | 說明 |
|---|---|---|
| code | int | 結果碼，0 表示成功，非 0 表示錯誤 |
| message | string | 錯誤消息（僅在出錯時返回） |
| details | string | 額外錯誤信息（僅在出錯時返回） |
| data | object | 業務數據（僅在成功時返回） |
接口概覽
賬戶接口
- 賬戶連接 - 進行錢包連接，獲取 JWT 令牌
訂單接口
- 驗證訂單 - 驗證訂單的有效性（不創建訂單）
- 鎖定訂單 - 鎖定訂單以進行填充
- 解鎖訂單 - 解鎖已鎖定的訂單
- 成交訂單 - 執行訂單成交（部分或全部）
- 拒單 - 拒絕訂單
- 查詢訂單 - 查詢 taker 鎖定或填充的訂單列表
- 成交記錄 - 查詢訂單成交記錄
WebSocket
- 實時推送 - 訂閱訂單狀態變更和取消請求的實時通知
請點擊左側導航欄查看各個接口的詳細文檔。
枚舉類型說明
OrderStatus - 訂單狀態
| 枚舉項 | 說明 | 是否終態 | 描述 |
|---|---|---|---|
| pending | 待處理 | 否 | 訂單已創建，等待 Taker 鎖定。例如等待美股開市時也會處於此狀態 |
| locked | 已鎖定 | 否 | 訂單被 Taker 鎖定，可能正在交易中 |
| partially_filled | 部分成交 | 是 | 訂單部分成交，剩餘部分已退還。通常是用戶在成交過程中發起撤單請求，最終有部分成交 |
| filled | 完全成交 | 是 | 訂單完全成交 |
| cancelled | 已取消 | 是 | 訂單被 Maker 取消 |
| expired | 已過期 | 是 | 訂單超過有效期 |
| rejected | 已拒絕 | 是 | 訂單驗證失敗或被 Taker 拒絕，一般會提供拒絕原因 |
| suspended | 已暫停 | 否 | 訂單被掛起，需人工介入處理 |
終態說明：標記為終態（是）的狀態無法再轉換到其他狀態。
Exchange - 交易所代碼
| 下標 | 說明 |
|---|---|
| 0 | 納斯達克（美股交易所） |
Market - 市場代碼
| 枚舉項 | 說明 |
|---|---|
| usex | 美股市場 |
注意事項
- 數據格式: 所有接口使用 snake_case 命名風格
- 金額精度: 金額字段使用字符串類型，避免精度損失
- 地址格式: 以太坊地址必須包含
0x前綴 - 時間格式: 默認使用
ISO 8601 標準格式，如2025-11-17T03:00:24Z