持仓
获取持仓列表
检索您的持仓的分页列表，支持筛选和搜索选项。
端点： 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(`Market: ${position.market.name}`);
console.log(`Outcome: ${position.outcome.name}`);
console.log(`Quantity: ${position.quantity}`);
console.log(`Unrealized P&L: ${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(`Active Positions: ${summary.positionCount}`);
console.log(`Total Value: $${summary.totalValue.toFixed(2)}`);
console.log(`Total Unrealized P&L: $${summary.totalUnrealizedPnL.toFixed(2)}`);
console.log(`Markets: ${summary.markets}`);
常见用例
投资组合仪表板
获取所有开放持仓以在仪表板中显示当前持有、价值和未实现盈亏。
持仓监控
通过定期轮询持仓端点，根据未实现盈亏阈值设置提醒。
业绩分析
分析已关闭持仓以计算历史业绩指标和胜率。
市场敞口
通过聚合持仓价值计算不同市场类别的敞口。