@danielgroen/dxtrade-api 1.0.23 → 1.0.25

package/README.md

@@ -26,13 +26,15 @@ 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()`
+- [x] Real-time position streaming
 - [x] Full TypeScript support
 - [ ] Batch orders
 - [ ] Modify existing orders
-- [ ] Real-time price streaming
+- [x] Real-time OHLC streaming
 
 ## Quick Start
 
@@ -46,12 +48,13 @@ const client = new DxtradeClient({
   accountId: "optional_account_id",
 });
 
-await client.connect();
+// await client.auth(); // Auth only
+await client.connect(); // Auth + persistent WebSocket (recommended)
 
-const suggestions = await client.getSymbolSuggestions("EURUSD");
+const suggestions = await client.symbols.search("EURUSD");
 const symbol = suggestions[0];
 
-const order = await client.submitOrder({
+const order = await client.orders.submit({
   symbol: symbol.name,
   side: SIDE.BUY,
   quantity: 0.01,
@@ -60,6 +63,18 @@ const order = await client.submitOrder({
 });
 
 console.log(`Order ${order.orderId}: ${order.status}`);
+client.disconnect(); // disconnect stream -- only needed if client.connect()
+```
+
+## Connection Modes
+
+```ts
+// 1. Persistent WebSocket (recommended) — reuses one WS for all data, enables streaming
+await client.connect();
+client.disconnect(); // when done
+
+// 2. Lightweight — auth only, each data call opens a temporary WebSocket
+await client.auth();
 ```
 
 ## Configuration
@@ -89,42 +104,51 @@ BROKER.FTMO         // "https://dxtrade.ftmo.com"
 
 ### Session
 
-- `client.connect()` — Login, fetch CSRF, WebSocket handshake, optional account switch
+- `client.connect()` — Auth + persistent WebSocket. Recommended for most use cases.
+- `client.auth()` — Lightweight: login, fetch CSRF, WebSocket handshake, optional account switch. No persistent WS.
+- `client.disconnect()` — Close the persistent WebSocket connection
 - `client.login()` — Authenticate with broker
 - `client.fetchCsrf()` — Fetch CSRF token from broker page
 - `client.switchAccount(accountId)` — Switch to a specific account
 
-### Market Data
+### Positions
 
-- `client.getSymbolSuggestions(text)` — Search for symbols
-- `client.getSymbolInfo(symbol)` — Get instrument info (volume limits, lot size)
-- `client.getSymbolLimits()` — Get order size limits and stop/limit distances for all symbols
-- `client.getInstruments(params?)` — Get all available instruments, optionally filtered by partial match (e.g. `{ type: "FOREX" }`)
-- `client.getOHLC(params)` — Fetch OHLC price bars for a symbol (resolution, range, maxBars, priceField)
+- `client.positions.get()` — Get all open positions with P&L metrics merged (margin, plOpen, marketValue, etc.)
+- `client.positions.close(params)` — Close a position (supports partial closes via the quantity field)
+- `client.positions.closeAll()` — Close all open positions with market orders
+- `client.positions.stream(callback)` — Stream real-time position updates with live P&L (requires `connect()`). Returns an unsubscribe function.
 
-### Trading
+### Orders
 
-- `client.submitOrder(params)` — Submit an order and wait for WebSocket confirmation
-- `client.getOrders()` — Get all pending/open orders via WebSocket
-- `client.cancelOrder(orderChainId)` — Cancel a single pending order
-- `client.cancelAllOrders()` — Cancel all pending orders
+- `client.orders.get()` — Get all pending/open orders
+- `client.orders.submit(params)` — Submit an order and wait for WebSocket confirmation
+- `client.orders.cancel(orderChainId)` — Cancel a single pending order
+- `client.orders.cancelAll()` — Cancel all pending orders
 
-### Positions
+### Account
 
-- `client.getPositions()` — Get all open positions via WebSocket
-- `client.closePosition(params)` — Close a position (supports partial closes via the quantity field)
-- `client.closeAllPositions()` — Close all open positions with market orders
-- `client.getPositionMetrics()` — Get position-level P&L metrics via WebSocket
+- `client.account.metrics()` — Get account metrics (equity, balance, margin, open P&L, etc.)
+- `client.account.tradeJournal({ from, to })` — Fetch trade journal entries for a date range (Unix timestamps)
+- `client.account.tradeHistory({ from, to })` — Fetch trade history for a date range (Unix timestamps)
 
-### Account
+### Symbols
+
+- `client.symbols.search(text)` — Search for symbols
+- `client.symbols.info(symbol)` — Get instrument info (volume limits, lot size)
+- `client.symbols.limits()` — Get order size limits and stop/limit distances for all symbols
+
+### Instruments
+
+- `client.instruments.get(params?)` — Get all available instruments, optionally filtered by partial match (e.g. `{ type: "FOREX" }`)
+
+### OHLC
 
-- `client.getAccountMetrics()` — Get account metrics (equity, balance, margin, open P&L, etc.)
-- `client.getTradeJournal({ from, to })` — Fetch trade journal entries for a date range (Unix timestamps)
-- `client.getTradeHistory({ from, to })` — Fetch trade history for a date range (Unix timestamps)
+- `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.
 
-### Analytics
+### Assessments
 
-- `client.getAssessments(params)` — Fetch PnL assessments for a date range
+- `client.assessments.get(params)` — Fetch PnL assessments for a date range
 
 ## Enums
 
@@ -157,23 +181,25 @@ const client = new DxtradeClient({
 ```bash
 cp .env.example .env  # fill in credentials
 npm run example:connect
-npm run example:order
-npm run example:orders
-npm run example:positions
-npm run example:close-position
-npm run example:close-all-positions
-npm run example:position-metrics
-npm run example:assessments
-npm run example:assessments:btc
-npm run example:account
-npm run example:instruments
-npm run example:ohlc
-npm run example:instruments:forex
-npm run example:symbol
-npm run example:symbol:btc
-npm run example:trade-journal
-npm run example:trade-history
 npm run example:debug
+npm run example:positions:get
+npm run example:positions:close
+npm run example:positions:close-all
+npm run example:positions:metrics
+npm run example:positions:stream
+npm run example:orders:submit
+npm run example:account:metrics
+npm run example:account:trade-journal
+npm run example:account:trade-history
+npm run example:symbols:info
+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
 ```
 
 ## DXtrade API Docs

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { EventEmitter } from 'events';
+
 declare const BROKER: {
     readonly LARKFUNDING: "https://trade.gooeytrade.com";
     readonly EIGHTCAP: "https://trader.dx-eightcap.com";
@@ -74,7 +76,10 @@ declare enum ERROR {
     ACCOUNT_POSITIONS_ERROR = "ACCOUNT_POSITIONS_ERROR",
     TRADE_JOURNAL_ERROR = "TRADE_JOURNAL_ERROR",
     TRADE_HISTORY_ERROR = "TRADE_HISTORY_ERROR",
-    ASSESSMENTS_ERROR = "ASSESSMENTS_ERROR"
+    ASSESSMENTS_ERROR = "ASSESSMENTS_ERROR",
+    RATE_LIMITED = "RATE_LIMITED",
+    WS_MANAGER_ERROR = "WS_MANAGER_ERROR",
+    STREAM_REQUIRES_CONNECT = "STREAM_REQUIRES_CONNECT"
 }
 declare enum WS_MESSAGE {
     ACCOUNT_METRICS = "ACCOUNT_METRICS",
@@ -95,7 +100,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"
     }
 }
 
@@ -209,6 +215,16 @@ declare namespace Order {
     }
 }
 
+declare class WsManager extends EventEmitter {
+    private _ws;
+    private _cache;
+    connect(wsUrl: string, cookieStr: string, debug?: boolean | string): Promise<void>;
+    waitFor<T>(type: string, timeout?: number): Promise<T>;
+    getCached<T>(type: string): T | undefined;
+    close(): void;
+    get isConnected(): boolean;
+}
+
 interface DxtradeConfig {
     username: string;
     password: string;
@@ -226,6 +242,20 @@ interface DxtradeCallbacks {
     onOrderPlaced?: (order: Order.Response) => void;
     onOrderUpdate?: (order: Order.Update) => void;
 }
+interface ClientContext {
+    config: DxtradeConfig;
+    callbacks: DxtradeCallbacks;
+    cookies: Record<string, string>;
+    csrf: string | null;
+    accountId: string | null;
+    atmosphereId: string | null;
+    wsManager: WsManager | null;
+    broker: keyof typeof BROKER;
+    retries: number;
+    debug: boolean | string;
+    ensureSession(): void;
+    throwError(code: string, message: string): never;
+}
 
 interface WsPayload {
     accountId: string | null;
@@ -360,13 +390,28 @@ 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 Close {
         legs: {
             instrumentId: number;
@@ -409,68 +454,44 @@ declare namespace Symbol {
     }
 }
 
-/**
- * Client for interacting with the DXtrade trading API.
- *
- * @example
- * ```ts
- * import { DxtradeClient, ORDER_TYPE, SIDE, BROKER } from "dxtrade-api";
- *
- * const client = new DxtradeClient({
- *   username: "your_username",
- *   password: "your_password",
- *   broker: BROKER.FTMO,
- * });
- *
- * await client.connect();
- * ```
- */
-declare class DxtradeClient {
+declare class PositionsDomain {
     private _ctx;
-    constructor(config: DxtradeConfig);
-    /** Authenticate with the broker using username and password. */
-    login(): Promise<void>;
-    /** Fetch the CSRF token required for authenticated requests. */
-    fetchCsrf(): Promise<void>;
-    /** Switch to a specific trading account by ID. */
-    switchAccount(accountId: string): Promise<void>;
-    /** Connect to the broker: login, fetch CSRF, WebSocket handshake, and optional account switch. */
-    connect(): Promise<void>;
-    /** Search for symbols matching the given text (e.g. "EURUSD", "BTC"). */
-    getSymbolSuggestions(text: string): Promise<Symbol.Suggestion[]>;
-    /** Get detailed instrument info for a symbol, including volume limits and lot size. */
-    getSymbolInfo(symbol: string): Promise<Symbol.Info>;
-    /** Get order size limits and stop/limit distances for all symbols. */
-    getSymbolLimits(): Promise<Symbol.Limits[]>;
+    constructor(_ctx: ClientContext);
+    /** Get all open positions with P&L metrics merged. */
+    get(): Promise<Position.Full[]>;
+    /** 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>;
+    /** Stream real-time position updates with P&L metrics. Requires connect(). Returns unsubscribe function. */
+    stream(callback: (positions: Position.Full[]) => 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.
      */
-    submitOrder(params: Order.SubmitParams): Promise<Order.Update>;
-    /** Get all pending/open orders via WebSocket. */
-    getOrders(): Promise<Order.Get[]>;
+    submit(params: Order.SubmitParams): Promise<Order.Update>;
     /** Cancel a single pending order by its order chain ID. */
-    cancelOrder(orderChainId: number): Promise<void>;
+    cancel(orderChainId: number): Promise<void>;
     /** Cancel all pending orders. */
-    cancelAllOrders(): Promise<void>;
+    cancelAll(): Promise<void>;
+}
+declare class AccountDomain {
+    private _ctx;
+    constructor(_ctx: ClientContext);
     /** Get account metrics including equity, balance, margin, and open P&L. */
-    getAccountMetrics(): Promise<Account.Metrics>;
-    /** Get all open positions via WebSocket. */
-    getPositions(): Promise<Position.Get[]>;
-    /**
-     * Close a position. Supports partial closes by specifying a quantity smaller than the full position size.
-     */
-    closePosition(position: Position.Close): Promise<void>;
-    /** Close all open positions with market orders. */
-    closeAllPositions(): Promise<void>;
-    /** Get position-level P&L metrics via WebSocket. */
-    getPositionMetrics(): Promise<Position.Metrics[]>;
+    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)
      */
-    getTradeJournal(params: {
+    tradeJournal(params: {
         from: number;
         to: number;
     }): Promise<any>;
@@ -479,14 +500,30 @@ declare class DxtradeClient {
      * @param params.from - Start timestamp (Unix ms)
      * @param params.to - End timestamp (Unix ms)
      */
-    getTradeHistory(params: {
+    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" }`). */
-    getInstruments(params?: Partial<Instrument.Info>): Promise<Instrument.Info[]>;
-    /** Fetch PnL assessments for an instrument within a date range. */
-    getAssessments(params: Assessments.Params): Promise<Assessments.Response>;
+    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")
@@ -495,7 +532,61 @@ declare class DxtradeClient {
      * @param params.maxBars - Maximum bars to return (default: 3500)
      * @param params.priceField - "bid" or "ask" (default: "bid")
      */
-    getOHLC(params: OHLC.Params): Promise<OHLC.Bar[]>;
+    get(params: OHLC.Params): Promise<OHLC.Bar[]>;
+    /** Stream real-time OHLC bar updates. Requires connect(). Returns unsubscribe function. */
+    stream(params: OHLC.Params, callback: (bars: OHLC.Bar[]) => void): Promise<() => void>;
+}
+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.
+ *
+ * @example
+ * ```ts
+ * import { DxtradeClient, ORDER_TYPE, SIDE, BROKER } from "dxtrade-api";
+ *
+ * const client = new DxtradeClient({
+ *   username: "your_username",
+ *   password: "your_password",
+ *   broker: BROKER.FTMO,
+ * });
+ *
+ * await client.connect();
+ * ```
+ */
+declare class DxtradeClient {
+    private _ctx;
+    /** Position operations: get, close, metrics, streaming. */
+    readonly positions: PositionsDomain;
+    /** Order operations: get, submit, cancel. */
+    readonly orders: OrdersDomain;
+    /** Account operations: metrics, trade journal, trade history. */
+    readonly account: AccountDomain;
+    /** Symbol operations: search, info, limits. */
+    readonly symbols: SymbolsDomain;
+    /** Instrument operations: get (with optional filtering). */
+    readonly instruments: InstrumentsDomain;
+    /** OHLC price bar operations: get, stream. */
+    readonly ohlc: OhlcDomain;
+    /** PnL assessment operations: get. */
+    readonly assessments: AssessmentsDomain;
+    constructor(config: DxtradeConfig);
+    /** Authenticate with the broker using username and password. */
+    login(): Promise<void>;
+    /** Fetch the CSRF token required for authenticated requests. */
+    fetchCsrf(): Promise<void>;
+    /** Switch to a specific trading account by ID. */
+    switchAccount(accountId: string): Promise<void>;
+    /** Authenticate and establish a session: login, fetch CSRF, WebSocket handshake, and optional account switch. */
+    auth(): Promise<void>;
+    /** Connect to the broker with a persistent WebSocket: auth + persistent WS for data reuse and streaming. */
+    connect(): Promise<void>;
+    /** Close the persistent WebSocket connection. */
+    disconnect(): void;
 }
 
 export { ACTION, BROKER, type DxtradeCallbacks, DxtradeClient, type DxtradeConfig, DxtradeError, ERROR, ORDER_TYPE, SIDE, TIF, WS_MESSAGE, type WsPayload, endpoints };