@mfxhub/sdk 0.2.3 → 0.4.0

package/dist/index.d.ts

@@ -18,10 +18,12 @@ export type { Account, Deal, DealPageOptions, DealWindow, PendingOrder, PendingO
 export { Execution, POLL_CAP_MS, POLL_FROM_MS } from "./execution.js";
 export { CLOSE_LIFETIME, CLOSE_REAUTHENTICATE, CLOSE_SLOW_CONSUMER, Channel, ChannelRefused, MfxStream, Resync, StreamClosed, StreamMessage, wsConnector, } from "./stream.js";
 export type { Connector, StreamConnection, StreamEvent, StreamOptions, StreamStats, Timeframe, } from "./stream.js";
-export type { ClosePosition, ClosePositionBy, ClosePositionPartial, Keyed, ModifyOrder, ModifyPosition, OrderType, PlaceOrder, SetTrailingStop, Side, WaitFor, } from "./execution.js";
-export type { CommandState, ExecutionResult, Reason, Tickets } from "./results.js";
+export type { ClosePosition, ClosePositionBy, ClosePositionPartial, Keyed, ModifyOrder, ModifyPosition, OrderType, PlaceOrder, Resource, SetTrailingStop, Side, WaitFor, } from "./execution.js";
+export type { CommandState, ExecutionResult, Reason, Tickets, VenueDeal } from "./results.js";
 export { Terminals, isUsable } from "./terminals.js";
-export type { CreateTerminal, JournalLine, JournalOptions, PageOptions, Redundancy, Terminal, TerminalFilter, TerminalJournal, TerminalState, } from "./terminals.js";
+export type { CreateTerminal, BulkAction, BulkAsk, JournalLine, JournalOptions, PageOptions, Redundancy, Terminal, TerminalFilter, TerminalJournal, TerminalQueue, TerminalState, WaitOptions, } from "./terminals.js";
+export { TradingAccounts } from "./trading-accounts.js";
+export type { AccountEnvironment, AccountState, CtraderGrant, CtraderGrantStarted, GrantScope, StartCtraderGrant, TradingAccount, TradingAccountFilter, TradingAccountPageOptions, TradingSymbol, TradingSymbolList, Venue, } from "./trading-accounts.js";
 export { RequestSigner, SigningKey, signingMessage } from "./signing.js";
 export { KEY_HEADER, NONCE_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER } from "./signing.js";
 export type { components, operations, paths } from "./generated/api.js";

package/dist/index.js

@@ -14,6 +14,7 @@ export { Accounts } from "./accounts.js";
 export { Execution, POLL_CAP_MS, POLL_FROM_MS } from "./execution.js";
 export { CLOSE_LIFETIME, CLOSE_REAUTHENTICATE, CLOSE_SLOW_CONSUMER, Channel, ChannelRefused, MfxStream, Resync, StreamClosed, StreamMessage, wsConnector, } from "./stream.js";
 export { Terminals, isUsable } from "./terminals.js";
+export { TradingAccounts } from "./trading-accounts.js";
 export { RequestSigner, SigningKey, signingMessage } from "./signing.js";
 export { KEY_HEADER, NONCE_HEADER, SIGNATURE_HEADER, TIMESTAMP_HEADER } from "./signing.js";
 export { VERSION } from "./version.js";

package/dist/results.d.ts

@@ -6,13 +6,24 @@ export type CommandState = components["schemas"]["CommandState"];
  * (`transport_error`, `timeout`, `refused`, and `maintenance` when the API refuses outright).
  * A reason the platform adds later arrives in `reasonText` as it was sent, with `reason` null.
  */
-export type Reason = "success" | "requote" | "instrument_disabled" | "no_liquidity" | "market_closed" | "invalid_stops" | "invalid_volume" | "insufficient_funds" | "trade_disabled" | "rejected_other" | "rate_limited" | "expired" | "unknown" | "maintenance" | "transport_error" | "timeout" | "refused";
+export type Reason = "success" | "requote" | "instrument_disabled" | "no_liquidity" | "market_closed" | "invalid_stops" | "invalid_volume" | "insufficient_funds" | "trade_disabled" | "rejected_other" | "rate_limited" | "expired" | "unknown" | "maintenance" | "venue_unavailable" | "not_on_this_venue" | "transport_error" | "timeout" | "refused";
 /** MT5 relates one order, one deal and one position per fill; null where MT5 has none yet. */
 export interface Tickets {
     readonly order: number | null;
     readonly deal: number | null;
     readonly position: number | null;
 }
+/**
+ * One deal a command made, as the venue reported it (cTrader): two for an emulated close-by, one
+ * for an order filled at once. `volumeUnits` is in units of the instrument, not lots.
+ */
+export interface VenueDeal {
+    readonly deal: number;
+    readonly order: number | null;
+    readonly position: number | null;
+    readonly volumeUnits: string | null;
+    readonly price: string | null;
+}
 /**
  * The whole answer to one execution call. Never thrown, always returned.
  *
@@ -60,6 +71,21 @@ export interface ExecutionResult {
     readonly detail: string | null;
     /** When sending it again can work: a maintenance window's end, where the platform said. */
     readonly retryAt: Date | null;
+    /** The venue that answered, `mt5` or `ctrader`; null until there is a result. */
+    readonly venue: string | null;
+    /**
+     * The venue's own code for a refusal, verbatim, beside `reason` (cTrader: such as
+     * NOT_ENOUGH_MONEY). Null on MT5, whose code is `mt5Retcode`.
+     */
+    readonly venueCode: string | null;
+    /** Every deal the command made, in order (cTrader). Empty on MT5, where `tickets.deal` is it. */
+    readonly deals: readonly VenueDeal[];
+    /** The volume filled in units of the instrument; `execVolume` stays in lots. Null on MT5. */
+    readonly volumeUnits: string | null;
+    /** A close-by the venue has no equivalent for, done as two closes (cTrader). */
+    readonly closeByEmulated: boolean;
+    /** A market order filled but its stop loss or take profit could not be set: it is open without. */
+    readonly protectionNotSet: boolean;
 }
 /** A result from a Command or a CommandAccepted body, whichever the call answered with. */
 export declare function fromCommand(body: unknown, idempotencyKey: string, clientRttMs: number): ExecutionResult;

package/dist/results.js

@@ -40,10 +40,31 @@ const REASONS = new Set([
     "expired",
     "unknown",
     "maintenance",
+    "venue_unavailable",
+    "not_on_this_venue",
     "transport_error",
     "timeout",
     "refused",
 ]);
+function deals(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        const one = record(item);
+        const deal = int(one.deal);
+        if (deal === null)
+            continue;
+        out.push({
+            deal,
+            order: int(one.order),
+            position: int(one.position),
+            volumeUnits: decimalOut(one.volume_units),
+            price: decimalOut(one.price),
+        });
+    }
+    return out;
+}
 function int(value) {
     return typeof value === "number" && Number.isInteger(value) ? value : null;
 }
@@ -95,6 +116,12 @@ export function fromCommand(body, idempotencyKey, clientRttMs) {
         reroutedFrom: text(result.rerouted_from),
         detail: null,
         retryAt: null,
+        venue: text(result.venue),
+        venueCode: text(result.venue_code),
+        deals: deals(result.deals),
+        volumeUnits: decimalOut(result.volume_units),
+        closeByEmulated: result.close_by_emulated === true,
+        protectionNotSet: result.protection_not_set === true,
     };
 }
 /**

package/dist/terminals.d.ts

@@ -52,9 +52,31 @@ export interface PageOptions extends TerminalFilter {
 /**
  * Can this terminal be used right now: market data, execution, account reads? True only in ACTIVE.
  * OFFLINE means its cell is not reporting; the platform brings it back by itself, so retry rather
- * than create another.
+ * than create another. QUEUED means it is placed and waiting for its turn to start: its cell
+ * starts terminals a few at a time, and `queue.expected_start_at` says when to expect it.
  */
 export declare function isUsable(terminal: Pick<Terminal, "state">): boolean;
+/** Where a QUEUED terminal waits: its place, its expected start and why it waits. */
+export type TerminalQueue = components["schemas"]["TerminalQueue"];
+/** A bulk restart or retire: what was taken, what was refused, and its expected finish. */
+export type BulkAction = components["schemas"]["BulkAction"];
+/** What {@link Terminals.waitUntilActive} takes. */
+export interface WaitOptions {
+    /** How long to wait in all, in milliseconds. 15 minutes unless given. */
+    readonly timeoutMs?: number;
+}
+/** Which of your terminals a bulk action takes, and why. At least one filter. */
+export interface BulkAsk {
+    /** Why; written to the audit log and to each item. */
+    readonly reason: string;
+    /** Required: the same key sent again returns the same action. */
+    readonly idempotencyKey: string;
+    readonly farmId?: string;
+    readonly brokerId?: string;
+    readonly terminalIds?: readonly string[];
+    /** Without it, a terminal with open positions is refused and the rest are taken. */
+    readonly confirmOpenPositions?: boolean;
+}
 /** Provision and inspect the terminals this key's tenant owns. */
 export declare class Terminals {
     #private;
@@ -79,5 +101,30 @@ export declare class Terminals {
      * Sent once and never retried: if the answer is lost, send the same idempotency key again.
      */
     create(request: CreateTerminal): Promise<Terminal>;
+    /**
+     * Read the terminal until it is no longer on its way to ACTIVE (REQUESTED, QUEUED, PROVISIONING,
+     * LOGGING_IN), or until `timeoutMs` has been waited. Returns the last read either way: ACTIVE,
+     * a state it settled in instead (FAILED, for one), or still on its way when the time ran out.
+     *
+     * A QUEUED terminal is read again at its `queue.expected_start_at` (between 2 s and a minute
+     * away), not on a fixed beat: its cell starts terminals a few at a time, so asking every two
+     * seconds tells nothing new. Any other state is read again after 2 s, doubling to 15 s.
+     */
+    waitUntilActive(terminalId: string, options?: WaitOptions): Promise<Terminal>;
+    /**
+     * Restart many of your terminals at once. Each is judged by the rules of a single restart; a
+     * refused one is listed in `refused` with its rule's code and the rest are taken. Each cell
+     * carries its share at its own pace, so the terminals already running on it are not slowed.
+     * Answered at once with the action and its expected finish; its items never expire.
+     */
+    bulkRestart(ask: BulkAsk): Promise<BulkAction>;
+    /** Retire many of your terminals at once, as {@link bulkRestart} restarts them. */
+    bulkRetire(ask: BulkAsk): Promise<BulkAction>;
+    /** A bulk action's progress: counts per state, what was refused, and its expected finish. */
+    getBulkAction(bulkActionId: string): Promise<BulkAction>;
+    /** Cancel a bulk action: its waiting items are cancelled, running ones finish. */
+    cancelBulkAction(bulkActionId: string, options: {
+        readonly idempotencyKey: string;
+    }): Promise<BulkAction>;
 }
 export {};

package/dist/terminals.js

@@ -39,11 +39,53 @@ function stateQuery(state) {
 /**
  * Can this terminal be used right now: market data, execution, account reads? True only in ACTIVE.
  * OFFLINE means its cell is not reporting; the platform brings it back by itself, so retry rather
- * than create another.
+ * than create another. QUEUED means it is placed and waiting for its turn to start: its cell
+ * starts terminals a few at a time, and `queue.expected_start_at` says when to expect it.
  */
 export function isUsable(terminal) {
     return terminal.state === "ACTIVE";
 }
+/** The states a terminal passes through on its way to ACTIVE; every other state is settled. */
+const ON_ITS_WAY = new Set([
+    "REQUESTED",
+    "QUEUED",
+    "PROVISIONING",
+    "LOGGING_IN",
+]);
+const POLL_FROM_MS = 2_000;
+const POLL_CAP_MS = 15_000;
+/** A QUEUED terminal is read again at its expected start, but never less often than this. */
+const QUEUED_CAP_MS = 60_000;
+function bulkBody(ask) {
+    if (typeof ask.reason !== "string" || ask.reason.trim() === "" || ask.reason.length > 500) {
+        throw new RangeError("reason is 1 to 500 characters");
+    }
+    if (ask.farmId === undefined && ask.brokerId === undefined && ask.terminalIds === undefined) {
+        throw new RangeError("a bulk action names farmId, brokerId or terminalIds");
+    }
+    if (ask.terminalIds !== undefined && ask.terminalIds.length > 1000) {
+        throw new RangeError("terminalIds is at most 1000");
+    }
+    return {
+        reason: ask.reason,
+        confirm_open_positions: ask.confirmOpenPositions ?? false,
+        ...(ask.farmId === undefined ? {} : { farm_id: uuid("farmId", ask.farmId) }),
+        ...(ask.brokerId === undefined ? {} : { broker_id: uuid("brokerId", ask.brokerId) }),
+        ...(ask.terminalIds === undefined
+            ? {}
+            : { terminal_ids: ask.terminalIds.map((id) => uuid("terminalIds", id)) }),
+    };
+}
+/** How long to wait before the next read of a terminal still on its way. */
+function nextWaitMs(terminal, backoffMs, nowMs) {
+    const expected = terminal.state === "QUEUED" ? terminal.queue?.expected_start_at : undefined;
+    if (typeof expected === "string") {
+        const until = Date.parse(expected) - nowMs;
+        if (Number.isFinite(until))
+            return Math.min(Math.max(until, POLL_FROM_MS), QUEUED_CAP_MS);
+    }
+    return Math.min(backoffMs, POLL_CAP_MS);
+}
 /** Provision and inspect the terminals this key's tenant owns. */
 export class Terminals {
     #client;
@@ -129,4 +171,67 @@ export class Terminals {
             idempotencyKey: key,
         }));
     }
+    /**
+     * Read the terminal until it is no longer on its way to ACTIVE (REQUESTED, QUEUED, PROVISIONING,
+     * LOGGING_IN), or until `timeoutMs` has been waited. Returns the last read either way: ACTIVE,
+     * a state it settled in instead (FAILED, for one), or still on its way when the time ran out.
+     *
+     * A QUEUED terminal is read again at its `queue.expected_start_at` (between 2 s and a minute
+     * away), not on a fixed beat: its cell starts terminals a few at a time, so asking every two
+     * seconds tells nothing new. Any other state is read again after 2 s, doubling to 15 s.
+     */
+    async waitUntilActive(terminalId, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 15 * 60_000;
+        if (typeof timeoutMs !== "number" || !(timeoutMs >= 0)) {
+            throw new RangeError("timeoutMs is 0 or more");
+        }
+        let waited = 0;
+        let backoff = POLL_FROM_MS;
+        let terminal = await this.get(terminalId);
+        while (ON_ITS_WAY.has(terminal.state) && waited < timeoutMs) {
+            const ms = Math.min(nextWaitMs(terminal, backoff, Date.now()), timeoutMs - waited);
+            await this.#client.pause(ms);
+            waited += ms;
+            backoff *= 2;
+            terminal = await this.get(terminalId);
+        }
+        return terminal;
+    }
+    /**
+     * Restart many of your terminals at once. Each is judged by the rules of a single restart; a
+     * refused one is listed in `refused` with its rule's code and the rest are taken. Each cell
+     * carries its share at its own pace, so the terminals already running on it are not slowed.
+     * Answered at once with the action and its expected finish; its items never expire.
+     */
+    async bulkRestart(ask) {
+        return this.#bulk("/terminals:restart", ask);
+    }
+    /** Retire many of your terminals at once, as {@link bulkRestart} restarts them. */
+    async bulkRetire(ask) {
+        return this.#bulk("/terminals:retire", ask);
+    }
+    /** A bulk action's progress: counts per state, what was refused, and its expected finish. */
+    async getBulkAction(bulkActionId) {
+        const id = uuid("bulkActionId", bulkActionId);
+        return (await this.#client.read({ method: "GET", path: `/bulk-actions/${id}` }));
+    }
+    /** Cancel a bulk action: its waiting items are cancelled, running ones finish. */
+    async cancelBulkAction(bulkActionId, options) {
+        const id = uuid("bulkActionId", bulkActionId);
+        return (await this.#client.write({
+            method: "POST",
+            path: `/bulk-actions/${id}/cancel`,
+            idempotencyKey: idempotencyKey(options.idempotencyKey),
+        }));
+    }
+    async #bulk(path, ask) {
+        const key = idempotencyKey(ask.idempotencyKey);
+        const body = bulkBody(ask);
+        return (await this.#client.write({
+            method: "POST",
+            path,
+            body,
+            idempotencyKey: key,
+        }));
+    }
 }

package/dist/trading-accounts.d.ts

@@ -0,0 +1,130 @@
+import { type Account, type Deal, type DealPageOptions, type DealWindow, type PendingOrderList, type PositionList } from "./accounts.js";
+import type { MfxClient } from "./client.js";
+import { type ClosePosition, type ClosePositionBy, type ClosePositionPartial, type Keyed, type ModifyOrder, type ModifyPosition, type PlaceOrder, type SetTrailingStop } from "./execution.js";
+import type { components } from "./generated/api.js";
+import { type Page } from "./pages.js";
+import type { ExecutionResult } from "./results.js";
+/** One trading account at one venue, as the API describes it. */
+export type TradingAccount = components["schemas"]["TradingAccount"];
+/** The trading technology an account is on. */
+export type Venue = TradingAccount["venue"];
+/** An account's state, in words that hold on every venue. */
+export type AccountState = TradingAccount["state"];
+/** Live or demo. */
+export type AccountEnvironment = NonNullable<TradingAccount["environment"]>;
+/** The symbols one cTrader account can trade, with their volume rules in lots and leverage. */
+export type TradingSymbolList = components["schemas"]["TradingSymbolList"];
+/** One symbol of a cTrader account. */
+export type TradingSymbol = components["schemas"]["TradingSymbol"];
+/** A cTrader grant: its state and, once ACTIVE, the accounts the trader shared. */
+export type CtraderGrant = components["schemas"]["CtraderGrant"];
+/** A started grant: the consent link to send the trader to, and until when it works. */
+export type CtraderGrantStarted = components["schemas"]["CtraderGrantStarted"];
+/** What a grant lets MFX Hub do: `accounts` reads only, `trading` reads and trades. */
+export type GrantScope = components["schemas"]["CtraderGrantCreate"]["scope"];
+/** What {@link TradingAccounts.startCtraderGrant} takes. */
+export interface StartCtraderGrant {
+    /** One grant covers live or demo accounts. */
+    readonly environment: AccountEnvironment;
+    readonly scope: GrantScope;
+    /** Where the trader comes back to, https only, with `grant_id`, `result` and your state. */
+    readonly returnUrl: string;
+    /** Your own value, returned unchanged on the return URL; never read by MFX Hub. */
+    readonly tenantState?: string;
+    readonly idempotencyKey: string;
+}
+/** Narrow the list on the platform, before the page is cut. */
+export interface TradingAccountFilter {
+    /** Only accounts on this venue, or on one of these. */
+    readonly venue?: Venue | readonly Venue[];
+    /** Only live, or only demo, accounts. */
+    readonly environment?: AccountEnvironment;
+    /** Only accounts in this state, or in one of these. */
+    readonly state?: AccountState | readonly AccountState[];
+}
+/** What {@link TradingAccounts.page} takes. */
+export interface TradingAccountPageOptions extends TradingAccountFilter {
+    /** The `nextCursor` of the page before; leave it out for the first page. */
+    readonly cursor?: string;
+    /** How many to a page, 1 to 200. */
+    readonly limit?: number;
+}
+/** Read, trade and connect the trading accounts this key's tenant holds. */
+export declare class TradingAccounts {
+    #private;
+    constructor(client: MfxClient);
+    /**
+     * One trading account, by its own id or by one of its terminals' ids. Another tenant's, or an id
+     * that is not an account of yours, is 404.
+     */
+    get(accountId: string): Promise<TradingAccount>;
+    /** One page of this tenant's trading accounts, newest first. One request. */
+    page(options?: TradingAccountPageOptions): Promise<Page<TradingAccount>>;
+    /**
+     * Every trading account, following the cursor, one request a page. There is no total. The
+     * filters narrow the list on the platform, so a filtered page is never short for being filtered.
+     */
+    list(options?: Omit<TradingAccountPageOptions, "cursor">): AsyncGenerator<TradingAccount, void, undefined>;
+    /**
+     * Balance, equity, margin and profile, answered by the account's lead runner. On cTrader the
+     * equity is computed by the platform (the venue sends none); `stale` says when it could not be.
+     */
+    funds(accountId: string): Promise<Account>;
+    /** Every open position, as one snapshot. On cTrader `volume` is in lots. */
+    positions(accountId: string): Promise<PositionList>;
+    /** Every pending order, as one snapshot. */
+    pendingOrders(accountId: string): Promise<PendingOrderList>;
+    /**
+     * One page of deals inside a window of at most 31 days, newest first, optionally of one
+     * position. On cTrader every time is UTC and `magic` is the order's origin marker.
+     */
+    dealsPage(accountId: string, options: DealPageOptions): Promise<Page<Deal>>;
+    /** Every deal inside the window, following the cursor, one request a page. */
+    deals(accountId: string, window: DealWindow): AsyncGenerator<Deal, void, undefined>;
+    /**
+     * The symbols a cTrader account can trade: a volume a command sends must be a whole
+     * `volume_step` between `volume_min` and `volume_max`, in lots. An MT5 account is refused.
+     */
+    symbols(accountId: string): Promise<TradingSymbolList>;
+    /**
+     * Place a market or pending order on the account. `volume` is in lots on every venue, and on
+     * cTrader a whole step of the symbol (`symbols`). On cTrader `magic` stays on the order as its
+     * label, and a market order's stops are set just after the fill (`protectionNotSet` says when
+     * that failed).
+     */
+    placeOrder(accountId: string, order: PlaceOrder): Promise<ExecutionResult>;
+    /** Amend a pending order's price, stops or expiry. */
+    modifyOrder(accountId: string, ticket: number, change: ModifyOrder): Promise<ExecutionResult>;
+    /** Cancel a pending order. */
+    cancelOrder(accountId: string, ticket: number, options: Keyed): Promise<ExecutionResult>;
+    /** Move a position's stop loss, take profit, or both. */
+    modifyPosition(accountId: string, ticket: number, change: ModifyPosition): Promise<ExecutionResult>;
+    /** Close a position in full. */
+    closePosition(accountId: string, ticket: number, options: ClosePosition): Promise<ExecutionResult>;
+    /** Close part of a position, in lots. */
+    closePositionPartial(accountId: string, ticket: number, options: ClosePositionPartial): Promise<ExecutionResult>;
+    /**
+     * Close a position against an opposite one. cTrader has no close-by: it is done as two closes,
+     * the result says `closeByEmulated` and `deals` holds both.
+     */
+    closePositionBy(accountId: string, ticket: number, options: ClosePositionBy): Promise<ExecutionResult>;
+    /** Trail a position's stop loss. A venue without a trailing stop refuses it, as a result. */
+    setTrailingStop(accountId: string, ticket: number, options: SetTrailingStop): Promise<ExecutionResult>;
+    /** Remove a position's trailing stop. */
+    clearTrailingStop(accountId: string, ticket: number, options: Keyed): Promise<ExecutionResult>;
+    /**
+     * Start connecting a trader's cTrader accounts; resolves to the consent link to send them to.
+     * They sign in at cTrader (MFX Hub never sees the password), choose the accounts to share and
+     * come back to `returnUrl`. The link lives 15 minutes. A plan without cTrader is forbidden.
+     */
+    startCtraderGrant(grant: StartCtraderGrant): Promise<CtraderGrantStarted>;
+    /** One grant: PENDING, ACTIVE, REVOKED or EXPIRED, and once ACTIVE the accounts shared. */
+    ctraderGrant(grantId: string): Promise<CtraderGrant>;
+    /**
+     * Make some of an ACTIVE grant's accounts trading accounts of yours, by cTrader's ids (1 to
+     * 50). Each starts PENDING and is CONNECTED once authorised at cTrader.
+     */
+    connectCtraderAccounts(grantId: string, ctidTraderAccountIds: readonly (string | number)[], options: Keyed): Promise<TradingAccount[]>;
+    /** Revoke a grant: its accounts move to REAUTH_NEEDED; a new grant reconnects them. */
+    revokeCtraderGrant(grantId: string, options: Keyed): Promise<CtraderGrant>;
+}

package/dist/trading-accounts.js

@@ -0,0 +1,228 @@
+// `client.tradingAccounts`: the tenant's trading accounts over every venue.
+//
+// One trading account is one account at one venue: an MT5 account (run by one terminal, or two with
+// HA), and a cTrader account. An MT5 account takes its first terminal's id, and `get` also takes
+// any of its terminals' ids. Its state is the venue-neutral word (CONNECTED, DEGRADED,
+// REAUTH_NEEDED, ...); `client.terminals.get` has the MT5 detail.
+//
+// The same object trades an account and reads it on any venue: the nine commands of
+// `client.execution` keyed on the account (`exec:write`), and its funds, positions, pending orders,
+// deals and symbols (`acct:read`). The platform hands each to the account's lead runner. A cTrader
+// account is connected through a grant: `startCtraderGrant` answers the consent link to send the
+// trader to, `ctraderGrant` lists the accounts they shared, and `connectCtraderAccounts` makes the
+// chosen ones trading accounts of yours (`term:write`).
+//
+// DECISION: a namespace of its own beside `client.accounts`, which stays what it was: the balance,
+// positions and deals of a terminal's account. Folding the two together would give `accounts.get`
+// two meanings.
+import { Accounts, } from "./accounts.js";
+import { idempotencyKey, limit as pageLimit, uuid } from "./arguments.js";
+import { Execution, } from "./execution.js";
+import { everyItem, pageOf } from "./pages.js";
+function joined(name, value) {
+    if (value === undefined)
+        return undefined;
+    const words = typeof value === "string" ? [value] : value;
+    if (words.length === 0)
+        throw new RangeError(`${name} is one or more values; got none`);
+    for (const word of words) {
+        if (typeof word !== "string" || word === "")
+            throw new TypeError(`${name} is a list of words`);
+    }
+    return words.join(",");
+}
+/** Read, trade and connect the trading accounts this key's tenant holds. */
+export class TradingAccounts {
+    #client;
+    #orders;
+    #reads;
+    constructor(client) {
+        this.#client = client;
+        this.#orders = new Execution(client, "accounts");
+        this.#reads = new Accounts(client, "accounts");
+    }
+    /**
+     * One trading account, by its own id or by one of its terminals' ids. Another tenant's, or an id
+     * that is not an account of yours, is 404.
+     */
+    async get(accountId) {
+        const id = uuid("accountId", accountId);
+        return (await this.#client.read({ method: "GET", path: `/accounts/${id}` }));
+    }
+    /** One page of this tenant's trading accounts, newest first. One request. */
+    async page(options = {}) {
+        const limit = pageLimit(options.limit);
+        if (options.cursor !== undefined && typeof options.cursor !== "string") {
+            throw new TypeError("cursor is the nextCursor of the page before");
+        }
+        if (options.environment !== undefined && typeof options.environment !== "string") {
+            throw new TypeError("environment is live or demo");
+        }
+        const body = await this.#client.read({
+            method: "GET",
+            path: "/accounts",
+            query: {
+                cursor: options.cursor,
+                limit,
+                venue: joined("venue", options.venue),
+                environment: options.environment,
+                state: joined("state", options.state),
+            },
+        });
+        return pageOf(body);
+    }
+    /**
+     * Every trading account, following the cursor, one request a page. There is no total. The
+     * filters narrow the list on the platform, so a filtered page is never short for being filtered.
+     */
+    list(options = {}) {
+        const limit = pageLimit(options.limit);
+        const rest = {
+            ...(limit === undefined ? {} : { limit }),
+            ...(options.venue === undefined ? {} : { venue: options.venue }),
+            ...(options.environment === undefined ? {} : { environment: options.environment }),
+            ...(options.state === undefined ? {} : { state: options.state }),
+        };
+        return everyItem((cursor) => this.page({ ...rest, ...(cursor === undefined ? {} : { cursor }) }));
+    }
+    // ------------------------------------------------------------------------------------- reads
+    /**
+     * Balance, equity, margin and profile, answered by the account's lead runner. On cTrader the
+     * equity is computed by the platform (the venue sends none); `stale` says when it could not be.
+     */
+    async funds(accountId) {
+        return this.#reads.account(accountId);
+    }
+    /** Every open position, as one snapshot. On cTrader `volume` is in lots. */
+    async positions(accountId) {
+        return this.#reads.positions(accountId);
+    }
+    /** Every pending order, as one snapshot. */
+    async pendingOrders(accountId) {
+        return this.#reads.pendingOrders(accountId);
+    }
+    /**
+     * One page of deals inside a window of at most 31 days, newest first, optionally of one
+     * position. On cTrader every time is UTC and `magic` is the order's origin marker.
+     */
+    async dealsPage(accountId, options) {
+        return this.#reads.dealsPage(accountId, options);
+    }
+    /** Every deal inside the window, following the cursor, one request a page. */
+    deals(accountId, window) {
+        return this.#reads.deals(accountId, window);
+    }
+    /**
+     * The symbols a cTrader account can trade: a volume a command sends must be a whole
+     * `volume_step` between `volume_min` and `volume_max`, in lots. An MT5 account is refused.
+     */
+    async symbols(accountId) {
+        const id = uuid("accountId", accountId);
+        const path = `/accounts/${id}/symbols`;
+        return (await this.#client.read({ method: "GET", path }));
+    }
+    // ---------------------------------------------------------------------------------- commands
+    // The same bodies and rules as `client.execution`, sent to /accounts/{id}/...: each resolves to
+    // a result and never rejects. Read the outcome with `client.execution.waitFor`.
+    /**
+     * Place a market or pending order on the account. `volume` is in lots on every venue, and on
+     * cTrader a whole step of the symbol (`symbols`). On cTrader `magic` stays on the order as its
+     * label, and a market order's stops are set just after the fill (`protectionNotSet` says when
+     * that failed).
+     */
+    async placeOrder(accountId, order) {
+        return this.#orders.placeOrder(accountId, order);
+    }
+    /** Amend a pending order's price, stops or expiry. */
+    async modifyOrder(accountId, ticket, change) {
+        return this.#orders.modifyOrder(accountId, ticket, change);
+    }
+    /** Cancel a pending order. */
+    async cancelOrder(accountId, ticket, options) {
+        return this.#orders.cancelOrder(accountId, ticket, options);
+    }
+    /** Move a position's stop loss, take profit, or both. */
+    async modifyPosition(accountId, ticket, change) {
+        return this.#orders.modifyPosition(accountId, ticket, change);
+    }
+    /** Close a position in full. */
+    async closePosition(accountId, ticket, options) {
+        return this.#orders.closePosition(accountId, ticket, options);
+    }
+    /** Close part of a position, in lots. */
+    async closePositionPartial(accountId, ticket, options) {
+        return this.#orders.closePositionPartial(accountId, ticket, options);
+    }
+    /**
+     * Close a position against an opposite one. cTrader has no close-by: it is done as two closes,
+     * the result says `closeByEmulated` and `deals` holds both.
+     */
+    async closePositionBy(accountId, ticket, options) {
+        return this.#orders.closePositionBy(accountId, ticket, options);
+    }
+    /** Trail a position's stop loss. A venue without a trailing stop refuses it, as a result. */
+    async setTrailingStop(accountId, ticket, options) {
+        return this.#orders.setTrailingStop(accountId, ticket, options);
+    }
+    /** Remove a position's trailing stop. */
+    async clearTrailingStop(accountId, ticket, options) {
+        return this.#orders.clearTrailingStop(accountId, ticket, options);
+    }
+    // ----------------------------------------------------------------------------- cTrader grants
+    /**
+     * Start connecting a trader's cTrader accounts; resolves to the consent link to send them to.
+     * They sign in at cTrader (MFX Hub never sees the password), choose the accounts to share and
+     * come back to `returnUrl`. The link lives 15 minutes. A plan without cTrader is forbidden.
+     */
+    async startCtraderGrant(grant) {
+        const key = idempotencyKey(grant.idempotencyKey);
+        if (typeof grant.returnUrl !== "string" || !grant.returnUrl.startsWith("https://")) {
+            throw new TypeError("returnUrl is an https:// URL");
+        }
+        const body = {
+            environment: grant.environment,
+            scope: grant.scope,
+            return_url: grant.returnUrl,
+            ...(grant.tenantState === undefined ? {} : { tenant_state: grant.tenantState }),
+        };
+        return (await this.#client.write({
+            method: "POST",
+            path: "/accounts/ctrader/grants",
+            body,
+            idempotencyKey: key,
+        }));
+    }
+    /** One grant: PENDING, ACTIVE, REVOKED or EXPIRED, and once ACTIVE the accounts shared. */
+    async ctraderGrant(grantId) {
+        const id = uuid("grantId", grantId);
+        const path = `/accounts/ctrader/grants/${id}`;
+        return (await this.#client.read({ method: "GET", path }));
+    }
+    /**
+     * Make some of an ACTIVE grant's accounts trading accounts of yours, by cTrader's ids (1 to
+     * 50). Each starts PENDING and is CONNECTED once authorised at cTrader.
+     */
+    async connectCtraderAccounts(grantId, ctidTraderAccountIds, options) {
+        const id = uuid("grantId", grantId);
+        const key = idempotencyKey(options.idempotencyKey);
+        const ids = ctidTraderAccountIds.map(String);
+        if (ids.length === 0)
+            throw new RangeError("connect at least one account");
+        const body = (await this.#client.write({
+            method: "POST",
+            path: `/accounts/ctrader/grants/${id}/accounts`,
+            body: { ctid_trader_account_ids: ids },
+            idempotencyKey: key,
+        }));
+        return body.items;
+    }
+    /** Revoke a grant: its accounts move to REAUTH_NEEDED; a new grant reconnects them. */
+    async revokeCtraderGrant(grantId, options) {
+        const id = uuid("grantId", grantId);
+        return (await this.#client.write({
+            method: "DELETE",
+            path: `/accounts/ctrader/grants/${id}`,
+            idempotencyKey: idempotencyKey(options.idempotencyKey),
+        }));
+    }
+}