Pricing and Market Data

/**
 * Get current prices for Account
 * @param accountID - Account identifier
 * @param queryParams - Query parameters object
 *   - instruments: string (comma-separated list of instruments, required)
 *   - since: string (datetime to get prices since, optional)
 *   - includeUnitsAvailable: boolean (include units available, optional, default true)
 *   - includeHomeConversions: boolean (include home currency conversions, optional, default false)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { prices: ClientPrice[], homeConversions: HomeConversions[], time: string }
 */
ctx.pricing.get(accountID, queryParams, responseHandler);

// Get current prices for multiple instruments
ctx.pricing.get('001-001-1234567-001', {
  instruments: 'EUR_USD,GBP_USD,USD_JPY'
}, response => {
  if (response.isSuccess()) {
    response.body.prices.forEach(price => {
      console.log(`${price.instrument}:`);
      console.log(`  Tradeable: ${price.tradeable}`);
      console.log(`  Bid: ${price.closeoutBid}`);
      console.log(`  Ask: ${price.closeoutAsk}`);
      console.log(`  Spread: ${parseFloat(price.closeoutAsk) - parseFloat(price.closeoutBid)}`);

      if (price.unitsAvailable) {
        console.log(`  Units Available (Long): ${price.unitsAvailable.default.long}`);
        console.log(`  Units Available (Short): ${price.unitsAvailable.default.short}`);
      }
    });
  }
});

/**
 * Stream prices
 * @param accountID - Account identifier
 * @param queryParams - Query parameters object
 *   - instruments: string (comma-separated list of instruments, required)
 *   - snapshot: boolean (send initial snapshot, optional, default true)
 * @param streamChunkHandler - Callback for each streamed chunk (ClientPrice or PricingHeartbeat)
 * @param responseHandler - Callback receiving Response object when stream ends
 */
ctx.pricing.stream(accountID, queryParams, streamChunkHandler, responseHandler);

// Stream live prices
ctx.pricing.stream('001-001-1234567-001',
  { instruments: 'EUR_USD,GBP_USD' },
  chunk => {
    try {
      const data = JSON.parse(chunk);

      if (data.type === 'HEARTBEAT') {
        console.log('Heartbeat:', data.time);
      } else if (data.type === 'PRICE') {
        console.log(`${data.instrument}: Bid ${data.closeoutBid} / Ask ${data.closeoutAsk}`);
        console.log(`  Time: ${data.time}`);
        console.log(`  Tradeable: ${data.tradeable}`);
      }
    } catch (e) {
      console.error('Parse error:', e);
    }
  },
  response => {
    console.log('Price stream ended');
  }
);

/**
 * Get base prices
 * @param queryParams - Query parameters object
 *   - time: string (datetime for historical prices, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { prices: Price[], time: string }
 */
ctx.pricing.basePrices(queryParams, responseHandler);

/**
 * Get price range
 * @param instrument - Instrument name
 * @param queryParams - Query parameters object
 *   - from: string (start datetime RFC3339, required)
 *   - to: string (end datetime RFC3339, required)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { prices: Price[] }
 */
ctx.pricing.getPriceRange(instrument, queryParams, responseHandler);

/**
 * Get candlestick data for instrument
 * @param instrument - Instrument name
 * @param queryParams - Query parameters object
 *   - price: string (price component: M=mid, B=bid, A=ask, BA=bid+ask, MBA=mid+bid+ask, optional, default M)
 *   - granularity: string (candlestick granularity: S5,S10,S15,S30,M1,M2,M4,M5,M10,M15,M30,H1,H2,H3,H4,H6,H8,H12,D,W,M, optional, default S5)
 *   - count: number (number of candles to return, max 5000, optional, default 500)
 *   - from: string (start datetime RFC3339, optional)
 *   - to: string (end datetime RFC3339, optional)
 *   - smooth: boolean (smooth prices, optional, default false)
 *   - includeFirst: boolean (include first candle before from time, optional)
 *   - dailyAlignment: number (hour of day for daily candle alignment 0-23, optional, default 17)
 *   - alignmentTimezone: string (timezone for alignment, optional, default America/New_York)
 *   - weeklyAlignment: string (day of week for weekly alignment: Monday-Sunday, optional, default Friday)
 *   - units: string (number of units to calculate financing for, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { instrument: string, granularity: string, candles: Candlestick[] }
 */
ctx.pricing.candles(instrument, queryParams, responseHandler);

// Also available via ctx.instrument:
ctx.instrument.candles(instrument, queryParams, responseHandler);

// Get last 100 daily candles for EUR_USD
ctx.pricing.candles('EUR_USD', {
  granularity: 'D',
  count: 100,
  price: 'MBA'  // Mid, bid, and ask
}, response => {
  if (response.isSuccess()) {
    console.log(`${response.body.candles.length} candles retrieved`);

    response.body.candles.forEach(candle => {
      if (candle.complete) {
        console.log(`${candle.time}:`);
        console.log(`  Mid: O=${candle.mid.o} H=${candle.mid.h} L=${candle.mid.l} C=${candle.mid.c}`);
        console.log(`  Volume: ${candle.volume}`);
      }
    });
  }
});

// Get hourly candles for a date range
ctx.pricing.candles('GBP_USD', {
  granularity: 'H1',
  from: '2023-01-01T00:00:00Z',
  to: '2023-01-31T23:59:59Z',
  price: 'M'
}, response => {
  if (response.isSuccess()) {
    console.log('Hourly candles:', response.body.candles.length);
  }
});

/**
 * Get current price for instrument
 * @param instrument - Instrument name
 * @param queryParams - Query parameters object
 *   - time: string (datetime for historical price, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { price: Price, time: string }
 */
ctx.instrument.price(instrument, queryParams, responseHandler);

/**
 * Get prices for multiple instruments
 * @param instruments - Comma-separated list of instruments or single instrument
 * @param queryParams - Query parameters object
 *   - instruments: string (comma-separated list, optional if provided as first param)
 *   - time: string (datetime for historical prices, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { prices: Price[], time: string }
 */
ctx.instrument.prices(instruments, queryParams, responseHandler);

/**
 * Get order book for instrument
 * @param instrument - Instrument name
 * @param queryParams - Query parameters object
 *   - time: string (datetime for historical order book, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { orderBook: OrderBook }
 */
ctx.instrument.orderBook(instrument, queryParams, responseHandler);

ctx.instrument.orderBook('EUR_USD', {}, response => {
  if (response.isSuccess()) {
    const book = response.body.orderBook;
    console.log(`Order Book for ${book.instrument}:`);
    console.log(`  Time: ${book.time}`);
    console.log(`  Current Price: ${book.price}`);
    console.log(`  Bucket Width: ${book.bucketWidth}`);

    book.buckets.forEach(bucket => {
      console.log(`  Price ${bucket.price}: Long ${bucket.longCountPercent}% / Short ${bucket.shortCountPercent}%`);
    });
  }
});

/**
 * Get position book for instrument
 * @param instrument - Instrument name
 * @param queryParams - Query parameters object
 *   - time: string (datetime for historical position book, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { positionBook: PositionBook }
 */
ctx.instrument.positionBook(instrument, queryParams, responseHandler);

ctx.instrument.positionBook('EUR_USD', {}, response => {
  if (response.isSuccess()) {
    const book = response.body.positionBook;
    console.log(`Position Book for ${book.instrument}:`);
    console.log(`  Time: ${book.time}`);
    console.log(`  Current Price: ${book.price}`);

    book.buckets.forEach(bucket => {
      console.log(`  Price ${bucket.price}: Long ${bucket.longCountPercent}% / Short ${bucket.shortCountPercent}%`);
    });
  }
});

interface ClientPrice {
  type: 'PRICE';
  instrument: string;
  time: string;
  status: string;  // tradeable, non-tradeable, invalid
  tradeable: boolean;

  // Price levels with liquidity
  bids: PriceBucket[];
  asks: PriceBucket[];

  // Closeout prices
  closeoutBid: string;
  closeoutAsk: string;

  // Conversion factors
  quoteHomeConversionFactors?: QuoteHomeConversionFactors;

  // Units available for trading
  unitsAvailable?: UnitsAvailable;
}

interface Price {
  instrument: string;
  time: string;
  tradeable: boolean;

  // Base prices
  baseBid: string;
  baseAsk: string;

  // Price levels with liquidity
  bids: PriceBucket[];
  asks: PriceBucket[];

  // Closeout prices
  closeoutBid: string;
  closeoutAsk: string;
}

interface PriceBucket {
  price: string;
  liquidity: number;
}

interface Candlestick {
  time: string;
  bid?: CandlestickData;  // Bid OHLC (if requested)
  ask?: CandlestickData;  // Ask OHLC (if requested)
  mid?: CandlestickData;  // Mid OHLC (if requested)
  volume: number;
  complete: boolean;  // True if candlestick period is complete
}

interface CandlestickData {
  o: string;  // Open
  h: string;  // High
  l: string;  // Low
  c: string;  // Close
}

interface OrderBook {
  instrument: string;
  time: string;
  price: string;  // Current market price
  bucketWidth: string;  // Price width of each bucket
  buckets: OrderBookBucket[];
}

interface OrderBookBucket {
  price: string;
  longCountPercent: string;  // Percentage of long orders
  shortCountPercent: string;  // Percentage of short orders
}

interface PositionBook {
  instrument: string;
  time: string;
  price: string;  // Current market price
  bucketWidth: string;  // Price width of each bucket
  buckets: PositionBookBucket[];
}

interface PositionBookBucket {
  price: string;
  longCountPercent: string;  // Percentage of long positions
  shortCountPercent: string;  // Percentage of short positions
}

interface QuoteHomeConversionFactors {
  positiveUnits: string;  // Conversion factor for positive amounts
  negativeUnits: string;  // Conversion factor for negative amounts
}

interface HomeConversions {
  currency: string;
  accountGain: string;  // Conversion factor for gains
  accountLoss: string;  // Conversion factor for losses
  positionValue: string;  // Conversion factor for position value
}

interface PricingHeartbeat {
  type: 'HEARTBEAT';
  time: string;
}