포지션

포지션 API는 Xmarket 플랫폼의 모든 마켓에서 활성 거래 포지션에 대한 접근을 제공합니다.

포지션 목록 가져오기

필터 및 검색 옵션으로 페이지네이션된 포지션 목록을 가져옵니다.

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
}

포지션 상태

포지션은 다음과 같은 상태를 가질 수 있습니다:

상태	설명
열려	미실현 손익이 있는 활성 포지션
마감됨	포지션이 마감되어 이익이 실현됨
정산됨	마켓이 결과 처리되어 포지션이 자동으로 정산됨

포지션 이해하기

포지션은 특정 마켓 결과에 대한 보유를 나타냅니다. 주요 속성은 다음과 같습니다:

• 결과 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}`);

일반적인 사용 사례

포트폴리오 대시보드

모든 오픈 포지션을 가져와 현재 보유, 가치 및 미실현 손익을 대시보드에 표시합니다.

포지션 모니터링

포지션 엔드포인트를 정기적으로 폴링하여 미실현 손익 임계값 기반 알림을 설정합니다.

성과 분석

종료된 포지션을 분석하여 과거 성과 지표 및 승률을 계산합니다.

마켓 노출

포지션 가치를 집계하여 다양한 마켓 카테고리별 노출을 계산합니다.

관련 문서

• 주문 API - 포지션을 구축하기 위해 주문 생성 및 관리

• 마켓 API - 포지션에 대한 마켓 정보 가져오기

• 오더북 API - 포지션 가치 평가를 위한 현재 가격 확인

• 빠른 시작 - API로 시작하기