Position

This endpoint retrieves the user's current holdings across all markets and security types. It provides details such as total quantity held, quantities available for trading or frozen, and financial metrics like average cost and previous closing price. It is typically used in portfolio views, trading UIs, and compliance reporting.

---

📨 HTTP Request

GET /account/v1/positions

---

📥 Query Parameters

Parameter	Type	Required	Description	Valid Values
market	enum	No	Filter by market type	hkex, usex, See market enum for details
security_type	enum	No	Filter by security type	stock. See security_type enum for full list
page	int	No	current page index	1 as default
page_size	int	No	number of records of each page	20 as default
portfolio_id	string	No	Portfolio ID (which is a user-defined external id ) to distinguish between position from different portfolios.	Maximum length allowed: 50 characters. like : d59c4577-d450-2cbb-43c9-ef06e40f1fde

---

✅ Successful Response

Response Fields

Field	Type	Description
market	decimal	Market type (refer to market enum)
product_code	string	Unique product identifier
product_name	string	Product name
qty	decimal	Total holding quantity
os_sell_qty	decimal	Quantity frozen for pending sell orders
avail_qty	decimal	Quantity available for purchase (T+1 markets)
avail_sell_qty	decimal	Quantity available to sell
uncleared_qty	decimal	Quantity held but not tradable
base_currency	string	Currency code
avg_cost	decimal	Average cost (including fees)
avg_price	decimal	Average price (excluding fees)
prev_price	decimal	Previous day's closing price
prev_market_value	decimal	Market value calculated from previous close
pending_deposit_qty	decimal	Quantity pending deposit
pending_withdrawal_qty	decimal	Quantity pending withdrawal
approved_deposit_qty	decimal	Quantity under approval for deposit
approved_withdrawal_qty	decimal	Quantity under approval for withdrawal
security_type	enum	Security type (refer to security_type enum)
contract_time	string	Contract expiration date (for derivatives, if applicable)
portfolio_id	string	Portfolio ID (which is a user-defined external id )

❌ Error Response

Error Fields

Field	Type	Description
code	int	Error code
message	string	Human-readable error message
details	string	Additional error information

---

💡 cURL Example

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"

---

✅ Sample Success Response

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

---

❌ Sample Error Response

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