持倉
獲取持倉列表
獲取帶有篩選同搜索選項嘅分頁持倉列表。
端點： GET /api/v1/positions
查詢參數：
| 參數 | 類型 | 描述 |
|---|---|---|
| status | string | 按持倉狀態篩選（open、closed、settled） |
| page | number | 分頁頁碼 |
| pageSize | number | 每頁結果數量 |
持倉狀態
持倉可以有以下狀態：
| 狀態 | 描述 |
|---|---|
| open | 持倉活躍中，有未實現盈虧 |
| closed | 持倉已關閉，利潤已實現 |
| settled | 市場已結算，持倉自動結算 |
理解持倉
持倉代表你喺特定市場結果中嘅持有量。關鍵屬性包括：
- 結果 ID：你正在交易嘅特定結果
- 數量：持有嘅股份數量
- 平均價格：你嘅平均入場價格
- 當前價格：最新市場價格
- 未實現盈虧：當前利潤/虧損（未平倉持倉）
- 已實現盈虧：實際利潤/虧損（已平倉持倉）
代碼範例
獲取所有未平倉持倉
const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://engine.xmarket.app/api/v1';
async function getOpenPositions() {
const response = await fetch(
`${BASE_URL}/positions?status=open&pageSize=50`,
{
headers: {
'x-api-key': API_KEY,
'Content-Type': 'application/json'
}
}
);
const data = await response.json();
return data.items;
}
// 使用範例
const positions = await getOpenPositions();
positions.forEach(position => {
console.log(`市場: ${position.market.name}`);
console.log(`結果: ${position.outcome.name}`);
console.log(`數量: ${position.quantity}`);
console.log(`未實現盈虧: ${position.unrealizedPnL}`);
console.log('---');
});
計算總投資組合價值
async function getPortfolioSummary() {
const response = await fetch(
`${BASE_URL}/positions?status=open&pageSize=1000`,
{
headers: {
'x-api-key': API_KEY,
'Content-Type': 'application/json'
}
}
);
const data = await response.json();
const positions = data.items;
const totalValue = positions.reduce((sum, pos) => {
return sum + (pos.quantity * pos.currentPrice);
}, 0);
const totalUnrealizedPnL = positions.reduce((sum, pos) => {
return sum + pos.unrealizedPnL;
}, 0);
return {
positionCount: positions.length,
totalValue,
totalUnrealizedPnL,
markets: [...new Set(positions.map(p => p.market.id))].length
};
}
// 使用範例
const summary = await getPortfolioSummary();
console.log(`活躍持倉: ${summary.positionCount}`);
console.log(`總價值: $${summary.totalValue.toFixed(2)}`);
console.log(`總未實現盈虧: $${summary.totalUnrealizedPnL.toFixed(2)}`);
console.log(`市場數量: ${summary.markets}`);
常見用例
投資組合儀表板
獲取所有未平倉持倉嚟喺儀表板中顯示當前持有量、價值同未實現盈虧。
持倉監控
通過定期輪詢持倉端點，根據未實現盈虧閾值設置提醒。
績效分析
分析已平倉持倉嚟計算歷史績效指標同勝率。
市場敞口
通過聚合持倉價值計算喺唔同市場類別嘅敞口。