tessl/npm-oanda--v20

JavaScript bindings for OANDA's v20 REST API enabling programmatic forex and CFD trading operations.

Overview

Eval results

Files

Transaction History

Name: tessl/npm-oanda--v20
Author: tessl

Complete transaction history access with querying by date range or transaction ID, transaction detail retrieval, and transaction streaming for real-time updates on all account activity.

All transaction operations are accessed via ctx.transaction where ctx is a Context instance.

Capabilities

List Transactions

Get a list of Transactions for an Account with pagination.

/**
 * Get list of Transactions for Account
 * @param accountID - Account identifier
 * @param queryParams - Query parameters object
 *   - from: string (start datetime RFC3339 format, optional)
 *   - to: string (end datetime RFC3339 format, optional)
 *   - pageSize: number (transactions per page, max 1000, optional, default 100)
 *   - type: string (comma-separated list of transaction types to filter, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: {
 *   from: string,
 *   to: string,
 *   pageSize: number,
 *   type: string[],
 *   count: number,
 *   pages: string[],
 *   lastTransactionID: string
 * }
 */
list(accountID, queryParams, responseHandler);

Usage Example:

// List recent transactions
ctx.transaction.list('001-001-1234567-001', {
  pageSize: 50
}, response => {
  if (response.isSuccess()) {
    console.log(`Transaction count: ${response.body.count}`);
    console.log(`Pages available: ${response.body.pages.length}`);
    console.log('Fetch individual pages using URLs in pages array');
  }
});

// List transactions by date range
ctx.transaction.list('001-001-1234567-001', {
  from: '2023-01-01T00:00:00Z',
  to: '2023-01-31T23:59:59Z',
  pageSize: 100
}, response => {
  if (response.isSuccess()) {
    console.log(`Transactions in January: ${response.body.count}`);
  }
});

// Filter by transaction type
ctx.transaction.list('001-001-1234567-001', {
  type: 'ORDER_FILL,MARKET_ORDER',
  pageSize: 50
}, response => {
  if (response.isSuccess()) {
    console.log('Order fill transactions:', response.body);
  }
});

Get Transaction Details

Get the details of a single Transaction.

/**
 * Get details of specific Transaction
 * @param accountID - Account identifier
 * @param transactionID - Transaction identifier
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { transaction: Transaction, lastTransactionID: string }
 */
get(accountID, transactionID, responseHandler);

Usage Example:

ctx.transaction.get('001-001-1234567-001', '1234', response => {
  if (response.isSuccess()) {
    const txn = response.body.transaction;
    console.log(`Transaction ${txn.id}:`);
    console.log(`  Type: ${txn.type}`);
    console.log(`  Time: ${txn.time}`);
    console.log(`  Account ID: ${txn.accountID}`);

    // Type-specific properties
    if (txn.type === 'ORDER_FILL') {
      console.log(`  Instrument: ${txn.instrument}`);
      console.log(`  Units: ${txn.units}`);
      console.log(`  Price: ${txn.price}`);
      console.log(`  P/L: ${txn.pl}`);
    }
  }
});

Get Transaction Range

Get a range of Transactions by ID.

/**
 * Get range of Transactions
 * @param accountID - Account identifier
 * @param queryParams - Query parameters object
 *   - from: string (starting transaction ID, required)
 *   - to: string (ending transaction ID, required)
 *   - type: string (comma-separated list of transaction types to filter, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { transactions: Transaction[], lastTransactionID: string }
 */
range(accountID, queryParams, responseHandler);

Usage Example:

// Get transactions from ID 1000 to 1100
ctx.transaction.range('001-001-1234567-001', {
  from: '1000',
  to: '1100'
}, response => {
  if (response.isSuccess()) {
    console.log(`Retrieved ${response.body.transactions.length} transactions`);
    response.body.transactions.forEach(txn => {
      console.log(`${txn.id}: ${txn.type} at ${txn.time}`);
    });
  }
});

Get Transactions Since ID

Get all Transactions since a specific Transaction ID.

/**
 * Get Transactions since ID
 * @param accountID - Account identifier
 * @param queryParams - Query parameters object
 *   - id: string (transaction ID to query from, required)
 *   - type: string (comma-separated list of transaction types to filter, optional)
 * @param responseHandler - Callback receiving Response object
 * Response body contains: { transactions: Transaction[], lastTransactionID: string }
 */
since(accountID, queryParams, responseHandler);

Usage Example:

// Get all transactions since ID 1500
ctx.transaction.since('001-001-1234567-001', {
  id: '1500'
}, response => {
  if (response.isSuccess()) {
    console.log(`New transactions: ${response.body.transactions.length}`);
    response.body.transactions.forEach(txn => {
      console.log(`${txn.id}: ${txn.type}`);
    });
  }
});

Stream Transactions

Stream real-time Transactions for an Account.

/**
 * Stream Transactions
 * @param accountID - Account identifier
 * @param streamChunkHandler - Callback for each streamed chunk (Transaction or TransactionHeartbeat)
 * @param responseHandler - Callback receiving Response object when stream ends
 * Streamed objects are Transaction instances or TransactionHeartbeat instances
 */
stream(accountID, streamChunkHandler, responseHandler);

Usage Example:

ctx.transaction.stream('001-001-1234567-001',
  chunk => {
    // Handle each streamed chunk
    try {
      const data = JSON.parse(chunk);

      if (data.type === 'HEARTBEAT') {
        console.log('Heartbeat:', data.time);
      } else {
        // Transaction received
        console.log(`Transaction ${data.id}: ${data.type}`);

        if (data.type === 'ORDER_FILL') {
          console.log(`  ${data.instrument} ${data.units} @ ${data.price}`);
          console.log(`  P/L: ${data.pl}`);
        }
      }
    } catch (e) {
      console.error('Parse error:', e);
    }
  },
  response => {
    // Stream ended
    console.log('Transaction stream ended');
  }
);

Types

Transaction Base

All transactions share common base properties:

interface TransactionBase {
  id: string;
  time: string;  // RFC3339 timestamp
  userID: string;
  accountID: string;
  batchID?: string;
  requestID?: string;
  type: string;  // Transaction type (see Transaction Types below)
}

Transaction Types

The library includes 36 transaction types organized by category:

Account Lifecycle:

CREATE - CreateTransaction - Account creation
CLOSE - CloseTransaction - Account closure
REOPEN - ReopenTransaction - Account reopening

Configuration:

CLIENT_CONFIGURE - ClientConfigureTransaction - Account configuration change
CLIENT_CONFIGURE_REJECT - ClientConfigureRejectTransaction - Rejected configuration

Funding:

TRANSFER_FUNDS - TransferFundsTransaction - Fund transfer
TRANSFER_FUNDS_REJECT - TransferFundsRejectTransaction - Rejected transfer

Order Creation:

MARKET_ORDER - MarketOrderTransaction - Market order created
MARKET_ORDER_REJECT - MarketOrderRejectTransaction - Market order rejected
FIXED_PRICE_ORDER - FixedPriceOrderTransaction - Fixed price order
LIMIT_ORDER - LimitOrderTransaction - Limit order created
LIMIT_ORDER_REJECT - LimitOrderRejectTransaction - Limit order rejected
STOP_ORDER - StopOrderTransaction - Stop order created
STOP_ORDER_REJECT - StopOrderRejectTransaction - Stop order rejected
MARKET_IF_TOUCHED_ORDER - MarketIfTouchedOrderTransaction - MIT order created
MARKET_IF_TOUCHED_ORDER_REJECT - MarketIfTouchedOrderRejectTransaction - MIT order rejected
TAKE_PROFIT_ORDER - TakeProfitOrderTransaction - Take profit order created
TAKE_PROFIT_ORDER_REJECT - TakeProfitOrderRejectTransaction - Take profit rejected
STOP_LOSS_ORDER - StopLossOrderTransaction - Stop loss order created
STOP_LOSS_ORDER_REJECT - StopLossOrderRejectTransaction - Stop loss rejected
TRAILING_STOP_LOSS_ORDER - TrailingStopLossOrderTransaction - Trailing stop loss created
TRAILING_STOP_LOSS_ORDER_REJECT - TrailingStopLossOrderRejectTransaction - Trailing stop loss rejected

Order Execution:

ORDER_FILL - OrderFillTransaction - Order filled
ORDER_CANCEL - OrderCancelTransaction - Order cancelled
ORDER_CANCEL_REJECT - OrderCancelRejectTransaction - Order cancellation rejected

Modifications:

ORDER_CLIENT_EXTENSIONS_MODIFY - OrderClientExtensionsModifyTransaction - Order extensions modified
ORDER_CLIENT_EXTENSIONS_MODIFY_REJECT - OrderClientExtensionsModifyRejectTransaction - Modification rejected
TRADE_CLIENT_EXTENSIONS_MODIFY - TradeClientExtensionsModifyTransaction - Trade extensions modified
TRADE_CLIENT_EXTENSIONS_MODIFY_REJECT - TradeClientExtensionsModifyRejectTransaction - Modification rejected

Margin & Risk:

MARGIN_CALL_ENTER - MarginCallEnterTransaction - Margin call entered
MARGIN_CALL_EXTEND - MarginCallExtendTransaction - Margin call extended
MARGIN_CALL_EXIT - MarginCallExitTransaction - Margin call exited

Trade Management:

DELAYED_TRADE_CLOSURE - DelayedTradeClosureTransaction - Delayed trade closure
DAILY_FINANCING - DailyFinancingTransaction - Daily financing applied
RESET_RESETTABLE_PL - ResetResettablePLTransaction - Resettable P/L reset

Key Transaction Type Details

OrderFillTransaction

Most important transaction type for tracking trade execution:

interface OrderFillTransaction extends TransactionBase {
  type: 'ORDER_FILL';
  orderID: string;
  clientOrderID?: string;
  instrument: string;
  units: string;
  price: string;
  pl: string;  // Realized P/L
  financing: string;
  commission: string;
  accountBalance: string;
  gainQuoteHomeConversionFactor: string;
  lossQuoteHomeConversionFactor: string;
  halfSpreadCost: string;

  // Trade impact
  tradeOpened?: TradeOpen;
  tradesClosed?: TradeReduce[];
  tradeReduced?: TradeReduce;

  // Full trade state
  fullPrice?: FullPrice;
  reason?: string;
}

MarketOrderTransaction

Market order creation:

interface MarketOrderTransaction extends TransactionBase {
  type: 'MARKET_ORDER';
  instrument: string;
  units: string;
  timeInForce: string;
  priceBound?: string;
  positionFill: string;
  reason?: string;
  clientExtensions?: ClientExtensions;
  takeProfitOnFill?: TakeProfitDetails;
  stopLossOnFill?: StopLossDetails;
  trailingStopLossOnFill?: TrailingStopLossDetails;
  tradeClientExtensions?: ClientExtensions;
}

DailyFinancingTransaction

Daily rollover financing:

interface DailyFinancingTransaction extends TransactionBase {
  type: 'DAILY_FINANCING';
  financing: string;
  accountBalance: string;
  accountFinancingMode: string;
  positionFinancings: PositionFinancing[];
}

TransactionHeartbeat

Heartbeat for transaction streams:

interface TransactionHeartbeat {
  type: 'HEARTBEAT';
  time: string;  // RFC3339 timestamp
}

Supporting Types

interface TradeOpen {
  tradeID: string;
  units: string;
  price: string;
  guaranteedExecutionFee?: string;
  clientExtensions?: ClientExtensions;
  halfSpreadCost: string;
  initialMarginRequired: string;
}

interface TradeReduce {
  tradeID: string;
  units: string;
  price: string;
  realizedPL: string;
  financing: string;
  guaranteedExecutionFee?: string;
  halfSpreadCost: string;
}

interface PositionFinancing {
  instrument: string;
  financing: string;
  openTradeFinancings: OpenTradeFinancing[];
}

interface OpenTradeFinancing {
  tradeID: string;
  financing: string;
  openTradeFinancing: string;
  financingToDate: string;
}

Transaction Streaming Best Practices

When streaming transactions:

Handle Heartbeats: Check for type === 'HEARTBEAT' to distinguish from actual transactions
Parse Incrementally: Process each chunk as it arrives rather than buffering
Error Handling: Wrap JSON parsing in try-catch blocks
Reconnection Logic: Implement reconnection on stream disconnect
Use Since ID: When reconnecting, use the last transaction ID to catch up on missed transactions