Place MetaTrader 5 orders from Node.js and TypeScript — no MetaTrader installed

mkdir mt5-trade && cd mt5-trade
npm init -y && npm pkg set type=module
npm install --save-dev typescript @types/node   # only for type checking

export FXAPIS_KEY="fx_test_…"          # your API key
export MT5_LOGIN="26177561"
export MT5_SERVER="VantageMarkets-Demo"
export MT5_PASSWORD="…"                # the trading password
export MT5_SYMBOL="EURUSD"             # as your broker names it

// Connect an MT5 account through fxapis, open a small trade, and close it.
// Run it against a broker DEMO account. Every fxapis key reaches a real broker.
import { randomUUID } from "node:crypto";
import { setTimeout as sleep } from "node:timers/promises";

const API = process.env.FXAPIS_API ?? "https://api.fxapis.com";
const KEY = required("FXAPIS_KEY");
const NEEDS_ATTENTION = new Set(["invalid_credentials", "trading_disabled", "needs_2fa", "needs_certificate"]);
// Codes that mean "nothing was placed yet — ask again with the SAME key".
const RETRY_SAME_KEY = new Set(["SEND_FAILED", "IDEMPOTENCY_IN_FLIGHT", "ACCOUNT_NOT_READY", "NO_RUNTIME", "RATE_LIMITED"]);

type Account = { id: string; login: string; server: string; state: string };
type Status = { id: string; state: string; detail: string | null };
type Order = {
  id: string;
  state: string;
  symbol: string;
  filledPrice: string | null;
  brokerPositionId: string | null;
};
type Position = {
  brokerPositionId: string;
  symbol: string;
  side: "buy" | "sell";
  volume: string | null;
  openPrice: string | null;
  profit: string | null;
  observedAt: string;
};
type ApiErrorBody = { code: string; message: string; details?: Array<Record<string, unknown>> };

class ApiError extends Error {
  status: number;
  code: string;
  details: Array<Record<string, unknown>>;
  constructor(status: number, body: ApiErrorBody) {
    super(`${status} ${body.code}: ${body.message}`);
    this.status = status;
    this.code = body.code;
    this.details = body.details ?? [];
  }
}

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}

async function call(method: string, path: string, body?: unknown, headers: Record<string, string> = {}, timeoutMs = 30_000) {
  // Content-Type only with a body.
  const json: Record<string, string> = body === undefined ? {} : { "Content-Type": "application/json" };
  return fetch(`${API}${path}`, {
    method,
    headers: { Authorization: `Bearer ${KEY}`, ...json, ...headers },
    body: body === undefined ? undefined : JSON.stringify(body),
    signal: AbortSignal.timeout(timeoutMs),
  });
}

/** The error object of a failed response, or null if the body is not ours (a proxy page). */
async function errorOf(response: Response): Promise<ApiErrorBody | null> {
  try {
    const parsed = (await response.json()) as { error?: ApiErrorBody };
    return parsed.error ?? null;
  } catch {
    return null;
  }
}

async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
  const response = await call(method, path, body);
  if (!response.ok) {
    const error = await errorOf(response);
    throw new ApiError(response.status, error ?? { code: "HTTP_ERROR", message: response.statusText });
  }
  return ((await response.json()) as { data: T }).data;
}

/** Stores the account at fxapis. It does not log in yet. */
async function connectAccount(login: string, server: string, password: string): Promise<Account> {
  try {
    return await request<Account>("POST", "/v1/accounts", {
      login,
      server,
      password,
      mode: "warm_on_demand",
      label: "node-guide",
    });
  } catch (error) {
    if (!(error instanceof ApiError) || error.code !== "ACCOUNT_EXISTS") throw error;
    // Connected on an earlier run: find it instead of connecting it twice.
    const accounts = await request<Account[]>("GET", "/v1/accounts");
    const existing = accounts.find((a) => a.login === login && a.server === server);
    if (!existing) throw error;
    return existing;
  }
}

/** Starts the broker login, then polls until the account is ready to trade. */
async function bringOnline(accountId: string, timeoutMs = 120_000): Promise<Status> {
  await request("POST", `/v1/accounts/${accountId}/warm`); // 409 NEEDS_OPERATOR / NO_SECRET throws
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const status = await request<Status>("GET", `/v1/accounts/${accountId}/status`);
    if (status.state === "ready") return status;
    if (NEEDS_ATTENTION.has(status.state)) {
      // Not retryable. Repeated failed logins are how brokers lock accounts.
      throw new Error(`account needs attention: ${status.state} (${status.detail})`);
    }
    await sleep(2_000);
  }
  throw new Error(`account not ready after ${timeoutMs / 1000}s`);
}

/** After ORDER_UNRESOLVED: never resend. Poll the order until the broker's record settles it. */
async function waitForOutcome(orderId: string, timeoutMs = 300_000): Promise<Order> {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const order = await request<Order>("GET", `/v1/orders/${orderId}`);
    if (order.state !== "unknown") return order;
    await sleep(5_000);
  }
  throw new Error(`order ${orderId} is still unknown. Do not resend it; check it again later.`);
}

/** Places an order (or a close) exactly once, however many times the request is retried. */
async function sendOrder(path: string, body: Record<string, unknown>, attempts = 6): Promise<Order> {
  const key = randomUUID(); // one key per order, reused on every retry
  for (let attempt = 0; attempt < attempts; attempt++) {
    const backoff = Math.min(2 ** attempt, 10) * 1000;
    let response: Response;
    try {
      response = await call("POST", path, body, { "Idempotency-Key": key }, 90_000);
    } catch {
      await sleep(backoff); // we never saw the answer; the same key makes asking again safe
      continue;
    }

    if (response.status === 201) return ((await response.json()) as { data: Order }).data;

    const error = await errorOf(response);
    if (!error && response.status >= 500) {
      await sleep(backoff); // not our error body: a gateway hiccup
      continue;
    }
    if (!error) throw new ApiError(response.status, { code: "HTTP_ERROR", message: response.statusText });

    if (error.code === "ORDER_UNRESOLVED") {
      return waitForOutcome(String(error.details?.[0]?.orderId));
    }
    if (RETRY_SAME_KEY.has(error.code)) {
      const retryAfter = Number(response.headers.get("retry-after") ?? 0) * 1000;
      await sleep(retryAfter || backoff);
      continue;
    }
    throw new ApiError(response.status, error); // ORDER_REJECTED, INVALID_REQUEST, QUOTA_EXCEEDED, …
  }
  throw new Error(`gave up after ${attempts} attempts; retrying later with key ${key} is still safe`);
}

async function main(): Promise<number> {
  const login = required("MT5_LOGIN");
  const server = required("MT5_SERVER");
  const symbol = process.env.MT5_SYMBOL ?? "EURUSD";

  const account = await connectAccount(login, server, required("MT5_PASSWORD"));
  console.log(`account ${account.id} (${account.state})`);

  await bringOnline(account.id);
  console.log("online");

  let order: Order;
  try {
    order = await sendOrder(`/v1/accounts/${account.id}/orders/market`, { symbol, side: "buy", volume: "0.01" });
  } catch (error) {
    if (error instanceof ApiError && error.code === "ORDER_REJECTED") {
      console.log(`rejected by the broker: ${error.message}`);
      return 1;
    }
    throw error;
  }
  console.log(`order ${order.id}: ${order.state} at ${order.filledPrice}`);
  if (order.state !== "filled" && order.state !== "partially_filled") return 1;

  // Positions refresh on their own about every 15 s; reconcile (optional) refreshes them now.
  await request("POST", `/v1/accounts/${account.id}/reconcile`);
  const positions = await request<Position[]>("GET", `/v1/accounts/${account.id}/positions`);
  for (const p of positions) {
    console.log(`  #${p.brokerPositionId} ${p.side} ${p.volume} ${p.symbol} @ ${p.openPrice} profit ${p.profit} (seen ${p.observedAt})`);
  }

  const close = await sendOrder(`/v1/accounts/${account.id}/positions/${order.brokerPositionId}/close`, {});
  console.log(`closed: ${close.state} at ${close.filledPrice}`);

  // Offline now rather than after the idle window. The stored password is kept.
  await request("POST", `/v1/accounts/${account.id}/cool`);

  if (process.env.FXAPIS_DISCONNECT === "1") {
    // Erases the stored password for good. Only when you are done with this account.
    const result = await request<{ credentialsRemoved: boolean }>("POST", `/v1/accounts/${account.id}/disconnect`);
    console.log(`disconnected, credentials removed: ${result.credentialsRemoved}`);
  }
  return 0;
}

process.exitCode = await main();

account 0d7c1f5e-4b6a-4c1e-9f0a-2d9e8c7b6a51 (created)
online
order b1c7…9e2a: filled at 1.13426
  #2109584418 buy 0.01 EURUSD @ 1.13426 profit -0.07 (seen 2026-09-30T10:14:03.512Z)
closed: filled at 1.13419