持倉

此端點用於查詢用戶在所有市場及證券類型下的當前持倉。提供總持有數量、可交易數量、凍結數量及平均成本、前收價等財務指標。常用於投資組合檢視、交易 UI 及合規報告。

---

📨 HTTP 請求

GET /account/v1/positions

---

📥 查詢參數

參數	類型	必填	說明	合法值
market	enum	否	依市場類型篩選	hkex, usex，詳見 market 枚舉
security_type	enum	否	依證券類型篩選	stock，詳見 security_type 枚舉
page	int	否	當前頁碼	預設 1
page_size	int	否	每頁筆數	預設 20
portfolio_id	string	否	投資組合 ID（用戶自訂外部 ID）以區分不同組合持倉	最長 50 字元，如：d59c4577-d450-2cbb-43c9-ef06e40f1fde

---

✅ 成功回應

回應欄位

欄位	類型	說明
market	decimal	市場類型（見 market 枚舉）
product_code	string	產品唯一標識
product_name	string	產品名稱
qty	decimal	持有總數量
os_sell_qty	decimal	已凍結待賣出數量
avail_qty	decimal	可買入數量（T+1 市場）
avail_sell_qty	decimal	可賣出數量
uncleared_qty	decimal	已持有但不可交易數量
base_currency	string	幣種代碼
avg_cost	decimal	平均成本（含手續費）
avg_price	decimal	平均價格（不含手續費）
prev_price	decimal	前一日收盤價
prev_market_value	decimal	以前一日收盤價計算的市值
pending_deposit_qty	decimal	待入庫數量
pending_withdrawal_qty	decimal	待出庫數量
approved_deposit_qty	decimal	審批中入庫數量
approved_withdrawal_qty	decimal	審批中出庫數量
security_type	enum	證券類型（見 security_type 枚舉）
contract_time	string	合約到期日（如為衍生品適用）
portfolio_id	string	投資組合 ID（用戶自訂外部 ID）

❌ 錯誤回應

錯誤欄位

欄位	類型	說明
code	int	錯誤代碼
message	string	錯誤訊息（人類可讀）
details	string	其他錯誤資訊

---

💡 cURL 範例

curl -X GET "https://{{base_url}}/account/v1/positions?market=usex&security_type=stock&portfolio_id=d59c4577-d450-2cbb-43c9-ef06e40f1fde" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Timestamp: 1746777861334" \
  -H "X-API-Signature: YOUR_GENERATED_SIGNATURE" \
  -H "Content-Type: application/json"

---

✅ 成功回應範例

{
  "code": 0,
  "data": {
    "total_records": 1,
    "page": 1,
    "page_size": 20,
    "positions": [
      {
        "market": "usex",
        "product_code": "AAPL",
        "product_name": "Apple Inc.",
        "qty": 100,
        "os_sell_qty": 10,
        "avail_qty": 90,
        "avail_sell_qty": 85,
        "uncleared_qty": 5,
        "base_currency": "USD",
        "avg_cost": 140.5,
        "avg_price": 139.0,
        "prev_price": 142.3,
        "prev_market_value": 14230,
        "pending_deposit_qty": 0,
        "pending_withdrawal_qty": 0,
        "approved_deposit_qty": 0,
        "approved_withdrawal_qty": 0,
        "security_type": "stock",
        "contract_time": 174677525,
        "portfolio_id": "d59c4577-d450-2cbb-43c9-ef06e40f1fde"
      }
    ]
  }
}

---

❌ 錯誤回應範例

{
  "code": 12010012,
  "message": "Internal server error"
}