@n1xyz/nord-ts 0.1.1 → 0.1.3

package/src/gen/openapi.ts

@@ -84,8 +84,12 @@ export interface paths {
         get: {
             parameters: {
                 query: {
+                    /** @description Start action ID (exclusive) */
                     from: number;
+                    /** @description End action ID (inclusive) */
                     to: number;
+                    /** @description Optionally provided binary version of client, so nord server can ensure all actions provided are executable by client. */
+                    clientVersion?: components["schemas"]["ExecutableVersion"] | null;
                 };
                 header?: never;
                 path?: never;
@@ -109,6 +113,14 @@ export interface paths {
                         "application/json": components["schemas"]["RangeTooLarge"];
                     };
                 };
+                501: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["NotImplemented"];
+                    };
+                };
             };
         };
         put?: never;
@@ -787,7 +799,7 @@ export interface paths {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["TriggerInfo"][] | null;
+                        "application/json": components["schemas"]["AccountTriggerInfo"][] | null;
                     };
                 };
             };
@@ -984,6 +996,79 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/state/download": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description Returns state download link and metadata, as defined by nearest(up to equality) snapshot `time` or `action_id`` or `timestamp`. If not specified, returns latest snapshot. Example: /state/download?actionId=1 /state/download?time&2025-09-22T12:34:56Z /state/download?timestamp&1695380000 - Does not implemented yet. To get the latest snap use: /state/download - w/o any params.
+         *
+         *     The link from responce can be inserted to search bar in browser to download. */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["StateDownloadMeta"];
+                    };
+                };
+                501: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["NotImplemented"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/state/download/{snapshot_id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** @description Typical HTTP file download endpoint. Actually same as provided by S3 storages. Means supports Range header, Content-Length, Content-Type, ETag and so on, and relevant headers. */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    snapshot_id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: never;
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/tv": {
         parameters: {
             query?: never;
@@ -1924,11 +2009,20 @@ export interface components {
             limit: number;
         };
         ActionsQuery: {
-            /** Format: uint64 */
+            /**
+             * Format: uint64
+             * @description Start action ID (exclusive)
+             */
             from: number;
-            /** Format: uint64 */
+            /**
+             * Format: uint64
+             * @description End action ID (inclusive)
+             */
             to: number;
+            /** @description Optionally provided binary version of client, so nord server can ensure all actions provided are executable by client. */
+            clientVersion?: components["schemas"]["ExecutableVersion"] | null;
         };
+        ExecutableVersion: string;
         ActionsItem: {
             /** Format: uint64 */
             actionId: number;
@@ -1941,6 +2035,10 @@ export interface components {
             /** Format: uint16 */
             maximal: number;
         };
+        NotImplemented: {
+            /** @description Human readable message describing what to expect next. */
+            message: string;
+        };
         ActionNotFound: null;
         /** @description Returns fee parts per market per balance change per action per account. Fee is taken from user without return. Please note that some operations need some deposit which will be returned - these are not part of fees. */
         FillRole: "maker" | "taker";
@@ -2271,14 +2369,23 @@ export interface components {
         /** @enum {string} */
         TriggerKind: "stopLoss" | "takeProfit";
         /** @enum {string} */
-        TriggerStatus: "active" | "success" | "cancel" | "fail" | "remove";
-        TriggerInfo: {
+        TriggerStatus: "Active" | "Success" | "Removed" | "Canceled";
+        /** @description Trigger into per account. */
+        AccountTriggerInfo: {
             /** Format: uint32 */
             marketId: number;
+            key: components["schemas"]["TriggerKey"];
+            triggerPrices: components["schemas"]["TriggerPrice"];
+            /** Format: uint64 */
+            actionId: number;
+        };
+        TriggerKey: {
             side: components["schemas"]["Side"];
             kind: components["schemas"]["TriggerKind"];
-            triggerPrice: components["schemas"]["PositivePriceMantissa"];
-            limitPrice?: components["schemas"]["PositivePriceMantissa"] | null;
+        };
+        TriggerPrice: {
+            trigger: components["schemas"]["PositivePriceMantissa"];
+            settlement?: components["schemas"]["PositivePriceMantissa"] | null;
         };
         /**
          * Format: uint64
@@ -2346,6 +2453,29 @@ export interface components {
              */
             pageSize: number | null;
         };
+        DownloadFilter: components["schemas"]["Op_for_DataDateTime"] | components["schemas"]["Op_for_uint64"] | components["schemas"]["Op_for_uint64"] | null;
+        /** @description Parses tag (anycase), and value in round braces using `from_str`. */
+        Op_for_DataDateTime: {
+            le: components["schemas"]["DataDateTime"];
+        };
+        DataDateTime: string;
+        /** @description Parses tag (anycase), and value in round braces using `from_str`. */
+        Op_for_uint64: {
+            /** Format: uint64 */
+            le: number;
+        };
+        StateDownloadMeta: {
+            /** @description Hash of the state file. Used as ETag. */
+            hash: number[];
+            /**
+             * Format: uri
+             * @description Link to download the state file.
+             */
+            link: string;
+            /** @description Version of binary which produced this state snapshot. So can decide whether it is compatible with client. todo(repl): After upgrade release make it non-optional. */
+            version?: components["schemas"]["BinaryId"] | null;
+        };
+        BinaryId: string;
         /** @description TV config query response https://www.tradingview.com/charting-library-docs/latest/connecting_data/UDF/#data-feed-configuration-data */
         TvConfigResponse: {
             supported_resolutions: components["schemas"]["Resolution"][];

package/src/nord/api/actions.ts

@@ -10,6 +10,7 @@ import {
   KeyType,
   Side,
   QuoteSize,
+  TriggerKind,
 } from "../../types";
 import {
   assert,
@@ -265,7 +266,7 @@ export async function placeOrder(
   const size = toScaledU64(params.size ?? 0, params.sizeDecimals);
 
   const scaledQuote = params.quoteSize
-    ? params.quoteSize.toScaledU64(params.priceDecimals, params.sizeDecimals)
+    ? params.quoteSize.toWire(params.priceDecimals, params.sizeDecimals)
     : undefined;
 
   assert(
@@ -411,6 +412,103 @@ export async function transfer(
   }
 }
 
+export async function addTrigger(
+  serverUrl: string,
+  signFn: (message: Uint8Array) => Promise<Uint8Array>,
+  currentTimestamp: bigint,
+  nonce: number,
+  params: {
+    sessionId: BigIntValue;
+    marketId: number;
+    side: Side;
+    kind: TriggerKind;
+    priceDecimals: number;
+    triggerPrice: Decimal.Value;
+    limitPrice?: Decimal.Value;
+    accountId?: number;
+  },
+): Promise<{ actionId: bigint }> {
+  const triggerPrice = toScaledU64(params.triggerPrice, params.priceDecimals);
+  assert(triggerPrice > 0n, "Trigger price must be positive");
+  const limitPrice =
+    params.limitPrice === undefined
+      ? undefined
+      : toScaledU64(params.limitPrice, params.priceDecimals);
+  if (limitPrice !== undefined) {
+    assert(limitPrice > 0n, "Limit price must be positive");
+  }
+  const key = create(proto.TriggerKeySchema, {
+    kind:
+      params.kind === TriggerKind.StopLoss
+        ? proto.TriggerKind.STOP_LOSS
+        : proto.TriggerKind.TAKE_PROFIT,
+    side: params.side === Side.Bid ? proto.Side.BID : proto.Side.ASK,
+  });
+  const prices = create(proto.Action_TriggerPricesSchema, {
+    triggerPrice,
+    limitPrice,
+  });
+  const action = createAction(currentTimestamp, nonce, {
+    case: "addTrigger",
+    value: create(proto.Action_AddTriggerSchema, {
+      sessionId: BigInt(params.sessionId),
+      marketId: params.marketId,
+      key,
+      prices,
+      accountId: params.accountId,
+    }),
+  });
+  const resp = await sendAction(
+    serverUrl,
+    (m) => sessionSign(signFn, m),
+    action,
+  );
+  if (resp.kind?.case === "triggerAdded") {
+    return { actionId: resp.actionId };
+  }
+  throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+}
+
+export async function removeTrigger(
+  serverUrl: string,
+  signFn: (message: Uint8Array) => Promise<Uint8Array>,
+  currentTimestamp: bigint,
+  nonce: number,
+  params: {
+    sessionId: BigIntValue;
+    marketId: number;
+    side: Side;
+    kind: TriggerKind;
+    accountId?: number;
+  },
+): Promise<{ actionId: bigint }> {
+  const key = create(proto.TriggerKeySchema, {
+    kind:
+      params.kind === TriggerKind.StopLoss
+        ? proto.TriggerKind.STOP_LOSS
+        : proto.TriggerKind.TAKE_PROFIT,
+    side: params.side === Side.Bid ? proto.Side.BID : proto.Side.ASK,
+  });
+  const action = createAction(currentTimestamp, nonce, {
+    case: "removeTrigger",
+    value: create(proto.Action_RemoveTriggerSchema, {
+      sessionId: BigInt(params.sessionId),
+      marketId: params.marketId,
+      key,
+      accountId: params.accountId,
+    }),
+  });
+  const resp = await sendAction(
+    serverUrl,
+    (m) => sessionSign(signFn, m),
+    action,
+  );
+  if (resp.kind?.case === "triggerRemoved") {
+    return { actionId: resp.actionId };
+  }
+  throw new Error(`Unexpected receipt kind ${resp.kind?.case}`);
+}
+
 export type AtomicSubaction =
   | {
       kind: "place";
@@ -457,7 +555,7 @@ export async function atomic(
       const price = toScaledU64(a.price ?? 0, a.priceDecimals);
       const size = toScaledU64(a.size ?? 0, a.sizeDecimals);
       const scaledQuote = a.quoteSize
-        ? a.quoteSize.toScaledU64(a.priceDecimals, a.sizeDecimals)
+        ? a.quoteSize.toWire(a.priceDecimals, a.sizeDecimals)
         : undefined;
 
       // Require at least one limit to be set (non-zero size, non-zero price, or quoteSize)

package/src/nord/api/triggers.ts

@@ -0,0 +1,57 @@
+import createClient from "openapi-fetch";
+
+import { paths, components } from "../../gen/openapi";
+
+type AccountTriggerInfo = components["schemas"]["AccountTriggerInfo"];
+type TriggerHistoryPage =
+  components["schemas"]["PageResult_for_uint64_and_HistoryTriggerInfo"];
+type HistoryTriggerQuery = components["schemas"]["AccountTriggersQuery"];
+
+export type { AccountTriggerInfo, TriggerHistoryPage, HistoryTriggerQuery };
+
+export async function getAccountTriggers(
+  serverUrl: string,
+  accountId: number,
+): Promise<AccountTriggerInfo[]> {
+  const client = createClient<paths>({ baseUrl: serverUrl });
+  const response = await client.GET("/account/{account_id}/triggers", {
+    params: {
+      path: { account_id: accountId },
+    },
+  });
+
+  if (response.data === undefined) {
+    throw new Error(
+      `Failed to fetch triggers for account ${accountId}: HTTP ${response.response.status}`,
+    );
+  }
+
+  return response.data ?? [];
+}
+
+export async function getAccountTriggerHistory(
+  serverUrl: string,
+  accountId: number,
+  options: HistoryTriggerQuery,
+): Promise<TriggerHistoryPage> {
+  const client = createClient<paths>({ baseUrl: serverUrl });
+  const response = await client.GET("/account/{account_id}/triggers/history", {
+    params: {
+      path: { account_id: accountId },
+      query: {
+        since: options.since,
+        until: options.until,
+        pageSize: options.pageSize,
+        startInclusive: options.startInclusive,
+      },
+    },
+  });
+
+  if (!response.data) {
+    throw new Error(
+      `Failed to fetch trigger history for account ${accountId}: HTTP ${response.response.status}`,
+    );
+  }
+
+  return response.data;
+}

package/src/nord/client/Nord.ts

@@ -6,6 +6,8 @@ import * as proto from "../../gen/nord_pb";
 import type { paths } from "../../gen/openapi.ts";
 import {
   Account,
+  AccountPnlPage,
+  AccountPnlQuery,
   ActionResponse,
   AggregateMetrics,
   Info,
@@ -636,6 +638,31 @@ export class Nord {
     });
   }
 
+  /**
+   * Get profit and loss history for an account
+   *
+   * @param accountId - Account ID to query
+   * @param query - Optional time and pagination filters
+   * @returns Page of PnL entries ordered from latest to oldest
+   * @throws {NordError} If the request fails
+   */
+  public async getAccountPnl(
+    accountId: number,
+    query?: Partial<AccountPnlQuery>,
+  ): Promise<AccountPnlPage> {
+    return await this.GET("/account/{account_id}/pnl", {
+      params: {
+        path: { account_id: accountId },
+        query: {
+          since: query?.since,
+          until: query?.until,
+          startInclusive: query?.startInclusive,
+          pageSize: query?.pageSize,
+        },
+      },
+    });
+  }
+
   /**
    * Get market statistics (alias for marketsStats for backward compatibility)
    *

package/src/nord/client/NordUser.ts

@@ -15,7 +15,13 @@ import * as ed from "@noble/ed25519";
 import { sha512 } from "@noble/hashes/sha512";
 ed.etc.sha512Sync = sha512;
 import { floatToScaledBigIntLossy } from "@n1xyz/proton";
-import { FillMode, Side, SPLTokenInfo, QuoteSize } from "../../types";
+import {
+  FillMode,
+  Side,
+  SPLTokenInfo,
+  QuoteSize,
+  TriggerKind,
+} from "../../types";
 import * as proto from "../../gen/nord_pb";
 import {
   BigIntValue,
@@ -34,7 +40,18 @@ import {
   withdraw,
   atomic as atomicAction,
   AtomicSubaction as ApiAtomicSubaction,
+  addTrigger as addTriggerAction,
+  removeTrigger as removeTriggerAction,
 } from "../api/actions";
+import type {
+  AccountTriggerInfo,
+  TriggerHistoryPage,
+  HistoryTriggerQuery,
+} from "../api/triggers";
+import {
+  getAccountTriggers as fetchAccountTriggers,
+  getAccountTriggerHistory as fetchAccountTriggerHistory,
+} from "../api/triggers";
 import { NordError } from "../utils/NordError";
 import { Nord } from "./Nord";
 
@@ -99,6 +116,22 @@ export interface PlaceOrderParams {
   accountId?: number;
 }
 
+export interface AddTriggerParams {
+  marketId: number;
+  side: Side;
+  kind: TriggerKind;
+  triggerPrice: Decimal.Value;
+  limitPrice?: Decimal.Value;
+  accountId?: number;
+}
+
+export interface RemoveTriggerParams {
+  marketId: number;
+  side: Side;
+  kind: TriggerKind;
+  accountId?: number;
+}
+
 /**
  * Parameters for transferring tokens between accounts
  */
@@ -834,6 +867,132 @@ export class NordUser {
     }
   }
 
+  /**
+   * Add a trigger for the current session
+   *
+   * @param params - Trigger parameters including market, side, and prices
+   * @returns Object containing the actionId of the submitted trigger
+   * @throws {NordError} If the operation fails
+   */
+  async addTrigger(params: AddTriggerParams): Promise<{ actionId: bigint }> {
+    try {
+      this.checkSessionValidity();
+      const market = findMarket(this.nord.markets, params.marketId);
+      if (!market) {
+        throw new NordError(`Market with ID ${params.marketId} not found`);
+      }
+      const result = await addTriggerAction(
+        this.nord.webServerUrl,
+        this.sessionSignFn,
+        await this.nord.getTimestamp(),
+        this.getNonce(),
+        {
+          sessionId: optExpect(this.sessionId, "No session"),
+          marketId: params.marketId,
+          side: params.side,
+          kind: params.kind,
+          priceDecimals: market.priceDecimals,
+          triggerPrice: params.triggerPrice,
+          limitPrice: params.limitPrice,
+          accountId: params.accountId,
+        },
+      );
+      return result;
+    } catch (error) {
+      throw new NordError("Failed to add trigger", { cause: error });
+    }
+  }
+
+  /**
+   * Remove a trigger for the current session
+   *
+   * @param params - Trigger parameters identifying the trigger to remove
+   * @returns Object containing the actionId of the removal action
+   * @throws {NordError} If the operation fails
+   */
+  async removeTrigger(
+    params: RemoveTriggerParams,
+  ): Promise<{ actionId: bigint }> {
+    try {
+      this.checkSessionValidity();
+      const market = findMarket(this.nord.markets, params.marketId);
+      if (!market) {
+        throw new NordError(`Market with ID ${params.marketId} not found`);
+      }
+      const result = await removeTriggerAction(
+        this.nord.webServerUrl,
+        this.sessionSignFn,
+        await this.nord.getTimestamp(),
+        this.getNonce(),
+        {
+          sessionId: optExpect(this.sessionId, "No session"),
+          marketId: params.marketId,
+          side: params.side,
+          kind: params.kind,
+          accountId: params.accountId,
+        },
+      );
+      return result;
+    } catch (error) {
+      throw new NordError("Failed to remove trigger", { cause: error });
+    }
+  }
+
+  /**
+   * Fetch active triggers for an account.
+   *
+   * @param params Optional parameters containing an explicit account id.
+   * @throws {NordError} If no account can be resolved or the request fails.
+   */
+  async getAccountTriggers(params?: {
+    accountId?: number;
+  }): Promise<AccountTriggerInfo[]> {
+    const accountId = params?.accountId ?? this.accountIds?.[0];
+
+    if (accountId == null) {
+      throw new NordError(
+        "Account ID is undefined. Make sure to call updateAccountId() before requesting triggers.",
+      );
+    }
+
+    try {
+      return await fetchAccountTriggers(this.nord.webServerUrl, accountId);
+    } catch (error) {
+      throw new NordError("Failed to fetch account triggers", { cause: error });
+    }
+  }
+
+  /**
+   * Fetch trigger history for an account.
+   *
+   * @param params Optional parameters with account id and history query filters.
+   * @throws {NordError} If no account can be resolved or the request fails.
+   */
+  async getAccountTriggerHistory(
+    params: HistoryTriggerQuery & { accountId?: number },
+  ): Promise<TriggerHistoryPage> {
+    const { accountId: providedAccountId, ...query } = params;
+    const accountId = providedAccountId ?? this.accountIds?.[0];
+
+    if (accountId == null) {
+      throw new NordError(
+        "Account ID is undefined. Make sure to call updateAccountId() before requesting trigger history.",
+      );
+    }
+
+    try {
+      return await fetchAccountTriggerHistory(
+        this.nord.webServerUrl,
+        accountId,
+        query,
+      );
+    } catch (error) {
+      throw new NordError("Failed to fetch account trigger history", {
+        cause: error,
+      });
+    }
+  }
+
   /**
    * Transfer tokens to another account
    *

package/src/types.ts

@@ -88,6 +88,10 @@ export type SideFromApi = components["schemas"]["Side"];
 export type FillModeFromApi = components["schemas"]["FillMode"];
 export type PlacementOrigin = components["schemas"]["PlacementOrigin"];
 export type FinalizationReason = components["schemas"]["FinalizationReason"];
+export type AccountPnlQuery = components["schemas"]["AccountPnlQuery"];
+export type AccountPnl = components["schemas"]["AccountPnl"];
+export type AccountPnlPage =
+  components["schemas"]["PageResult_for_uint64_and_AccountPnl"];
 
 /**
  * Configuration options for the Nord client
@@ -114,8 +118,8 @@ export enum KeyType {
 }
 
 export enum Side {
-  Ask,
-  Bid,
+  Ask = "ask",
+  Bid = "bid",
 }
 
 export enum FillMode {
@@ -125,6 +129,18 @@ export enum FillMode {
   FillOrKill,
 }
 
+export enum TriggerKind {
+  StopLoss = 0,
+  TakeProfit = 1,
+}
+
+export enum TriggerStatus {
+  Active = 0,
+  Success = 1,
+  Cancel = 2,
+  Remove = 4,
+}
+
 export interface SubscriberConfig {
   streamURL: string;
   maxBufferLen?: number;
@@ -304,9 +320,22 @@ export interface SPLTokenInfo {
 }
 
 // Positive decimal price and size.
+// Example:
+// ```
+// const limit = new QuoteSize(new Decimal(114000), new Decimal(0.00035)),
+//```
+// Gives 40$ USD limit.
+//
+// Given price is same(or very close) to the market price,
+// limit gives size tick as close as possible to settlemnt size tick.
+
+// If you want to get smaller tick on client (on server it will not change),
+// do `new QuoteSize(new Decimal(114000/2), new Decimal(0.00070))`.
+// It will be 40$ limit, but may help if BTC suddently moves fast.
 export class QuoteSize {
   price: Decimal;
   size: Decimal;
+  /// Input can be only positive values.
   constructor(quotePrice: Decimal.Value, quoteSize: Decimal.Value) {
     const p = new Decimal(quotePrice);
     const s = new Decimal(quoteSize);
@@ -317,11 +346,13 @@ export class QuoteSize {
     this.size = s;
   }
 
+  // USD value of limit, use for debug
   value(): Decimal {
     return this.price.mul(this.size);
   }
 
-  toScaledU64(
+  // Converts to wire format to be send to server, scaling price and size according to market decimals.
+  toWire(
     marketPriceDecimals: number,
     marketSizeDecimals: number,
   ): { price: bigint; size: bigint } {