@mautriz/mt5 1.0.0

package/index.ts

@@ -0,0 +1,477 @@
+// ── Response types ──────────────────────────────────────────────────
+
+export interface AccountInfo {
+  balance: number;
+  equity: number;
+  margin: number;
+  free_margin: number;
+  profit: number;
+  leverage: number;
+  currency: string;
+  name: string;
+  number: number;
+  server: string;
+  company: string;
+}
+
+export interface Position {
+  ticket: number;
+  symbol: string;
+  type: "buy" | "sell";
+  volume: number;
+  open_price: number;
+  sl: number;
+  tp: number;
+  profit: number;
+  open_time: string;
+}
+
+export type PendingOrderType =
+  | "buy_limit"
+  | "sell_limit"
+  | "buy_stop"
+  | "sell_stop"
+  | "unknown";
+
+export interface PendingOrder {
+  ticket: number;
+  symbol: string;
+  type: PendingOrderType;
+  volume: number;
+  price: number;
+  sl: number;
+  tp: number;
+}
+
+export type DealType = "buy" | "sell" | "other";
+export type DealEntry = "in" | "out" | "inout" | "unknown";
+
+export interface Deal {
+  ticket: number;
+  symbol: string;
+  type: DealType;
+  entry: DealEntry;
+  volume: number;
+  price: number;
+  profit: number;
+  commission: number;
+  swap: number;
+  time: string;
+}
+
+export interface SymbolTick {
+  symbol: string;
+  bid: number;
+  ask: number;
+  last: number;
+  volume: number;
+  time: string;
+}
+
+export type TradeMode =
+  | "disabled"
+  | "longonly"
+  | "shortonly"
+  | "closeonly"
+  | "full"
+  | "unknown";
+
+export interface TimeOffset {
+  offset_seconds: number;
+  server_time: string;
+  gmt_time: string;
+}
+
+export interface SymbolDetails {
+  symbol: string;
+  description: string;
+  digits: number;
+  point: number;
+  spread: number;
+  trade_mode: TradeMode;
+  volume_min: number;
+  volume_max: number;
+  volume_step: number;
+  trade_contract_size: number;
+  filling_mode: number;
+  bid: number;
+  ask: number;
+}
+
+// ── Request parameter types ─────────────────────────────────────────
+
+export type OrderType =
+  | "buy"
+  | "sell"
+  | "buy_limit"
+  | "sell_limit"
+  | "buy_stop"
+  | "sell_stop";
+
+export interface OpenOrderParams {
+  type: OrderType;
+  symbol: string;
+  volume: number;
+  price?: number;
+  sl?: number;
+  tp?: number;
+}
+
+export interface CloseOrderParams {
+  ticket: number;
+  volume?: number;
+}
+
+export interface ModifyOrderParams {
+  ticket: number;
+  sl?: number;
+  tp?: number;
+  price?: number;
+}
+
+// ── Error type ──────────────────────────────────────────────────────
+
+export class MT5Error extends Error {
+  public readonly retcode: number | undefined;
+
+  constructor(message: string, retcode?: number) {
+    super(message);
+    this.name = "MT5Error";
+    this.retcode = retcode;
+  }
+}
+
+// ── Push message types ──────────────────────────────────────────────
+
+export interface HelloMessage {
+  type: "hello";
+  ea: string;
+  symbol: string;
+  [key: string]: unknown;
+}
+
+export interface TickMessage {
+  type: "tick";
+  symbol: string;
+  bid: number;
+  ask: number;
+  [key: string]: unknown;
+}
+
+export interface PushMessage {
+  type: string;
+  [key: string]: unknown;
+}
+
+type PushEventMap = {
+  hello: HelloMessage;
+  tick: TickMessage;
+  message: PushMessage;
+  connected: undefined;
+  disconnected: { code: number; reason: string };
+  error: Event;
+};
+
+type EventCallback<T> = T extends undefined ? () => void : (data: T) => void;
+
+// ── Internal types ──────────────────────────────────────────────────
+
+interface PendingRequest {
+  resolve: (value: any) => void;
+  reject: (reason: any) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+// ── Client ──────────────────────────────────────────────────────────
+
+export class MT5Client {
+  private readonly url: string;
+  private ws: WebSocket | null = null;
+  private reqCounter = 0;
+  private pending = new Map<string, PendingRequest>();
+  private listeners = new Map<string, Set<Function>>();
+  private timeoutMs: number;
+
+  constructor(url: string, options?: { timeout?: number }) {
+    this.url = url;
+    this.timeoutMs = options?.timeout ?? 30_000;
+  }
+
+  // ── Connection ──────────────────────────────────────────────────
+
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+        resolve();
+        return;
+      }
+
+      const ws = new WebSocket(this.url);
+      this.ws = ws;
+
+      const onOpen = () => {
+        cleanup();
+        this.setupHandlers(ws);
+        this.emit("connected", undefined);
+        resolve();
+      };
+
+      const onError = (ev: Event) => {
+        cleanup();
+        reject(new MT5Error("WebSocket connection failed"));
+      };
+
+      const onClose = () => {
+        cleanup();
+        reject(new MT5Error("WebSocket closed before connection was established"));
+      };
+
+      const cleanup = () => {
+        ws.removeEventListener("open", onOpen);
+        ws.removeEventListener("error", onError);
+        ws.removeEventListener("close", onClose);
+      };
+
+      ws.addEventListener("open", onOpen);
+      ws.addEventListener("error", onError);
+      ws.addEventListener("close", onClose);
+    });
+  }
+
+  disconnect(): void {
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    for (const [, req] of this.pending) {
+      clearTimeout(req.timer);
+      req.reject(new MT5Error("Disconnected"));
+    }
+    this.pending.clear();
+  }
+
+  get connected(): boolean {
+    return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+  }
+
+  // ── Event emitter ───────────────────────────────────────────────
+
+  on<K extends keyof PushEventMap>(
+    event: K,
+    callback: EventCallback<PushEventMap[K]>
+  ): this {
+    let set = this.listeners.get(event);
+    if (!set) {
+      set = new Set();
+      this.listeners.set(event, set);
+    }
+    set.add(callback);
+    return this;
+  }
+
+  off<K extends keyof PushEventMap>(
+    event: K,
+    callback: EventCallback<PushEventMap[K]>
+  ): this {
+    const set = this.listeners.get(event);
+    if (set) {
+      set.delete(callback);
+      if (set.size === 0) this.listeners.delete(event);
+    }
+    return this;
+  }
+
+  private emit<K extends keyof PushEventMap>(
+    event: K,
+    data: PushEventMap[K]
+  ): void {
+    const set = this.listeners.get(event);
+    if (set) {
+      for (const cb of set) {
+        (cb as Function)(data);
+      }
+    }
+  }
+
+  // ── API methods ─────────────────────────────────────────────────
+
+  async getAccount(): Promise<AccountInfo> {
+    const res = await this.request({ action: "get_account" });
+    return {
+      balance: res.balance,
+      equity: res.equity,
+      margin: res.margin,
+      free_margin: res.free_margin,
+      profit: res.profit,
+      leverage: res.leverage,
+      currency: res.currency,
+      name: res.name,
+      number: res.number,
+      server: res.server,
+      company: res.company,
+    };
+  }
+
+  async openOrder(params: OpenOrderParams): Promise<{ ticket: number }> {
+    const res = await this.request({
+      action: "open_order",
+      type: params.type,
+      symbol: params.symbol,
+      volume: params.volume,
+      ...(params.price !== undefined && { price: params.price }),
+      ...(params.sl !== undefined && { sl: params.sl }),
+      ...(params.tp !== undefined && { tp: params.tp }),
+    });
+    return { ticket: res.ticket };
+  }
+
+  async closeOrder(params: CloseOrderParams): Promise<{ ticket: number }> {
+    const res = await this.request({
+      action: "close_order",
+      ticket: params.ticket,
+      ...(params.volume !== undefined && { volume: params.volume }),
+    });
+    return { ticket: res.ticket };
+  }
+
+  async modifyOrder(params: ModifyOrderParams): Promise<void> {
+    await this.request({
+      action: "modify_order",
+      ticket: params.ticket,
+      ...(params.sl !== undefined && { sl: params.sl }),
+      ...(params.tp !== undefined && { tp: params.tp }),
+      ...(params.price !== undefined && { price: params.price }),
+    });
+  }
+
+  async getPositions(): Promise<Position[]> {
+    const res = await this.request({ action: "get_positions" });
+    return res.positions;
+  }
+
+  async getOrders(): Promise<PendingOrder[]> {
+    const res = await this.request({ action: "get_orders" });
+    return res.orders;
+  }
+
+  async getDeals(days?: number): Promise<Deal[]> {
+    const res = await this.request({
+      action: "get_deals",
+      ...(days !== undefined && { days }),
+    });
+    return res.deals;
+  }
+
+  async getSymbolTick(symbol: string): Promise<SymbolTick> {
+    const res = await this.request({ action: "get_symbol_tick", symbol });
+    return {
+      symbol: res.symbol,
+      bid: res.bid,
+      ask: res.ask,
+      last: res.last,
+      volume: res.volume,
+      time: res.time,
+    };
+  }
+
+  async getSymbolDetails(symbol: string): Promise<SymbolDetails> {
+    const res = await this.request({ action: "get_symbol_details", symbol });
+    return {
+      symbol: res.symbol,
+      description: res.description,
+      digits: res.digits,
+      point: res.point,
+      spread: res.spread,
+      trade_mode: res.trade_mode,
+      volume_min: res.volume_min,
+      volume_max: res.volume_max,
+      volume_step: res.volume_step,
+      trade_contract_size: res.trade_contract_size,
+      filling_mode: res.filling_mode,
+      bid: res.bid,
+      ask: res.ask,
+    };
+  }
+
+  async getTimeOffset(): Promise<TimeOffset> {
+    const res = await this.request({ action: "get_time_offset" });
+    return {
+      offset_seconds: res.offset_seconds,
+      server_time: res.server_time,
+      gmt_time: res.gmt_time,
+    };
+  }
+
+  // ── Internals ───────────────────────────────────────────────────
+
+  private nextId(): string {
+    return `req-${++this.reqCounter}`;
+  }
+
+  private request(payload: Record<string, unknown>): Promise<any> {
+    return new Promise((resolve, reject) => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        reject(new MT5Error("Not connected"));
+        return;
+      }
+
+      const id = this.nextId();
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new MT5Error(`Request ${id} timed out after ${this.timeoutMs}ms`));
+      }, this.timeoutMs);
+
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify({ ...payload, id }));
+    });
+  }
+
+  private setupHandlers(ws: WebSocket): void {
+    ws.addEventListener("message", (ev: MessageEvent) => {
+      let msg: any;
+      try {
+        msg = JSON.parse(typeof ev.data === "string" ? ev.data : String(ev.data));
+      } catch {
+        return;
+      }
+
+      // Response to a request (has an "id" field matching a pending request)
+      if (msg.id && this.pending.has(msg.id)) {
+        const req = this.pending.get(msg.id)!;
+        this.pending.delete(msg.id);
+        clearTimeout(req.timer);
+
+        if (msg.status === "ok") {
+          req.resolve(msg);
+        } else {
+          req.reject(new MT5Error(msg.error || "Unknown error", msg.retcode));
+        }
+        return;
+      }
+
+      // Push message from EA (no matching request id)
+      if (msg.type) {
+        this.emit(msg.type as keyof PushEventMap, msg as any);
+        // Also emit on the generic "message" event
+        this.emit("message", msg as PushMessage);
+      }
+    });
+
+    ws.addEventListener("close", (ev: CloseEvent) => {
+      this.emit("disconnected", {
+        code: ev.code,
+        reason: ev.reason,
+      });
+      for (const [, req] of this.pending) {
+        clearTimeout(req.timer);
+        req.reject(new MT5Error("Connection closed"));
+      }
+      this.pending.clear();
+      this.ws = null;
+    });
+
+    ws.addEventListener("error", (ev: Event) => {
+      this.emit("error", ev);
+    });
+  }
+}

package/mt5.test.ts

@@ -0,0 +1,209 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { MT5Client } from "./index";
+
+const SYMBOL = process.env.SYMBOL || "BTCUSD";
+const URL = process.env.WS_URL || "ws://localhost:8080";
+
+const mt5 = new MT5Client(URL, { timeout: 300_000 });
+
+let buyTicket: number;
+let sellTicket: number;
+
+beforeAll(async () => {
+  await mt5.connect();
+});
+
+afterAll(() => {
+  mt5.disconnect();
+});
+
+describe("Account", () => {
+  it("should return account info", async () => {
+    const account = await mt5.getAccount();
+    expect(account.balance).toBeTypeOf("number");
+    expect(account.equity).toBeTypeOf("number");
+    expect(account.leverage).toBeGreaterThan(0);
+    console.log(
+      `    balance=${account.balance} equity=${account.equity} leverage=${account.leverage}`,
+    );
+  });
+});
+
+describe("Symbol", () => {
+  it("should return symbol details", async () => {
+    const details = await mt5.getSymbolDetails(SYMBOL);
+    expect(details.symbol).toBe(SYMBOL);
+    expect(details.trade_mode).toBe("full");
+    expect(details.volume_min).toBeGreaterThan(0);
+    console.log(
+      `    ${details.symbol}: digits=${details.digits} spread=${details.spread} filling_mode=${details.filling_mode}`,
+    );
+    console.log(
+      `    volume: min=${details.volume_min} max=${details.volume_max} step=${details.volume_step}`,
+    );
+  });
+
+  it("should return symbol tick with bid/ask", async () => {
+    let tick;
+    for (let attempt = 1; attempt <= 5; attempt++) {
+      tick = await mt5.getSymbolTick(SYMBOL);
+      if (tick.bid > 0) break;
+      console.log(`    attempt ${attempt}/5 — no quotes yet, waiting 1s...`);
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+    expect(tick!.bid).toBeGreaterThan(0);
+    expect(tick!.ask).toBeGreaterThan(0);
+    console.log(`    bid=${tick!.bid} ask=${tick!.ask} last=${tick!.last}`);
+  });
+});
+
+describe("Orders", () => {
+  it("should open a buy order", async () => {
+    const result = await mt5.openOrder({
+      type: "buy",
+      symbol: SYMBOL,
+      volume: 0.1,
+    });
+    expect(result.ticket).toBeGreaterThan(0);
+    buyTicket = result.ticket;
+    console.log(`    ticket=${buyTicket}`);
+  });
+
+  it("should show the buy in positions", async () => {
+    const positions = await mt5.getPositions();
+    const our = positions.find((p) => p.ticket === buyTicket);
+    expect(our).toBeDefined();
+    expect(our!.type).toBe("buy");
+    expect(our!.symbol).toBe(SYMBOL);
+    console.log(
+      `    found ${positions.length} position(s), ours: ticket=${our!.ticket} ${our!.type} ${our!.volume} ${our!.symbol}`,
+    );
+  });
+
+  it("should open a sell order", async () => {
+    const result = await mt5.openOrder({
+      type: "sell",
+      symbol: SYMBOL,
+      volume: 0.01,
+    });
+    expect(result.ticket).toBeGreaterThan(0);
+    sellTicket = result.ticket;
+    console.log(`    ticket=${sellTicket}`);
+  });
+
+  it("should close the buy position", async () => {
+    const result = await mt5.closeOrder({ ticket: buyTicket });
+    expect(result.ticket).toBeGreaterThan(0);
+  });
+
+  it("should close the sell position", async () => {
+    const result = await mt5.closeOrder({ ticket: sellTicket });
+    expect(result.ticket).toBeGreaterThan(0);
+  });
+
+  it("should have no remaining positions for our tickets", async () => {
+    const positions = await mt5.getPositions();
+    const ours = positions.filter(
+      (p) => p.ticket === buyTicket || p.ticket === sellTicket,
+    );
+    expect(ours).toHaveLength(0);
+    console.log(
+      `    ${positions.length} position(s) remaining (none are ours)`,
+    );
+  });
+});
+
+describe("Concurrent - Four Clients", () => {
+  it("should open and close orders simultaneously from 4 clients", async () => {
+    const clients = await Promise.all(
+      Array.from({ length: 3 }, () => {
+        const c = new MT5Client(URL, { timeout: 300_000 });
+        return c.connect().then(() => c);
+      }),
+    );
+    const allClients = [mt5, ...clients];
+
+    // Open 4 orders simultaneously from different clients
+    const opens = await Promise.all(
+      allClients.map((c, i) =>
+        c.openOrder({
+          type: i % 2 === 0 ? "buy" : "sell",
+          symbol: SYMBOL,
+          volume: 0.01,
+        }),
+      ),
+    );
+
+    for (const o of opens) {
+      expect(o.ticket).toBeGreaterThan(0);
+    }
+    console.log(`    tickets: ${opens.map((o) => o.ticket).join(", ")}`);
+
+    // Close all 4 simultaneously
+    const closes = await Promise.all(
+      allClients.map((c, i) => c.closeOrder({ ticket: opens[i].ticket })),
+    );
+
+    for (const c of closes) {
+      expect(c.ticket).toBeGreaterThan(0);
+    }
+    console.log(`    all 4 closed simultaneously`);
+
+    for (const c of clients) c.disconnect();
+  });
+});
+
+describe("Concurrent - Same Client", () => {
+  it("should open and close 4 positions simultaneously from one client", async () => {
+    // Open 4 orders simultaneously
+    const opens = await Promise.all(
+      Array.from({ length: 4 }, (_, i) =>
+        mt5.openOrder({
+          type: i % 2 === 0 ? "buy" : "sell",
+          symbol: SYMBOL,
+          volume: 0.01,
+        }),
+      ),
+    );
+
+    for (const o of opens) {
+      expect(o.ticket).toBeGreaterThan(0);
+    }
+    console.log(`    opened: ${opens.map((o) => o.ticket).join(", ")}`);
+
+    // Close all 4 simultaneously
+    const closes = await Promise.all(
+      opens.map((o) => mt5.closeOrder({ ticket: o.ticket })),
+    );
+
+    for (const c of closes) {
+      expect(c.ticket).toBeGreaterThan(0);
+    }
+    console.log(`    all 4 closed simultaneously`);
+
+    // Verify all gone
+    const positions = await mt5.getPositions();
+    const ours = positions.filter((p) =>
+      opens.some((o) => o.ticket === p.ticket),
+    );
+    expect(ours).toHaveLength(0);
+    console.log(`    verified: ${positions.length} position(s) remaining`);
+  });
+});
+
+describe("Deals", () => {
+  it("should contain our trades in history", async () => {
+    const deals = await mt5.getDeals(1);
+    expect(deals.length).toBeGreaterThan(0);
+    console.log(`    ${deals.length} deal(s) in last 24h`);
+
+    const ourDeals = deals.filter((d) => d.symbol === SYMBOL);
+    const entries = ourDeals.filter((d) => d.entry === "in");
+    const exits = ourDeals.filter((d) => d.entry === "out");
+    console.log(
+      `    ${SYMBOL}: ${entries.length} entry deal(s), ${exits.length} exit deal(s)`,
+    );
+    expect(entries.length).toBeGreaterThanOrEqual(2);
+    expect(exits.length).toBeGreaterThanOrEqual(2);
+  });
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@mautriz/mt5",
+  "version": "1.0.0",
+  "description": "TypeScript client library for the Mautriz MetaTrader 5 WebSocket API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "script": "npx tsx script.ts",
+    "bench": "npx tsx bench.ts",
+    "prepublishOnly": "tsc",
+    "publish:npm": "tsc && npm publish --access public"
+  },
+  "license": "ISC",
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^25.5.2"
+  },
+  "dependencies": {}
+}