Skip to main content

Positions

Get Positions List​

Retrieve a paginated list of your positions with filtering and search options.

Endpoint: GET /api/v1/positions

Query Parameters:

ParameterTypeDescription
statusstringFilter by position status (open, closed, settled)
pagenumberPage number for pagination
pageSizenumberNumber of results per page

Position Status​

Positions can have the following statuses:

StatusDescription
openPosition is active with unrealized gains/losses
closedPosition has been closed and profits realized
settledMarket resolved and position automatically settled

Understanding Positions​

A position represents your holdings in a specific market outcome. Key properties include:

  • Outcome ID: The specific outcome you're trading
  • Quantity: Number of shares held
  • Average Price: Your average entry price
  • Current Price: Latest market price
  • Unrealized P&L: Current profit/loss (open positions)
  • Realized P&L: Actual profit/loss (closed positions)

Code Examples​

Fetch All Open Positions​

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;
}

// Example usage
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('---');
});

Calculate Total Portfolio Value​

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
  };
}

// Example usage
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}`);

Common Use Cases​

Portfolio Dashboard​

Fetch all open positions to display current holdings, values, and unrealized P&L in a dashboard.

Position Monitoring​

Set up alerts based on unrealized P&L thresholds by regularly polling positions endpoint.

Performance Analytics​

Analyze closed positions to calculate historical performance metrics and win rates.

Market Exposure​

Calculate exposure across different market categories by aggregating position values.