@danielgroen/dxtrade-api 1.0.24 → 1.0.26

package/README.md

@@ -26,7 +26,7 @@ npm install dxtrade-api
 - [x] Position metrics (per-position P&L)
 - [x] Account metrics, trade journal & trade history
 - [x] Symbol search & instrument info
-- [x] OHLC / price bar data
+- [x] OHLC / price bar data (one-shot & streaming)
 - [x] PnL assessments
 - [x] Multi-broker support (FTMO, Eightcap, Lark Funding)
 - [x] Persistent WebSocket with `connect()`
@@ -34,7 +34,7 @@ npm install dxtrade-api
 - [x] Full TypeScript support
 - [ ] Batch orders
 - [ ] Modify existing orders
-- [ ] Real-time price streaming
+- [x] Real-time OHLC streaming
 
 ## Quick Start
 
@@ -48,8 +48,8 @@ const client = new DxtradeClient({
   accountId: "optional_account_id",
 });
 
-// connect() = auth + persistent WebSocket (recommended)
-await client.connect();
+// await client.auth(); // Auth only
+await client.connect(); // Auth + persistent WebSocket (recommended)
 
 const suggestions = await client.symbols.search("EURUSD");
 const symbol = suggestions[0];
@@ -63,17 +63,17 @@ const order = await client.orders.submit({
 });
 
 console.log(`Order ${order.orderId}: ${order.status}`);
-client.disconnect();
+client.disconnect(); // disconnect stream -- only needed if client.connect()
 ```
 
 ## Connection Modes
 
 ```ts
-// Persistent WebSocket (recommended) — reuses one WS for all data, enables streaming
+// 1. Persistent WebSocket (recommended) — reuses one WS for all data, enables streaming
 await client.connect();
 client.disconnect(); // when done
 
-// Lightweight — auth only, each data call opens a temporary WebSocket
+// 2. Lightweight — auth only, each data call opens a temporary WebSocket
 await client.auth();
 ```
 
@@ -113,11 +113,10 @@ BROKER.FTMO         // "https://dxtrade.ftmo.com"
 
 ### Positions
 
-- `client.positions.get()` — Get all open positions
-- `client.positions.close(params)` — Close a position (supports partial closes via the quantity field)
+- `client.positions.get()` — Get all open positions with P&L metrics merged (margin, plOpen, marketValue, etc.)
+- `client.positions.close(positionCode, options?)` — Close a position by its position code. Returns `Position.Full` with P&L metrics. Options: `waitForClose: "stream" | "poll"`, `timeout` (ms, default 30000), `pollInterval` (ms, default 1000)
 - `client.positions.closeAll()` — Close all open positions with market orders
-- `client.positions.metrics()` — Get position-level P&L metrics
-- `client.positions.stream(callback)` — Stream real-time position updates (requires `connect()`). Returns an unsubscribe function.
+- `client.positions.stream(callback)` — Stream real-time position updates with live P&L (requires `connect()`). Returns an unsubscribe function.
 
 ### Orders
 
@@ -145,6 +144,7 @@ BROKER.FTMO         // "https://dxtrade.ftmo.com"
 ### OHLC
 
 - `client.ohlc.get(params)` — Fetch OHLC price bars for a symbol (resolution, range, maxBars, priceField)
+- `client.ohlc.stream(params, callback)` — Stream real-time OHLC bar updates (requires `connect()`). Returns a promise that resolves with an unsubscribe function after the snapshot is received.
 
 ### Assessments
 
@@ -185,6 +185,7 @@ npm run example:debug
 npm run example:positions:get
 npm run example:positions:close
 npm run example:positions:close-all
+npm run example:positions:close-by-code
 npm run example:positions:metrics
 npm run example:positions:stream
 npm run example:orders:submit
@@ -196,6 +197,8 @@ npm run example:symbols:info:btc
 npm run example:instruments:get
 npm run example:instruments:get:forex
 npm run example:ohlc:get
+npm run example:ohlc:stream
+npm run example:ohlc:stream:btc
 npm run example:assessments:get
 npm run example:assessments:get:btc
 ```

package/dist/index.d.mts

@@ -67,7 +67,9 @@ declare enum ERROR {
     ORDERS_TIMEOUT = "ORDERS_TIMEOUT",
     ORDERS_ERROR = "ORDERS_ERROR",
     CANCEL_ORDER_ERROR = "CANCEL_ORDER_ERROR",
+    POSITION_NOT_FOUND = "POSITION_NOT_FOUND",
     POSITION_CLOSE_ERROR = "POSITION_CLOSE_ERROR",
+    POSITION_CLOSE_TIMEOUT = "POSITION_CLOSE_TIMEOUT",
     POSITION_METRICS_TIMEOUT = "POSITION_METRICS_TIMEOUT",
     POSITION_METRICS_ERROR = "POSITION_METRICS_ERROR",
     ACCOUNT_METRICS_TIMEOUT = "ACCOUNT_METRICS_TIMEOUT",
@@ -81,6 +83,19 @@ declare enum ERROR {
     WS_MANAGER_ERROR = "WS_MANAGER_ERROR",
     STREAM_REQUIRES_CONNECT = "STREAM_REQUIRES_CONNECT"
 }
+declare enum MESSAGE_CATEGORY {
+    TRADE_LOG = "TRADE_LOG",
+    NOTIFICATION = "NOTIFICATION"
+}
+declare enum MESSAGE_TYPE {
+    ORDER = "ORDER",
+    INSTRUMENT_ACTIVATED = "INSTRUMENT_ACTIVATED"
+}
+declare enum ORDER_STATUS {
+    PLACED = "PLACED",
+    FILLED = "FILLED",
+    REJECTED = "REJECTED"
+}
 declare enum WS_MESSAGE {
     ACCOUNT_METRICS = "ACCOUNT_METRICS",
     ACCOUNTS = "ACCOUNTS",
@@ -100,7 +115,8 @@ declare enum WS_MESSAGE {
 }
 declare namespace WS_MESSAGE {
     enum SUBTOPIC {
-        BIG_CHART_COMPONENT = "BigChartComponentPresenter-4"
+        BIG_CHART_COMPONENT = "BigChartComponentPresenter-4",
+        OHLC_STREAM = "OHLCStreamPresenter-0"
     }
 }
 
@@ -109,6 +125,22 @@ declare class DxtradeError extends Error {
     constructor(code: string, message: string);
 }
 
+declare class OrdersDomain {
+    private _ctx;
+    constructor(_ctx: ClientContext);
+    /** Get all pending/open orders via WebSocket. */
+    get(timeout?: number): Promise<Order.Get[]>;
+    /** Cancel a single pending order by its order chain ID. */
+    cancel(orderChainId: number): Promise<void>;
+    /** Cancel all pending orders. */
+    cancelAll(): Promise<void>;
+    /**
+     * Submit a trading order and wait for WebSocket confirmation.
+     * Supports market, limit, and stop orders with optional stop loss and take profit.
+     */
+    submit(params: Order.SubmitParams): Promise<Order.Update>;
+}
+
 declare namespace Order {
     interface Get {
         account: string;
@@ -158,6 +190,7 @@ declare namespace Order {
         orderId: string;
         status: string;
         statusDescription?: string;
+        positionCode?: string;
         [key: string]: unknown;
     }
     interface Model {
@@ -262,6 +295,31 @@ interface WsPayload {
     type: string;
 }
 
+declare class AccountDomain {
+    private _ctx;
+    constructor(_ctx: ClientContext);
+    /** Get account metrics including equity, balance, margin, and open P&L. */
+    metrics(timeout?: number): Promise<Account.Metrics>;
+    /**
+     * Fetch trade history for a date range.
+     * @param params.from - Start timestamp (Unix ms)
+     * @param params.to - End timestamp (Unix ms)
+     */
+    tradeHistory(params: {
+        from: number;
+        to: number;
+    }): Promise<Account.TradeHistory[]>;
+    /**
+     * Fetch trade journal entries for a date range.
+     * @param params.from - Start timestamp (Unix ms)
+     * @param params.to - End timestamp (Unix ms)
+     */
+    tradeJournal(params: {
+        from: number;
+        to: number;
+    }): Promise<any>;
+}
+
 declare namespace Account {
     interface TradeHistory {
         orderId: number;
@@ -292,6 +350,13 @@ declare namespace Account {
     }
 }
 
+declare class AssessmentsDomain {
+    private _ctx;
+    constructor(_ctx: ClientContext);
+    /** Fetch PnL assessments for an instrument within a date range. */
+    get(params: Assessments.Params): Promise<Assessments.Response>;
+}
+
 declare namespace Assessments {
     interface Params {
         from: number;
@@ -305,6 +370,13 @@ declare namespace Assessments {
     }
 }
 
+declare class InstrumentsDomain {
+    private _ctx;
+    constructor(_ctx: ClientContext);
+    /** Get all available instruments, optionally filtered by partial match (e.g. `{ type: "FOREX" }`). */
+    get(params?: Partial<Instrument.Info>, timeout?: number): Promise<Instrument.Info[]>;
+}
+
 declare namespace Instrument {
     interface Info {
         id: number;
@@ -344,6 +416,22 @@ declare namespace Instrument {
     }
 }
 
+declare class OhlcDomain {
+    private _ctx;
+    constructor(_ctx: ClientContext);
+    /** Stream real-time OHLC bar updates. Requires connect(). Returns unsubscribe function. */
+    stream(params: OHLC.Params, callback: (bars: OHLC.Bar[]) => void): Promise<() => void>;
+    /**
+     * Fetch OHLC price bars for a symbol.
+     * @param params.symbol - Instrument symbol (e.g. "EURUSD")
+     * @param params.resolution - Bar period in seconds (default: 60 = 1 min)
+     * @param params.range - Lookback window in seconds (default: 432000 = 5 days)
+     * @param params.maxBars - Maximum bars to return (default: 3500)
+     * @param params.priceField - "bid" or "ask" (default: "bid")
+     */
+    get(params: OHLC.Params, timeout?: number): Promise<OHLC.Bar[]>;
+}
+
 declare namespace OHLC {
     interface Params {
         /** Symbol to fetch bars for (e.g. "EURUSD"). */
@@ -369,6 +457,22 @@ declare namespace OHLC {
     }
 }
 
+declare class PositionsDomain {
+    private _ctx;
+    constructor(_ctx: ClientContext);
+    /** Stream real-time position updates with P&L metrics. Requires connect(). Returns unsubscribe function. */
+    stream(callback: (positions: Position.Full[]) => void): () => void;
+    /** Get all open positions with P&L metrics merged. */
+    get(): Promise<Position.Full[]>;
+    /** Close all open positions with market orders. */
+    closeAll(): Promise<void>;
+    /** Close a position by its position code. Returns the position with P&L metrics. Optionally wait for close confirmation via `waitForClose: "stream" | "poll"`. */
+    close(positionCode: string, options?: Position.CloseOptions): Promise<Position.Full>;
+    private _waitForCloseStream;
+    private _waitForClosePoll;
+    private _sendCloseRequest;
+}
+
 declare namespace Position {
     interface Get {
         uid: string;
@@ -389,13 +493,36 @@ declare namespace Position {
         stopLoss: number | null;
     }
     interface Metrics {
-        positionCode: string;
-        openPl: number;
-        openPlPerLot: number;
-        currentPrice: number;
-        convertedOpenPl: number;
+        uid: string;
+        accountId: string;
+        margin: number;
+        plOpen: number;
+        plClosed: number;
+        totalCommissions: number;
+        totalFinancing: number;
+        plRate: number;
+        averagePrice: number;
+        marketValue: number;
         [key: string]: unknown;
     }
+    interface Full extends Get {
+        margin: number;
+        plOpen: number;
+        plClosed: number;
+        totalCommissions: number;
+        totalFinancing: number;
+        plRate: number;
+        averagePrice: number;
+        marketValue: number;
+    }
+    interface CloseOptions {
+        /** Wait for the position to disappear after closing. "stream" uses the persistent WebSocket (requires connect()), "poll" repeatedly calls getPositions(). */
+        waitForClose?: "stream" | "poll";
+        /** Timeout in ms for waitForClose (default: 30000). */
+        timeout?: number;
+        /** Poll interval in ms when using waitForClose: "poll" (default: 1000). */
+        pollInterval?: number;
+    }
     interface Close {
         legs: {
             instrumentId: number;
@@ -411,6 +538,17 @@ declare namespace Position {
     }
 }
 
+declare class SymbolsDomain {
+    private _ctx;
+    constructor(_ctx: ClientContext);
+    /** Search for symbols matching the given text (e.g. "EURUSD", "BTC"). */
+    search(text: string): Promise<Symbol.Suggestion[]>;
+    /** Get detailed instrument info for a symbol, including volume limits and lot size. */
+    info(symbol: string): Promise<Symbol.Info>;
+    /** Get order size limits and stop/limit distances for all symbols. */
+    limits(timeout?: number): Promise<Symbol.Limits[]>;
+}
+
 declare namespace Symbol {
     interface Suggestion {
         id: number;
@@ -438,94 +576,6 @@ declare namespace Symbol {
     }
 }
 
-declare class PositionsDomain {
-    private _ctx;
-    constructor(_ctx: ClientContext);
-    /** Get all open positions via WebSocket. */
-    get(): Promise<Position.Get[]>;
-    /** Close a position. Supports partial closes by specifying a quantity smaller than the full position size. */
-    close(params: Position.Close): Promise<void>;
-    /** Close all open positions with market orders. */
-    closeAll(): Promise<void>;
-    /** Get position-level P&L metrics via WebSocket. */
-    metrics(): Promise<Position.Metrics[]>;
-    /** Stream real-time position updates. Requires connect(). Returns unsubscribe function. */
-    stream(callback: (positions: Position.Get[]) => void): () => void;
-}
-declare class OrdersDomain {
-    private _ctx;
-    constructor(_ctx: ClientContext);
-    /** Get all pending/open orders via WebSocket. */
-    get(): Promise<Order.Get[]>;
-    /**
-     * Submit a trading order and wait for WebSocket confirmation.
-     * Supports market, limit, and stop orders with optional stop loss and take profit.
-     */
-    submit(params: Order.SubmitParams): Promise<Order.Update>;
-    /** Cancel a single pending order by its order chain ID. */
-    cancel(orderChainId: number): Promise<void>;
-    /** Cancel all pending orders. */
-    cancelAll(): Promise<void>;
-}
-declare class AccountDomain {
-    private _ctx;
-    constructor(_ctx: ClientContext);
-    /** Get account metrics including equity, balance, margin, and open P&L. */
-    metrics(): Promise<Account.Metrics>;
-    /**
-     * Fetch trade journal entries for a date range.
-     * @param params.from - Start timestamp (Unix ms)
-     * @param params.to - End timestamp (Unix ms)
-     */
-    tradeJournal(params: {
-        from: number;
-        to: number;
-    }): Promise<any>;
-    /**
-     * Fetch trade history for a date range.
-     * @param params.from - Start timestamp (Unix ms)
-     * @param params.to - End timestamp (Unix ms)
-     */
-    tradeHistory(params: {
-        from: number;
-        to: number;
-    }): Promise<Account.TradeHistory[]>;
-}
-declare class SymbolsDomain {
-    private _ctx;
-    constructor(_ctx: ClientContext);
-    /** Search for symbols matching the given text (e.g. "EURUSD", "BTC"). */
-    search(text: string): Promise<Symbol.Suggestion[]>;
-    /** Get detailed instrument info for a symbol, including volume limits and lot size. */
-    info(symbol: string): Promise<Symbol.Info>;
-    /** Get order size limits and stop/limit distances for all symbols. */
-    limits(): Promise<Symbol.Limits[]>;
-}
-declare class InstrumentsDomain {
-    private _ctx;
-    constructor(_ctx: ClientContext);
-    /** Get all available instruments, optionally filtered by partial match (e.g. `{ type: "FOREX" }`). */
-    get(params?: Partial<Instrument.Info>): Promise<Instrument.Info[]>;
-}
-declare class OhlcDomain {
-    private _ctx;
-    constructor(_ctx: ClientContext);
-    /**
-     * Fetch OHLC price bars for a symbol.
-     * @param params.symbol - Instrument symbol (e.g. "EURUSD")
-     * @param params.resolution - Bar period in seconds (default: 60 = 1 min)
-     * @param params.range - Lookback window in seconds (default: 432000 = 5 days)
-     * @param params.maxBars - Maximum bars to return (default: 3500)
-     * @param params.priceField - "bid" or "ask" (default: "bid")
-     */
-    get(params: OHLC.Params): Promise<OHLC.Bar[]>;
-}
-declare class AssessmentsDomain {
-    private _ctx;
-    constructor(_ctx: ClientContext);
-    /** Fetch PnL assessments for an instrument within a date range. */
-    get(params: Assessments.Params): Promise<Assessments.Response>;
-}
 /**
  * Client for interacting with the DXtrade trading API.
  *
@@ -544,6 +594,7 @@ declare class AssessmentsDomain {
  */
 declare class DxtradeClient {
     private _ctx;
+    private _session;
     /** Position operations: get, close, metrics, streaming. */
     readonly positions: PositionsDomain;
     /** Order operations: get, submit, cancel. */
@@ -554,7 +605,7 @@ declare class DxtradeClient {
     readonly symbols: SymbolsDomain;
     /** Instrument operations: get (with optional filtering). */
     readonly instruments: InstrumentsDomain;
-    /** OHLC price bar operations: get. */
+    /** OHLC price bar operations: get, stream. */
     readonly ohlc: OhlcDomain;
     /** PnL assessment operations: get. */
     readonly assessments: AssessmentsDomain;
@@ -573,4 +624,4 @@ declare class DxtradeClient {
     disconnect(): void;
 }
 
-export { ACTION, BROKER, type DxtradeCallbacks, DxtradeClient, type DxtradeConfig, DxtradeError, ERROR, ORDER_TYPE, SIDE, TIF, WS_MESSAGE, type WsPayload, endpoints };
+export { ACTION, BROKER, type DxtradeCallbacks, DxtradeClient, type DxtradeConfig, DxtradeError, ERROR, MESSAGE_CATEGORY, MESSAGE_TYPE, ORDER_STATUS, ORDER_TYPE, SIDE, TIF, WS_MESSAGE, type WsPayload, endpoints };