aftermath-ts-sdk 1.3.23-perps.26 → 1.3.23-perps.28

package/dist/packages/perpetuals/perpetuals.d.ts

@@ -1,73 +1,397 @@
 import { Caller } from "../../general/utils/caller";
-import { PerpetualsMarketId, ApiPerpetualsOwnedAccountCapsBody, PerpetualsOrderSide, CoinType, PerpetualsOrderId, FilledTakerOrderEvent, Timestamp, ApiPerpetualsHistoricalMarketDataResponse, PerpetualsAccountCap, PerpetualsAccountId, PerpetualsAccountObject, CallerConfig, SuiAddress, ObjectId, ApiPerpetualsMarkets24hrStatsResponse, ApiPerpetualsAccountCapsBody, Percentage, Balance, PerpetualsVaultCap, PerpetualsVaultWithdrawRequest, PerpetualsVaultCapExtended, PerpetualsOrderPrice, ApiTransactionResponse, PerpetualsWsUpdatesResponseMessage, PerpetualsWsCandleResponseMessage, ApiPerpetualsCreateVaultCapBody } from "../../types";
+import { PerpetualsMarketId, ApiPerpetualsOwnedAccountCapsBody, PerpetualsOrderSide, CoinType, PerpetualsOrderId, FilledTakerOrderEvent, Timestamp, ApiPerpetualsHistoricalMarketDataResponse, PerpetualsAccountCap, PerpetualsAccountId, PerpetualsAccountObject, CallerConfig, SuiAddress, ObjectId, ApiPerpetualsMarkets24hrStatsResponse, ApiPerpetualsAccountCapsBody, Percentage, Balance, PerpetualsVaultCap, PerpetualsVaultWithdrawRequest, PerpetualsOrderPrice, ApiTransactionResponse, PerpetualsWsUpdatesResponseMessage, PerpetualsWsCandleResponseMessage, ApiPerpetualsCreateVaultCapBody, PerpetualsVaultLpCoin, PerpetualsPartialVaultCap } from "../../types";
 import { PerpetualsMarket } from "./perpetualsMarket";
 import { PerpetualsAccount } from "./perpetualsAccount";
 import { PerpetualsOrderUtils } from "./utils";
 import { AftermathApi } from "../../general/providers";
 import { Transaction, TransactionObjectArgument } from "@mysten/sui/transactions";
 import { PerpetualsVault } from "./perpetualsVault";
+/**
+ * High-level client for interacting with Aftermath Perpetuals.
+ *
+ * This class exposes a typed, ergonomic interface over the Perpetuals HTTP API
+ * and websocket endpoints, including:
+ *
+ * - Market discovery (`getAllMarkets`, `getMarkets`, `getMarket`)
+ * - Vault discovery (`getAllVaults`, `getVaults`, `getVault`)
+ * - Account & position data (`getAccount`, `getAccounts`, `getAccountObjects`)
+ * - Ownership queries (`getOwnedAccountCaps`, `getOwnedVaultCaps`)
+ * - Historical data & stats (`getMarketHistoricalData`, `getMarkets24hrStats`)
+ * - Pricing helpers (`getPrices`, `getLpCoinPrices`)
+ * - Transaction builders (`getCreateAccountTx`, `getCreateVaultCapTx`, `getCreateVaultTx`)
+ * - Websocket feeds (`openUpdatesWebsocketStream`, `openMarketCandlesWebsocketStream`)
+ *
+ * Typical usage via the root SDK:
+ *
+ * ```ts
+ * import { Aftermath } from "@aftermath/sdk";
+ *
+ * const afSdk = new Aftermath("MAINNET");
+ * await afSdk.init();
+ *
+ * const perps = afSdk.Perpetuals();
+ *
+ * // Fetch markets for a given collateral coin type
+ * const markets = await perps.getAllMarkets({
+ *   collateralCoinType: "0x2::sui::SUI",
+ * });
+ *
+ * // Fetch account + positions for a given account cap
+ * const [accountCap] = await perps.getOwnedAccountCaps({
+ *   walletAddress: "0x...",
+ * });
+ *
+ * const account = await perps.getAccount({ accountCap });
+ *
+ * // Build a create-account transaction (not signed or sent)
+ * const createAccountTx = await perps.getCreateAccountTx({
+ *   walletAddress: "0x...",
+ *   collateralCoinType: "0x2::sui::SUI",
+ * });
+ * ```
+ */
 export declare class Perpetuals extends Caller {
     readonly Provider?: AftermathApi | undefined;
+    /**
+     * Helper namespace for order-specific utilities such as parsing order IDs,
+     * extracting price bits, etc.
+     *
+     * This is a direct alias of {@link PerpetualsOrderUtils}.
+     */
     static readonly OrderUtils: typeof PerpetualsOrderUtils;
-    static readonly constants: {
-        stopOrderGasCostSUI: bigint;
-    };
+    /**
+     * Creates a new Perpetuals client.
+     *
+     * @param config - Optional caller configuration (network, auth token, etc.).
+     * @param Provider - Optional shared {@link AftermathApi} provider instance. When
+     *   provided, transaction-building helpers (e.g. `getCreateAccountTx`) can
+     *   derive serialized `txKind` from a `Transaction` object.
+     */
     constructor(config?: CallerConfig, Provider?: AftermathApi | undefined);
+    /**
+     * Fetch all perpetual markets for a given collateral coin type.
+     *
+     * @param inputs.collateralCoinType - Coin type used as collateral, e.g. `"0x2::sui::SUI"`.
+     * @returns Array of {@link PerpetualsMarket} instances, each wrapping the raw market data.
+     *
+     * @example
+     * ```ts
+     * const markets = await perps.getAllMarkets({
+     *   collateralCoinType: "0x2::sui::SUI",
+     * });
+     * ```
+     */
     getAllMarkets(inputs: {
         collateralCoinType: CoinType;
     }): Promise<PerpetualsMarket[]>;
+    /**
+     * Fetch a single market by ID.
+     *
+     * Internally calls {@link getMarkets} and returns the first entry.
+     *
+     * @param inputs.marketId - The market (clearing house) object ID.
+     * @returns A {@link PerpetualsMarket} instance corresponding to the given ID.
+     *
+     * @example
+     * ```ts
+     * const market = await perps.getMarket({ marketId: "0x..." });
+     * ```
+     */
     getMarket(inputs: {
         marketId: PerpetualsMarketId;
     }): Promise<PerpetualsMarket>;
+    /**
+     * Fetch multiple markets by ID.
+     *
+     * NOTE: the backend currently always returns market data together with an
+     * orderbook object, but this SDK helper ignores the orderbook and constructs
+     * {@link PerpetualsMarket} instances from the `market` field only.
+     *
+     * @param inputs.marketIds - Array of market object IDs to fetch.
+     * @returns Array of {@link PerpetualsMarket} objects in the same order as `marketIds`.
+     *
+     * @example
+     * ```ts
+     * const [marketA, marketB] = await perps.getMarkets({
+     *   marketIds: ["0x..A", "0x..B"],
+     * });
+     * ```
+     */
     getMarkets(inputs: {
         marketIds: PerpetualsMarketId[];
     }): Promise<PerpetualsMarket[]>;
+    /**
+     * Fetch all vaults on the current network.
+     *
+     * @returns Array of {@link PerpetualsVault} objects, each wrapping a vault on-chain object.
+     *
+     * @example
+     * ```ts
+     * const vaults = await perps.getAllVaults();
+     * ```
+     */
     getAllVaults(): Promise<PerpetualsVault[]>;
+    /**
+     * Fetch a single vault by ID.
+     *
+     * Internally calls {@link getVaults} and returns the first entry.
+     *
+     * @param inputs.marketId - The vault object ID (note: named `marketId` for historical reasons).
+     * @returns A {@link PerpetualsVault} instance.
+     *
+     * @example
+     * ```ts
+     * const vault = await perps.getVault({ marketId: "0x..." });
+     * ```
+     */
     getVault(inputs: {
         marketId: ObjectId;
     }): Promise<PerpetualsVault>;
+    /**
+     * Fetch multiple vaults by ID.
+     *
+     * @param inputs.vaultIds - Array of vault object IDs.
+     * @returns Array of {@link PerpetualsVault} objects in the same order as `vaultIds`.
+     *
+     * @example
+     * ```ts
+     * const [vaultA, vaultB] = await perps.getVaults({
+     *   vaultIds: ["0x..A", "0x..B"],
+     * });
+     * ```
+     */
     getVaults(inputs: {
         vaultIds: ObjectId[];
     }): Promise<PerpetualsVault[]>;
+    /**
+     * Convenience helper to fetch a single account (positions + account object) from an account cap.
+     *
+     * Internally calls {@link getAccounts} and returns the first entry.
+     *
+     * @param inputs.accountCap - Account-cap or vault-cap-extended object to derive account metadata from.
+     * @param inputs.marketIds - Optional list of markets to filter positions by.
+     * @returns A {@link PerpetualsAccount} instance.
+     *
+     * @example
+     * ```ts
+     * const [accountCap] = await perps.getOwnedAccountCaps({ walletAddress: "0x..." });
+     * const account = await perps.getAccount({ accountCap });
+     * ```
+     */
     getAccount(inputs: {
-        accountCap: PerpetualsAccountCap | PerpetualsVaultCapExtended;
+        accountCap: PerpetualsAccountCap | PerpetualsPartialVaultCap;
         marketIds?: PerpetualsMarketId[];
     }): Promise<PerpetualsAccount>;
+    /**
+     * Fetch one or more accounts (positions + account objects) from account caps.
+     *
+     * This composes two API calls:
+     * - `/perpetuals/accounts/positions` to fetch {@link PerpetualsAccountObject}s
+     * - Local pairing with the provided `accountCaps`
+     *
+     * The resulting {@link PerpetualsAccount} objects wrap both the on-chain account
+     * data and the cap metadata in a single helper.
+     *
+     * @param inputs.accountCaps - Array of account caps or vault-cap-extended objects.
+     * @param inputs.marketIds - Optional list of market IDs to filter positions by.
+     * @returns Array of {@link PerpetualsAccount} instances in the same order as `accountCaps`.
+     *
+     * @example
+     * ```ts
+     * const accountCaps = await perps.getOwnedAccountCaps({ walletAddress: "0x..." });
+     * const accounts = await perps.getAccounts({ accountCaps });
+     * ```
+     */
     getAccounts(inputs: {
-        accountCaps: (PerpetualsAccountCap | PerpetualsVaultCapExtended)[];
+        accountCaps: (PerpetualsAccountCap | PerpetualsPartialVaultCap)[];
         marketIds?: PerpetualsMarketId[];
     }): Promise<PerpetualsAccount[]>;
+    /**
+     * Fetch raw account objects (including positions) for one or more account IDs.
+     *
+     * @param inputs.accountIds - List of account IDs to query.
+     * @param inputs.collateralCoinType - Collateral coin type to use for valuation.
+     * @param inputs.marketIds - Optional list of market IDs to filter positions by.
+     * @returns Array of {@link PerpetualsAccountObject} in the same order as `accountIds`.
+     *
+     * @example
+     * ```ts
+     * const accountObjects = await perps.getAccountObjects({
+     *   accountIds: [123n, 456n],
+     *   collateralCoinType: "0x2::sui::SUI",
+     * });
+     * ```
+     */
     getAccountObjects(inputs: {
         accountIds: PerpetualsAccountId[];
         collateralCoinType: CoinType;
         marketIds?: PerpetualsMarketId[];
     }): Promise<PerpetualsAccountObject[]>;
+    /**
+     * Fetch all account caps (perpetuals accounts) owned by a wallet, optionally
+     * filtered by collateral coin types.
+     *
+     * @param inputs.walletAddress - Owner wallet address.
+     * @param inputs.collateralCoinTypes - Optional list of collateral coin types to filter by.
+     * @returns Array of {@link PerpetualsAccountCap} objects.
+     *
+     * @example
+     * ```ts
+     * const caps = await perps.getOwnedAccountCaps({
+     *   walletAddress: "0x...",
+     *   collateralCoinTypes: ["0x2::sui::SUI"],
+     * });
+     * ```
+     */
     getOwnedAccountCaps(inputs: ApiPerpetualsOwnedAccountCapsBody & {
         collateralCoinTypes?: CoinType[];
     }): Promise<PerpetualsAccountCap[]>;
+    /**
+     * Fetch all vault caps owned by a wallet.
+     *
+     * @param inputs.walletAddress - Owner wallet address.
+     * @returns Array of {@link PerpetualsVaultCap} objects.
+     *
+     * @example
+     * ```ts
+     * const vaultCaps = await perps.getOwnedVaultCaps({
+     *   walletAddress: "0x...",
+     * });
+     * ```
+     */
     getOwnedVaultCaps(inputs: ApiPerpetualsOwnedAccountCapsBody): Promise<PerpetualsVaultCap[]>;
-    getOwnedWithdrawRequests(inputs: {
+    /**
+     * Fetch all pending vault withdrawal requests created by a given wallet.
+     *
+     * @param inputs.walletAddress - Wallet address that created the withdraw requests.
+     * @returns Array of {@link PerpetualsVaultWithdrawRequest}.
+     *
+     * @example
+     * ```ts
+     * const withdrawRequests = await perps.getOwnedVaultWithdrawRequests({
+     *   walletAddress: "0x...",
+     * });
+     * ```
+     */
+    getOwnedVaultWithdrawRequests(inputs: {
         walletAddress: SuiAddress;
     }): Promise<PerpetualsVaultWithdrawRequest[]>;
+    getOwnedVaultLpCoins(inputs: {
+        walletAddress: SuiAddress;
+    }): Promise<PerpetualsVaultLpCoin[]>;
+    /**
+     * Fetch account caps by their cap object IDs.
+     *
+     * @param inputs.accountCapIds - List of account cap object IDs.
+     * @returns Array of {@link PerpetualsAccountCap}.
+     *
+     * @example
+     * ```ts
+     * const caps = await perps.getAccountCaps({
+     *   accountCapIds: ["0xcap1", "0xcap2"],
+     * });
+     * ```
+     */
     getAccountCaps(inputs: ApiPerpetualsAccountCapsBody): Promise<PerpetualsAccountCap[]>;
+    /**
+     * Fetch historical OHLCV candle data for a single market.
+     *
+     * @param inputs.marketId - Market ID to query.
+     * @param inputs.fromTimestamp - Start timestamp (inclusive).
+     * @param inputs.toTimestamp - End timestamp (exclusive).
+     * @param inputs.intervalMs - Candle interval in milliseconds.
+     * @returns Array of {@link PerpetualsMarketCandleDataPoint}.
+     *
+     * @example
+     * ```ts
+     * const candles = await perps.getMarketHistoricalData({
+     *   marketId: "0x...",
+     *   fromTimestamp: Date.now() - 24 * 60 * 60 * 1000,
+     *   toTimestamp: Date.now(),
+     *   intervalMs: 60_000, // 1 minute
+     * });
+     * ```
+     */
     getMarketHistoricalData(inputs: {
         marketId: PerpetualsMarketId;
         fromTimestamp: Timestamp;
         toTimestamp: Timestamp;
         intervalMs: number;
     }): Promise<ApiPerpetualsHistoricalMarketDataResponse>;
+    /**
+     * Fetch 24-hour stats for multiple markets.
+     *
+     * @param inputs.marketIds - Market IDs to query.
+     * @returns Array of 24hr stats aligned with `marketIds`.
+     *
+     * @example
+     * ```ts
+     * const stats = await perps.getMarkets24hrStats({
+     *   marketIds: ["0x...", "0x..."],
+     * });
+     * ```
+     */
     getMarkets24hrStats(inputs: {
         marketIds: PerpetualsMarketId[];
     }): Promise<ApiPerpetualsMarkets24hrStatsResponse>;
+    /**
+     * Fetch the latest oracle prices (base & collateral) for one or more markets.
+     *
+     * @param inputs.marketIds - List of market IDs to query.
+     * @returns Array of `{ basePrice, collateralPrice }` objects in the same order as `marketIds`.
+     *   Returns `[]` if `marketIds` is empty.
+     *
+     * @example
+     * ```ts
+     * const prices = await perps.getPrices({ marketIds: ["0x..."] });
+     * const { basePrice, collateralPrice } = prices[0];
+     * ```
+     */
     getPrices(inputs: {
         marketIds: ObjectId[];
     }): Promise<{
         basePrice: number;
         collateralPrice: number;
     }[]>;
+    /**
+     * Fetch LP coin prices (in collateral units) for a set of vaults.
+     *
+     * @param inputs.vaultIds - List of vault IDs to query.
+     * @returns Array of LP prices corresponding to each vault ID; returns `[]` if none are provided.
+     *
+     * @example
+     * ```ts
+     * const [price] = await perps.getLpCoinPrices({ vaultIds: ["0x..."] });
+     * ```
+     */
     getLpCoinPrices(inputs: {
         vaultIds: ObjectId[];
     }): Promise<number[]>;
+    /**
+     * Build a `create-account` transaction for Aftermath Perpetuals.
+     *
+     * This helper:
+     * - Optionally converts a {@link Transaction} into a serialized `txKind`
+     *   via the shared `Provider` (if present).
+     * - Calls the `/perpetuals/transactions/create-account` endpoint.
+     * - Returns a serialized transaction (`txKind`) that you can sign and execute.
+     *
+     * @param inputs.walletAddress - The wallet address that will own the new account.
+     * @param inputs.collateralCoinType - Collateral coin type to be used with this account.
+     * @param inputs.tx - Optional {@link Transaction} to extend; if provided,
+     *   the create-account commands are appended to this transaction.
+     *
+     * @returns API transaction response containing `txKind`.
+     *
+     * @example
+     * ```ts
+     * const { txKind } = await perps.getCreateAccountTx({
+     *   walletAddress: "0x...",
+     *   collateralCoinType: "0x2::sui::SUI",
+     * });
+     * // sign + execute txKind with your wallet adapter
+     * ```
+     */
     getCreateAccountTx(inputs: {
         walletAddress: SuiAddress;
         collateralCoinType: CoinType;
@@ -75,17 +399,71 @@ export declare class Perpetuals extends Caller {
     }): Promise<Omit<ApiTransactionResponse, "txKind"> & {
         tx: Transaction;
     }>;
+    /**
+     * Build a `create-vault-cap` transaction.
+     *
+     * This helper directly forwards the body through to the backend. If you wish
+     * to extend an existing {@link Transaction}, build the `txKind` yourself
+     * and pass it as part of {@link ApiPerpetualsCreateVaultCapBody}.
+     *
+     * @param inputs - Request body for the create-vault-cap endpoint.
+     * @returns API transaction response containing `txKind`.
+     *
+     * @example
+     * ```ts
+     * const { txKind } = await perps.getCreateVaultCapTx({
+     *   walletAddress: "0x...",
+     * });
+     * ```
+     */
     getCreateVaultCapTx(inputs: ApiPerpetualsCreateVaultCapBody): Promise<Omit<ApiTransactionResponse, "txKind"> & {
         tx: Transaction;
     }>;
+    /**
+     * Build a `create-vault` transaction.
+     *
+     * This helper:
+     * - Optionally converts a {@link Transaction} into a serialized `txKind`
+     *   via the shared `Provider` (if present).
+     * - Calls `/perpetuals/vault/transactions/create-vault`.
+     * - Returns a serialized transaction (`txKind`) that you can sign and execute.
+     *
+     * You can specify the initial deposit either as an explicit amount or as a
+     * `depositCoinArg` referring to an existing transaction argument.
+     *
+     * @param inputs.name - Human-readable vault name.
+     * @param inputs.walletAddress - Address of vault owner.
+     * @param inputs.lpCoinType - Coin type for the LP token.
+     * @param inputs.collateralCoinType - Collateral coin type for the vault.
+     * @param inputs.lockPeriodMs - Lock-in period for deposits in milliseconds.
+     * @param inputs.ownerFeePercentage - Percentage of user profits taken as owner fee.
+     * @param inputs.forceWithdrawDelayMs - Delay before forced withdrawals are processed.
+     * @param inputs.isSponsoredTx - Whether this transaction is sponsored (fees paid by another party).
+     * @param inputs.initialDepositAmount - Initial deposit amount (mutually exclusive with `initialDepositCoinArg`).
+     * @param inputs.initialDepositCoinArg - Transaction object argument referencing the deposit coin.
+     * @param inputs.tx - Optional {@link Transaction} to extend.
+     *
+     * @returns API transaction response containing `txKind`.
+     *
+     * @example
+     * ```ts
+     * const { txKind } = await perps.getCreateVaultTx({
+     *   name: "My Vault",
+     *   walletAddress: "0x...",
+     *   lpCoinType: "0x...::lp::LP",
+     *   collateralCoinType: "0x2::sui::SUI",
+     *   lockPeriodMs: BigInt(7 * 24 * 60 * 60 * 1000),
+     *   ownerFeePercentage: 0.2,
+     *   forceWithdrawDelayMs: BigInt(24 * 60 * 60 * 1000),
+     *   initialDepositAmount: BigInt("1000000000"),
+     * });
+     * ```
+     */
     getCreateVaultTx(inputs: {
         name: string;
         walletAddress: SuiAddress;
         lpCoinType: CoinType;
         collateralCoinType: CoinType;
-        collateralOracleId: ObjectId;
-        collateralPriceFeedId: ObjectId;
-        collateralPriceFeedTolerance: bigint;
         lockPeriodMs: bigint;
         ownerFeePercentage: Percentage;
         forceWithdrawDelayMs: bigint;
@@ -98,32 +476,154 @@ export declare class Perpetuals extends Caller {
     })): Promise<Omit<ApiTransactionResponse, "txKind"> & {
         tx: Transaction;
     }>;
+    /**
+     * Determine the logical order side (Bid/Ask) from a signed base asset amount.
+     *
+     * @param inputs.baseAssetAmount - Position base size. Positive => Bid (long), negative => Ask (short).
+     * @returns Corresponding {@link PerpetualsOrderSide}.
+     *
+     * @example
+     * ```ts
+     * const side = Perpetuals.positionSide({ baseAssetAmount: -1 });
+     * // side === PerpetualsOrderSide.Ask
+     * ```
+     */
     static positionSide(inputs: {
         baseAssetAmount: number;
     }): PerpetualsOrderSide;
+    /**
+     * Compute the effective price from a {@link FilledTakerOrderEvent}.
+     *
+     * Uses `quoteAssetDelta / baseAssetDelta`.
+     *
+     * @param inputs.orderEvent - Filled taker order event.
+     * @returns Trade price as a `number`.
+     */
     static orderPriceFromEvent(inputs: {
         orderEvent: FilledTakerOrderEvent;
     }): number;
+    /**
+     * Extract the price (as floating-point) from an encoded order ID.
+     *
+     * Internally uses {@link PerpetualsOrderUtils.price} and converts the
+     * fixed-point `PerpetualsOrderPrice` into a `number`.
+     *
+     * @param inputs.orderId - Encoded order ID.
+     * @returns Floating-point price.
+     */
     static orderPriceFromOrderId(inputs: {
         orderId: PerpetualsOrderId;
     }): number;
+    /**
+     * Convert a floating-point price into a fixed-point {@link PerpetualsOrderPrice}
+     * using 9 decimal places of precision.
+     *
+     * @param inputs.price - Floating-point price.
+     * @returns Encoded {@link PerpetualsOrderPrice} as `bigint`.
+     */
     static priceToOrderPrice: (inputs: {
         price: number;
     }) => PerpetualsOrderPrice;
+    /**
+     * Convert a fixed-point {@link PerpetualsOrderPrice} to a human-friendly price.
+     *
+     * @param inputs.orderPrice - Encoded order price as `bigint`.
+     * @returns Floating-point price value.
+     */
     static orderPriceToPrice: (inputs: {
         orderPrice: PerpetualsOrderPrice;
     }) => number;
+    /**
+     * Convert a fixed-point lot or tick size (9 decimals) to a `number`.
+     *
+     * @param lotOrTickSize - Fixed-point size as `bigint`.
+     * @returns Floating-point representation.
+     */
     static lotOrTickSizeToNumber(lotOrTickSize: bigint): number;
+    /**
+     * Convert a floating-point lot or tick size to its fixed-point representation (9 decimals).
+     *
+     * @param lotOrTickSize - Floating-point size.
+     * @returns Fixed-point representation as `bigint`.
+     */
     static lotOrTickSizeToBigInt(lotOrTickSize: number): bigint;
+    /**
+     * Infer the order side from an order ID.
+     *
+     * Uses {@link PerpetualsOrderUtils.isAsk} under the hood.
+     *
+     * @param orderId - Encoded order ID.
+     * @returns {@link PerpetualsOrderSide.Ask} if ask, otherwise {@link PerpetualsOrderSide.Bid}.
+     */
     static orderIdToSide: (orderId: PerpetualsOrderId) => PerpetualsOrderSide;
+    /**
+     * Construct a full event type string for a collateral-specific event.
+     *
+     * Many Move events are generic over a collateral coin type. This helper
+     * appends `<collateralCoinType>` to a base `eventType`.
+     *
+     * @param inputs.eventType - Base event type without type parameters.
+     * @param inputs.collateralCoinType - Collateral coin type, e.g. `"0x2::sui::SUI"`.
+     * @returns Fully-qualified event type string.
+     *
+     * @example
+     * ```ts
+     * const fullType = Perpetuals.eventTypeForCollateral({
+     *   eventType: "0x1::perps::DepositedCollateral",
+     *   collateralCoinType: "0x2::sui::SUI",
+     * });
+     * // "0x1::perps::DepositedCollateral<0x2::sui::SUI>"
+     * ```
+     */
     static eventTypeForCollateral: (inputs: {
         eventType: string;
         collateralCoinType: CoinType;
     }) => string;
     /**
-     * Open the main updates websocket: /perpetuals/ws/updates
+     * Open the main updates websocket: `/perpetuals/ws/updates`.
+     *
+     * This stream can deliver:
+     * - Market updates
+     * - User account + stop order updates
+     * - Oracle price updates
+     * - Orderbook deltas
+     * - Market trades
+     * - User trades
+     * - User collateral changes
      *
-     * @returns controller with perps-specific subscribe/unsubscribe helpers
+     * The returned controller object includes a set of convenient subscribe /
+     * unsubscribe helpers for each stream type.
+     *
+     * @param args.onMessage - Handler for incoming messages from the ws.
+     * @param args.onOpen - Optional hook called when the websocket is opened.
+     * @param args.onError - Optional hook called on websocket error.
+     * @param args.onClose - Optional hook called when the websocket closes.
+     *
+     * @returns An object containing:
+     * - `ws`: the underlying `WebSocket` instance
+     * - subscribe/unsubscribe helpers:
+     *   - `subscribeMarket` / `unsubscribeMarket`
+     *   - `subscribeUser` / `unsubscribeUser`
+     *   - `subscribeOracle` / `unsubscribeOracle`
+     *   - `subscribeOrderbook` / `unsubscribeOrderbook`
+     *   - `subscribeMarketTrades` / `unsubscribeMarketTrades`
+     *   - `subscribeUserTrades` / `unsubscribeUserTrades`
+     *   - `subscribeUserCollateralChanges` / `unsubscribeUserCollateralChanges`
+     * - `close`: function to close the websocket
+     *
+     * @example
+     * ```ts
+     * const stream = perps.openUpdatesWebsocketStream({
+     *   onMessage: (msg) => {
+     *     if ("market" in msg) {
+     *       console.log("Market update", msg.market);
+     *     }
+     *   },
+     * });
+     *
+     * stream.subscribeMarket({ marketId: "0x..." });
+     * stream.subscribeUser({ accountId: 123n, withStopOrders: undefined });
+     * ```
      */
     openUpdatesWebsocketStream(args: {
         onMessage: (env: PerpetualsWsUpdatesResponseMessage) => void;
@@ -187,8 +687,33 @@ export declare class Perpetuals extends Caller {
         close: () => void;
     };
     /**
-     * Open market-candles websocket for a single market/interval:
-     * /perpetuals/ws/market-candles/{market_id}/{interval_ms}
+     * Open a market-candles websocket stream for a single market/interval:
+     * `/perpetuals/ws/market-candles/{market_id}/{interval_ms}`.
+     *
+     * The stream emits {@link PerpetualsWsCandleResponseMessage} messages,
+     * typically containing the latest candle for the specified interval.
+     *
+     * @param args.marketId - Market ID to subscribe to.
+     * @param args.intervalMs - Candle interval in milliseconds.
+     * @param args.onMessage - Handler for incoming candle updates.
+     * @param args.onOpen - Optional hook called when the websocket opens.
+     * @param args.onError - Optional hook called on websocket error.
+     * @param args.onClose - Optional hook called when the websocket closes.
+     *
+     * @returns An object containing:
+     * - `ws`: the underlying `WebSocket` instance
+     * - `close`: function to close the websocket
+     *
+     * @example
+     * ```ts
+     * const stream = perps.openMarketCandlesWebsocketStream({
+     *   marketId: "0x...",
+     *   intervalMs: 60_000,
+     *   onMessage: ({ lastCandle }) => {
+     *     console.log("New candle:", lastCandle);
+     *   },
+     * });
+     * ```
      */
     openMarketCandlesWebsocketStream(args: {
         marketId: PerpetualsMarketId;