@mfxhub/sdk 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -18,12 +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, 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, TradingAccount, TradingAccountFilter, TradingAccountPageOptions, Venue, } 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/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/trading-accounts.d.ts

@@ -1,6 +1,9 @@
+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. */
@@ -9,6 +12,27 @@ export type Venue = TradingAccount["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. */
@@ -25,7 +49,7 @@ export interface TradingAccountPageOptions extends TradingAccountFilter {
     /** How many to a page, 1 to 200. */
     readonly limit?: number;
 }
-/** Read the trading accounts this key's tenant holds. Needs `acct:read`. */
+/** Read, trade and connect the trading accounts this key's tenant holds. */
 export declare class TradingAccounts {
     #private;
     constructor(client: MfxClient);
@@ -41,4 +65,66 @@ export declare class TradingAccounts {
      * 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

@@ -1,15 +1,23 @@
 // `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 from the cTrader release a cTrader account. An MT5 account's id is its terminal's id, so
-// an id you already hold reads its account, and `get` also takes either HA terminal's id. Its state
-// is the venue-neutral word (CONNECTED, DEGRADED, REAUTH_NEEDED, ...); `client.terminals.get` has
-// the MT5 detail.
+// 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 { limit as pageLimit, uuid } from "./arguments.js";
+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)
@@ -23,11 +31,15 @@ function joined(name, value) {
     }
     return words.join(",");
 }
-/** Read the trading accounts this key's tenant holds. Needs `acct:read`. */
+/** 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
@@ -73,4 +85,144 @@ export class TradingAccounts {
         };
         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),
+        }));
+    }
 }

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This package's version. */
-export declare const VERSION = "0.3.0";
+export declare const VERSION = "0.4.0";
 /** What every request says it is, as a product token: the SDK's language and its version. */
-export declare const USER_AGENT = "mfx-sdk-typescript/0.3.0";
+export declare const USER_AGENT = "mfx-sdk-typescript/0.4.0";

package/dist/version.js

@@ -1,5 +1,5 @@
 // This package's version, in one place: exported by the package, and named by every request.
 /** This package's version. */
-export const VERSION = "0.3.0";
+export const VERSION = "0.4.0";
 /** What every request says it is, as a product token: the SDK's language and its version. */
 export const USER_AGENT = `mfx-sdk-typescript/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfxhub/sdk",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Typed TypeScript client for the MFX Hub API: hosted trading terminals, market data, execution and a live event stream",
   "license": "Apache-2.0",
   "type": "module",