Positions

The Positions API provides access to your active trading positions across all markets on the Xmarket platform.

Get Positions List

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

Get list of positions (paginated, status=all, sorted by createdAt, supports partial name search via ?search=)

get

Authorizations

x-api-key

x-api-keystringRequired

Query parameters

marketIdstringOptional

pagestringOptional

Page number

Default: 1Example: 1Pattern: ^\d+$

pageSizestringOptional

Page size

Default: 20Example: 20Pattern: ^\d+$

searchstringOptional

orderBystring · enumOptional

Sort by createdAt

Default: latestTradeExample: latestTradePossible values:

statusstring · enumOptional

Filter by status

Default: allExample: allPossible values:

cachedContractAddressesKeystringOptional

Cached contract addresses key

Example: cached-contract-addresses-key

Header parameters

x-api-keystringRequired

Responses

200

List of positions

application/json

Paginated list of positions

totalnumberRequiredExample: 100

pagenumberRequiredExample: 1

pageSizenumberRequiredExample: 20

400

Bad request

application/json

500

Internal server error

application/json

get

/api/v1/positions

HTTPcURLJavaScriptPython

GET /api/v1/positions HTTP/1.1
x-api-key: text
Accept: */*

{
  "items": [
    {
      "id": "position-uuid",
      "marketId": "market-uuid",
      "marketName": "text",
      "marketSlug": "text",
      "marketStatus": "text",
      "conditionId": "text",
      "outcomeName": "text",
      "outcomeId": "text",
      "price": 1,
      "quantity": 1,
      "latestPrice": 1,
      "bet": 1,
      "current": 1,
      "pnl": 1,
      "toWin": 1,
      "positionId": "position-uuid",
      "userContractAddress": "0x1234567890123456789012345678901234567890",
      "userId": "user-uuid",
      "coverImageUrl": "text",
      "createdAt": "2024-08-05T12:00:00Z",
      "updatedAt": "2024-08-05T12:00:00Z",
      "finished": true,
      "expiresAt": "2024-08-05T12:00:00Z",
      "isMarketDeleted": true
    }
  ],
  "total": 100,
  "page": 1,
  "pageSize": 20
}

Position Status

Positions can have the following statuses:

Status	Description
open	Position is active with unrealized gains/losses
closed	Position has been closed and profits realized
settled	Market 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.

Related Documentation

• Orders API - Create and manage orders to build positions

• Markets API - Get market information for your positions

• Orderbook API - Check current prices for position valuation

• Quick Start - Get started with the API