Position Management

/**
 * Get list of all Positions for Account
 * @param accountID - Account identifier
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { positions: Position[], lastTransactionID: string }
 */
list(accountID, responseHandler);

ctx.position.list('001-001-1234567-001', response => {
  if (response.isSuccess()) {
    response.body.positions.forEach(position => {
      console.log(`${position.instrument}:`);
      console.log(`  Long: ${position.long.units} units, P/L: ${position.long.pl}`);
      console.log(`  Short: ${position.short.units} units, P/L: ${position.short.pl}`);
      console.log(`  Total Unrealized P/L: ${position.unrealizedPL}`);
    });
  }
});

/**
 * Get list of open Positions
 * @param accountID - Account identifier
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { positions: Position[], lastTransactionID: string }
 */
listOpen(accountID, responseHandler);

ctx.position.listOpen('001-001-1234567-001', response => {
  if (response.isSuccess()) {
    const positions = response.body.positions;
    console.log(`${positions.length} open positions`);
    positions.forEach(position => {
      const longUnits = parseFloat(position.long.units);
      const shortUnits = parseFloat(position.short.units);
      const netUnits = longUnits + shortUnits;

      console.log(`${position.instrument}: ${netUnits} units (${netUnits > 0 ? 'LONG' : 'SHORT'})`);
      console.log(`  Unrealized P/L: ${position.unrealizedPL}`);
      console.log(`  Margin Used: ${position.marginUsed}`);
    });
  }
});

/**
 * Get details of specific Position
 * @param accountID - Account identifier
 * @param instrument - Instrument name (e.g., "EUR_USD")
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { position: Position, lastTransactionID: string }
 */
get(accountID, instrument, responseHandler);

ctx.position.get('001-001-1234567-001', 'EUR_USD', response => {
  if (response.isSuccess()) {
    const position = response.body.position;

    console.log(`Position for ${position.instrument}:`);

    if (parseFloat(position.long.units) !== 0) {
      console.log('Long Side:');
      console.log(`  Units: ${position.long.units}`);
      console.log(`  Average Price: ${position.long.averagePrice}`);
      console.log(`  Unrealized P/L: ${position.long.unrealizedPL}`);
      console.log(`  Trade IDs: ${position.long.tradeIDs.join(', ')}`);
    }

    if (parseFloat(position.short.units) !== 0) {
      console.log('Short Side:');
      console.log(`  Units: ${position.short.units}`);
      console.log(`  Average Price: ${position.short.averagePrice}`);
      console.log(`  Unrealized P/L: ${position.short.unrealizedPL}`);
      console.log(`  Trade IDs: ${position.short.tradeIDs.join(', ')}`);
    }

    console.log(`Total Unrealized P/L: ${position.unrealizedPL}`);
    console.log(`Margin Used: ${position.marginUsed}`);
  }
});

/**
 * Close a Position
 * @param accountID - Account identifier
 * @param instrument - Instrument name (e.g., "EUR_USD")
 * @param bodyParams - Body parameters object
 *   - longUnits: string (units to close on long side, "ALL" or "NONE", optional)
 *   - longClientExtensions: ClientExtensions (optional)
 *   - shortUnits: string (units to close on short side, "ALL" or "NONE", optional)
 *   - shortClientExtensions: ClientExtensions (optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: {
 *   longOrderCreateTransaction?: MarketOrderTransaction,
 *   longOrderFillTransaction?: OrderFillTransaction,
 *   longOrderCancelTransaction?: OrderCancelTransaction,
 *   shortOrderCreateTransaction?: MarketOrderTransaction,
 *   shortOrderFillTransaction?: OrderFillTransaction,
 *   shortOrderCancelTransaction?: OrderCancelTransaction,
 *   relatedTransactionIDs: string[],
 *   lastTransactionID: string
 * }
 */
close(accountID, instrument, bodyParams, responseHandler);

// Close entire position (both long and short sides)
ctx.position.close('001-001-1234567-001', 'EUR_USD', {
  longUnits: 'ALL',
  shortUnits: 'ALL'
}, response => {
  if (response.isSuccess()) {
    console.log('Position closed');

    if (response.body.longOrderFillTransaction) {
      const longFill = response.body.longOrderFillTransaction;
      console.log(`Long side closed: ${longFill.units} units @ ${longFill.price}`);
      console.log(`  P/L: ${longFill.pl}`);
    }

    if (response.body.shortOrderFillTransaction) {
      const shortFill = response.body.shortOrderFillTransaction;
      console.log(`Short side closed: ${shortFill.units} units @ ${shortFill.price}`);
      console.log(`  P/L: ${shortFill.pl}`);
    }
  }
});

// Close only long side
ctx.position.close('001-001-1234567-001', 'EUR_USD', {
  longUnits: 'ALL',
  shortUnits: 'NONE'
}, response => {
  if (response.isSuccess()) {
    console.log('Long position closed');
  }
});

// Close only short side with client extensions
ctx.position.close('001-001-1234567-001', 'EUR_USD', {
  longUnits: 'NONE',
  shortUnits: 'ALL',
  shortClientExtensions: {
    comment: 'Closing short position'
  }
}, response => {
  if (response.isSuccess()) {
    console.log('Short position closed');
  }
});

interface Position {
  // Identification
  instrument: string;

  // Financial summary over account lifetime
  pl: string;  // Total realized P/L
  resettablePL: string;
  financing: string;
  commission: string;
  guaranteedExecutionFees: string;

  // Current state
  unrealizedPL: string;
  marginUsed: string;

  // Long and short sides
  long: PositionSide;
  short: PositionSide;
}

interface PositionSide {
  // Position details
  units: string;  // Number of units (0 if no position on this side)
  averagePrice?: string;  // Volume-weighted average price (if units != 0)

  // Trade references
  tradeIDs: string[];  // Trade IDs contributing to this position side

  // Financial summary
  pl: string;  // Total realized P/L for this side
  unrealizedPL: string;  // Current unrealized P/L
  resettablePL: string;
  financing: string;
  guaranteedExecutionFees: string;
}

interface CalculatedPositionState {
  instrument: string;
  netUnrealizedPL: string;
  longUnrealizedPL: string;
  shortUnrealizedPL: string;
  marginUsed: string;
}