aftermath-ts-sdk 1.3.27 → 1.3.28

package/dist/packages/perpetuals/perpetuals.js

@@ -8,152 +8,1095 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-var _a;
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Perpetuals = void 0;
 const caller_1 = require("../../general/utils/caller");
 const types_1 = require("../../types");
 const perpetualsMarket_1 = require("./perpetualsMarket");
 const perpetualsAccount_1 = require("./perpetualsAccount");
-const iFixedUtils_1 = require("../../general/utils/iFixedUtils");
 const fixedUtils_1 = require("../../general/utils/fixedUtils");
-const utils_1 = require("../../general/utils");
-const utils_2 = require("./utils");
+const utils_1 = require("./utils");
+const transactions_1 = require("@mysten/sui/transactions");
+const perpetualsVault_1 = require("./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 (`getMarketCandleHistory`, `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",
+ * });
+ * ```
+ */
 class Perpetuals extends caller_1.Caller {
     // =========================================================================
     //  Constructor
     // =========================================================================
-    constructor(config) {
+    /**
+     * 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 can derive serialized `txKind`
+     *   from a {@link Transaction} object via `Provider.Transactions().fetchBase64TxKindFromTx`.
+     *
+     * @remarks
+     * This class extends {@link Caller} with the `"perpetuals"` route prefix, meaning:
+     * - HTTP calls resolve under `/perpetuals/...`
+     * - Websocket calls resolve under `/perpetuals/ws/...`
+     */
+    constructor(config, Provider) {
         super(config, "perpetuals");
+        this.Provider = Provider;
     }
     // =========================================================================
-    //  Class Objects
+    //  Markets
     // =========================================================================
+    /**
+     * Fetch all perpetual markets for a given collateral coin type.
+     *
+     * This method returns *wrapped* {@link PerpetualsMarket} instances, not the raw
+     * market structs. Each instance provides additional helpers for pricing, margin,
+     * and order parsing.
+     *
+     * @param inputs.collateralCoinType - Coin type used as collateral, e.g. `"0x2::sui::SUI"`.
+     * @returns Object containing `markets`.
+     *
+     * @example
+     * ```ts
+     * const { markets } = await perps.getAllMarkets({
+     *   collateralCoinType: "0x2::sui::SUI",
+     * });
+     * ```
+     */
     getAllMarkets(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { collateralCoinType } = inputs;
-            const marketDatas = yield this.fetchApi(`${collateralCoinType}/markets`);
-            return marketDatas.map((marketData) => new perpetualsMarket_1.PerpetualsMarket(marketData, this.config));
+            const res = yield this.fetchApi("all-markets", inputs);
+            return {
+                markets: res.markets.map((marketData) => new perpetualsMarket_1.PerpetualsMarket(marketData, this.config, this.Provider)),
+            };
         });
     }
+    /**
+     * 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 Object containing `market`.
+     *
+     * @throws If the backend returns an empty list for the given `marketId`,
+     * this will still attempt to return `markets[0]` (which would be `undefined`).
+     * Callers may want to validate the result.
+     *
+     * @example
+     * ```ts
+     * const { market } = await perps.getMarket({ marketId: "0x..." });
+     * ```
+     */
     getMarket(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const marketData = yield this.fetchApi(`${inputs.collateralCoinType}/markets/${inputs.marketId}`);
-            return new perpetualsMarket_1.PerpetualsMarket(marketData, this.config);
+            const { markets } = yield this.getMarkets({
+                marketIds: [inputs.marketId],
+            });
+            return {
+                market: markets[0],
+            };
         });
     }
+    /**
+     * Fetch multiple markets by ID.
+     *
+     * Backend note:
+     * - The API supports returning orderbooks. This SDK currently constructs
+     *  {@link PerpetualsMarket} from the returned `marketDatas[].market`.
+     *
+     * @param inputs.marketIds - Array of market object IDs to fetch.
+     * @returns Object containing `markets` in the same order as `marketIds`.
+     *
+     * @example
+     * ```ts
+     * const { markets } = await perps.getMarkets({
+     *   marketIds: ["0x..A", "0x..B"],
+     * });
+     * ```
+     */
     getMarkets(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { collateralCoinType } = inputs;
-            return Promise.all(inputs.marketIds.map((marketId) => this.getMarket({
-                marketId,
-                collateralCoinType,
-            })));
+            const res = yield this.fetchApi("markets", inputs);
+            return {
+                markets: res.marketDatas.map((marketData) => new perpetualsMarket_1.PerpetualsMarket(marketData.market, this.config, this.Provider)),
+            };
+        });
+    }
+    // =========================================================================
+    //  Vaults
+    // =========================================================================
+    /**
+     * Fetch all vaults on the current network.
+     *
+     * Vaults are managed accounts that can hold positions; LPs deposit collateral
+     * and receive an LP coin (see pricing helpers like {@link getLpCoinPrices}).
+     *
+     * @returns Object containing `vaults`.
+     *
+     * @example
+     * ```ts
+     * const { vaults } = await perps.getAllVaults();
+     * ```
+     */
+    getAllVaults() {
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.fetchApi("vaults", {});
+            return {
+                vaults: res.vaults.map((vaultObject) => new perpetualsVault_1.PerpetualsVault(vaultObject, this.config, this.Provider)),
+            };
         });
     }
+    /**
+     * Fetch a single vault by ID.
+     *
+     * Internally calls {@link getVaults} and returns the first entry.
+     *
+     * @param inputs.vaultId - Vault object ID.
+     * @returns Object containing `vault`.
+     */
+    getVault(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { vaults } = yield this.getVaults({
+                vaultIds: [inputs.vaultId],
+            });
+            return {
+                vault: vaults[0],
+            };
+        });
+    }
+    /**
+     * Fetch multiple vaults by ID.
+     *
+     * @param inputs.vaultIds - Array of vault object IDs.
+     * @returns Object containing `vaults` in the same order as `vaultIds`.
+     */
+    getVaults(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const res = yield this.fetchApi("vaults", inputs);
+            return {
+                vaults: res.vaults.map((vaultObject) => new perpetualsVault_1.PerpetualsVault(vaultObject, this.config, this.Provider)),
+            };
+        });
+    }
+    // =========================================================================
+    //  Accounts
+    // =========================================================================
+    /**
+     * 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 partial vault cap object to derive account metadata from.
+     * @param inputs.marketIds - Optional list of markets to filter positions by.
+     * @returns Object containing `account`.
+     *
+     * @example
+     * ```ts
+     * const [accountCap] = await perps.getOwnedAccountCaps({ walletAddress: "0x..." });
+     * const { account } = await perps.getAccount({ accountCap });
+     * ```
+     */
+    // TODO: merge this with `getAccountObjects` as an option ?
     getAccount(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { accountCap } = inputs;
-            const account = yield this.fetchApi(`${accountCap.collateralCoinType}/accounts/${accountCap.accountId}`);
-            return new perpetualsAccount_1.PerpetualsAccount(account, accountCap, this.config);
+            const { accountCap, marketIds } = inputs;
+            return {
+                account: (yield this.getAccounts({
+                    accountCaps: [accountCap],
+                    marketIds,
+                })).accounts[0],
+            };
         });
     }
-    getUserAccountCaps(inputs) {
+    /**
+     * Fetch one or more accounts (positions + account objects) from account caps.
+     *
+     * This composes:
+     * 1) {@link getAccountObjects} to fetch {@link PerpetualsAccountObject}s by account ID
+     * 2) Local pairing of returned account objects with `accountCaps`
+     *
+     * The returned {@link PerpetualsAccount} instances encapsulate:
+     * - The account snapshot (positions, balances, etc.)
+     * - The ownership/cap metadata (accountId, collateral type, vaultId, etc.)
+     *
+     * @param inputs.accountCaps - Array of account caps or partial vault cap objects.
+     * @param inputs.marketIds - Optional list of market IDs to filter positions by.
+     * @returns Object containing `accounts` in the same order as `accountCaps`.
+     *
+     * @remarks
+     * If `accountCaps` is empty, this returns `{ accounts: [] }` without making an API call.
+     */
+    getAccounts(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
-            const { collateralCoinType, walletAddress } = inputs;
-            return this.fetchApi(`${collateralCoinType}/accounts`, {
+            const { accountCaps, marketIds } = inputs;
+            if (accountCaps.length <= 0)
+                return {
+                    accounts: [],
+                };
+            const accountObjects = (yield this.getAccountObjects({
+                accountIds: accountCaps.map((accountCap) => accountCap.accountId),
+                marketIds,
+            })).accounts;
+            return {
+                accounts: accountObjects.map((account, index) => new perpetualsAccount_1.PerpetualsAccount(account, accountCaps[index], this.config, this.Provider)),
+            };
+        });
+    }
+    /**
+     * Fetch raw account objects (including positions) for one or more account IDs.
+     *
+     * This is the lower-level primitive used by {@link getAccounts}.
+     *
+     * @param inputs.accountIds - List of account IDs to query.
+     * @param inputs.marketIds - Optional list of market IDs to filter positions by.
+     *
+     * @returns {@link ApiPerpetualsAccountPositionsResponse} containing `accounts`.
+     *
+     * @remarks
+     * If `accountIds` is empty, this returns `{ accounts: [] }` without making an API call.
+     */
+    getAccountObjects(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { accountIds, marketIds } = inputs;
+            if (accountIds.length <= 0)
+                return {
+                    accounts: [],
+                };
+            return this.fetchApi("accounts/positions", {
+                accountIds,
+                marketIds,
+            });
+        });
+    }
+    // =========================================================================
+    //  Ownership Queries
+    // =========================================================================
+    /**
+     * Fetch all account caps (perpetuals accounts) owned by a wallet, optionally
+     * filtered by collateral coin types.
+     *
+     * Returned values are “caps” (ownership objects), not full account snapshots.
+     * To fetch account positions, use {@link getAccount} or {@link getAccounts}.
+     *
+     * @param inputs.walletAddress - Owner wallet address.
+     * @param inputs.collateralCoinTypes - Optional list of collateral coin types to filter by.
+     * @returns {@link ApiPerpetualsOwnedAccountCapsResponse} containing `accounts`.
+     *
+     * @example
+     * ```ts
+     * const { accounts } = await perps.getOwnedAccountCaps({
+     *   walletAddress: "0x...",
+     *   collateralCoinTypes: ["0x2::sui::SUI"],
+     * });
+     * ```
+     */
+    getOwnedAccountCaps(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { walletAddress, collateralCoinTypes } = inputs;
+            return this.fetchApi("accounts/owned", {
                 walletAddress,
+                collateralCoinTypes,
             });
         });
     }
+    /**
+     * Fetch all vault caps owned by a wallet.
+     *
+     * Vault caps represent ownership/administrative authority over a vault.
+     *
+     * @param inputs.walletAddress - Owner wallet address.
+     * @returns {@link ApiPerpetualsOwnedVaultCapsResponse} containing vault caps.
+     */
+    getOwnedVaultCaps(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("vaults/owned-vault-caps", inputs);
+        });
+    }
+    /**
+     * Fetch all pending vault withdrawal requests created by a given wallet.
+     *
+     * Withdraw requests are typically created when LPs request to exit a vault
+     * and may be subject to lock periods / delays depending on vault configuration.
+     *
+     * @param inputs.walletAddress - Wallet address that created the withdraw requests.
+     * @returns {@link ApiPerpetualsVaultOwnedWithdrawRequestsResponse} containing requests.
+     */
+    getOwnedVaultWithdrawRequests(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("vaults/owned-withdraw-requests", Object.assign({}, inputs));
+        });
+    }
+    /**
+     * Fetch all Perpetuals vault LP coins owned by a wallet.
+     *
+     * This returns coin objects (or summaries) representing LP token holdings.
+     * Use {@link getLpCoinPrices} to value them in collateral units.
+     *
+     * @param inputs - {@link ApiPerpetualsVaultOwnedLpCoinsBody}.
+     * @returns {@link ApiPerpetualsVaultOwnedLpCoinsResponse}.
+     */
+    getOwnedVaultLpCoins(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("vaults/owned-lp-coins", inputs);
+        });
+    }
+    /**
+     * Fetch account caps by their account IDs.
+     *
+     * @param inputs.accountCapIds - List of account IDs.
+     * @returns {@link ApiPerpetualsAccountCapsResponse} containing caps.
+     */
+    getAdminAccountCaps(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("accounts", inputs);
+        });
+    }
     // =========================================================================
-    //  Data
+    //  Historical Data & Stats
     // =========================================================================
-    getMarketHistoricalData(inputs) {
-        const { collateralCoinType, marketId, fromTimestamp, toTimestamp, intervalMs, } = inputs;
-        return this.fetchApi(`${collateralCoinType}/markets/${marketId}/historical-data/${fromTimestamp}/${toTimestamp}/${intervalMs}`);
+    /**
+     * 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 {@link ApiPerpetualsMarketCandleHistoryResponse} containing candle points.
+     *
+     * @remarks
+     * This is currently implemented on the Perpetuals root client, but it may be
+     * relocated to {@link PerpetualsMarket} in the future.
+     */
+    // TODO: move to market class ?
+    getMarketCandleHistory(inputs) {
+        const { marketId, fromTimestamp, toTimestamp, intervalMs } = inputs;
+        return this.fetchApi("market/candle-history", {
+            marketId,
+            fromTimestamp,
+            toTimestamp,
+            intervalMs,
+        });
+    }
+    /**
+     * Fetch 24-hour volume and price change stats for multiple markets.
+     *
+     * Returns volume, price change, and the latest base, collateral,
+     * mid, and mark prices for each requested market.
+     *
+     * @param inputs.marketIds - Market IDs to query.
+     * @returns {@link ApiPerpetualsMarkets24hrStatsResponse}.
+     */
+    getMarkets24hrStats(inputs) {
+        return this.fetchApi("markets/24hr-stats", inputs);
+    }
+    // =========================================================================
+    //  Prices
+    // =========================================================================
+    /**
+     * Fetch the latest prices for one or more markets.
+     *
+     * Returns base, collateral, order book mid, and mark prices for each
+     * requested market.
+     *
+     * @param inputs.marketIds - List of market IDs to query.
+     * @returns {@link ApiPerpetualsMarketsPricesResponse} containing `marketsPrices`.
+     *
+     * @remarks
+     * If `marketIds` is empty, returns `{ marketsPrices: [] }` without making an API call.
+     */
+    getPrices(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (inputs.marketIds.length <= 0)
+                return {
+                    marketsPrices: [],
+                };
+            return this.fetchApi("markets/prices", inputs);
+        });
+    }
+    /**
+     * Fetch LP coin prices (in collateral units) for a set of vaults.
+     *
+     * @param inputs.vaultIds - List of vault IDs to query.
+     * @returns {@link ApiPerpetualsVaultLpCoinPricesResponse} containing `lpCoinPrices`.
+     *
+     * @remarks
+     * If `vaultIds` is empty, returns `{ lpCoinPrices: [] }` without making an API call.
+     */
+    getLpCoinPrices(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (inputs.vaultIds.length <= 0)
+                return {
+                    lpCoinPrices: [],
+                };
+            return this.fetchApi("vaults/lp-coin-prices", inputs);
+        });
     }
     // =========================================================================
     //  Transactions
     // =========================================================================
+    /**
+     * Build a `transfer-cap` transaction that transfers a Perpetuals capability object (cap)
+     * to another wallet.
+     *
+     * Provide the `capObjectId` of the capability you want to transfer (e.g., an account cap
+     * or vault cap) and the `recipientAddress` that should receive it.
+     *
+     * This endpoint builds a transaction only; it does not submit it on-chain.
+     *
+     * @param inputs.recipientAddress - Recipient wallet address that should receive the cap.
+     * @param inputs.capObjectId - Object ID of the capability to transfer.
+     * @param inputs.tx - Optional transaction to extend.
+     *
+     * @returns Transaction response containing a `tx`.
+     */
+    getTransferCapTx(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { tx, recipientAddress, capObjectId } = inputs;
+            return this.fetchApiTxObject("transactions/transfer-cap", {
+                recipientAddress,
+                capObjectId,
+                txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({
+                    tx: tx !== null && tx !== void 0 ? tx : new transactions_1.Transaction(),
+                })),
+            }, undefined, {
+                txKind: true,
+            });
+        });
+    }
+    /**
+     * Build a `create-account` transaction for Aftermath Perpetuals.
+     *
+     * @param inputs.walletAddress - Wallet address that will own the new account.
+     * @param inputs.collateralCoinType - Collateral coin type used by the account.
+     * @param inputs.tx - Optional {@link Transaction} to extend; if provided, the
+     *   create-account commands are appended to this transaction.
+     *
+     * @returns {@link SdkTransactionResponse} with `tx`.
+     */
     getCreateAccountTx(inputs) {
         return __awaiter(this, void 0, void 0, function* () {
-            return this.fetchApiTransaction("transactions/create-account", inputs);
+            var _a;
+            const { walletAddress, collateralCoinType, tx } = inputs;
+            return this.fetchApiTxObject("transactions/create-account", {
+                walletAddress,
+                collateralCoinType,
+                txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({ tx })),
+            }, undefined, {
+                txKind: true,
+            });
+        });
+    }
+    /**
+     * Build a `create-vault-cap` transaction.
+     *
+     * A vault cap is an ownership/admin object for interacting with vault management
+     * flows. This method returns a transaction kind that mints/creates that cap.
+     *
+     * @param inputs - {@link ApiPerpetualsCreateVaultCapBody}.
+     * @returns {@link SdkTransactionResponse} with `tx`.
+     */
+    getCreateVaultCapTx(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApiTxObject("vault/transactions/create-vault-cap", inputs, undefined, {
+                txKind: true,
+            });
+        });
+    }
+    /**
+     * Build a `create-vault` transaction.
+     *
+     * This creates a new vault plus its on-chain metadata and initial LP supply
+     * seeded by the initial deposit.
+     *
+     * Deposit input:
+     * - Use `initialDepositAmount` to have the API select/merge coins as needed, OR
+     * - Use `initialDepositCoinArg` if you already have a coin argument in a larger tx.
+     *
+     * Metadata:
+     * - Stored on-chain (or in a referenced object) as part of vault creation.
+     * - `extraFields` allows forward-compatible additions (e.g. social links).
+     *
+     * @param inputs.walletAddress - Address of vault owner/curator.
+     * @param inputs.metadata - Vault display metadata (name, description, curator info).
+     * @param inputs.metadata - Vault display metadata (name, description, curator info).
+     * @param inputs.coinMetadataId - Coin metadata object id obtained from create vault cap tx
+     * @param inputs.treasuryCapId - Treasury cap object id obtained from create vault cap tx
+     * @param inputs.collateralCoinType - Collateral coin type for deposits.
+     * @param inputs.lockPeriodMs - Lock-in period for deposits in milliseconds.
+     * @param inputs.performanceFeePercentage - Fraction of profits taken as curator fee.
+     * @param inputs.forceWithdrawDelayMs - Delay before forced withdrawals can be processed.
+     * @param inputs.isSponsoredTx - Whether this tx is sponsored (gas 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 {@link SdkTransactionResponse} with `tx`.
+     */
+    getCreateVaultTx(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const { tx } = inputs, otherInputs = __rest(inputs, ["tx"]);
+            return this.fetchApiTxObject("vault/transactions/create-vault", Object.assign(Object.assign({}, otherInputs), { txKind: yield ((_a = this.Provider) === null || _a === void 0 ? void 0 : _a.Transactions().fetchBase64TxKindFromTx({ tx })) }), undefined, {
+                txKind: true,
+            });
+        });
+    }
+    // =========================================================================
+    //  Builder Codes Transactions
+    // =========================================================================
+    /**
+     * Build a transaction to create an integrator configuration.
+     *
+     * This endpoint creates a transaction that allows a user to grant permission to an
+     * integrator to receive fees on orders placed on their behalf. The user specifies
+     * a maximum taker fee that the integrator can charge. The integrator can then
+     * include their address and fee (up to the maximum) when placing orders for the user.
+     *
+     * The resulting transaction must be signed by the account owner and executed on-chain.
+     *
+     * @param inputs - {@link ApiPerpetualsBuilderCodesCreateIntegratorConfigTxBody}.
+     * @returns {@link SdkTransactionResponse} with `tx`.
+     *
+     * @example
+     * ```ts
+     * const tx = await perps.getCreateBuilderCodeIntegratorConfigTx({
+     *   accountId: 123n,
+     *   integratorAddress: "0x...",
+     *   maxTakerFee: 0.001, // 0.1% max fee
+     * });
+     * ```
+     */
+    getCreateBuilderCodeIntegratorConfigTx(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApiTxObject("builder-codes/transactions/create-integrator-config", inputs, undefined, {
+                txKind: true,
+            });
+        });
+    }
+    /**
+     * Build a transaction to remove an integrator configuration.
+     *
+     * This endpoint creates a transaction that removes an integrator's approval to
+     * collect fees on orders placed on behalf of the user. Once revoked, the integrator
+     * will no longer be able to submit orders with integrator fees for this account.
+     * The user can re-approve the integrator at any time by calling
+     * {@link getCreateIntegratorConfigTx} again.
+     *
+     * The resulting transaction must be signed by the account owner and executed on-chain.
+     *
+     * @param inputs - {@link ApiPerpetualsBuilderCodesRemoveIntegratorConfigTxBody}.
+     * @returns {@link SdkTransactionResponse} with `tx`.
+     *
+     * @example
+     * ```ts
+     * const tx = await perps.getRemoveBuilderCodeIntegratorConfigTx({
+     *   accountId: 123n,
+     *   integratorAddress: "0x...",
+     * });
+     * ```
+     */
+    getRemoveBuilderCodeIntegratorConfigTx(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApiTxObject("builder-codes/transactions/remove-integrator-config", inputs, undefined, {
+                txKind: true,
+            });
+        });
+    }
+    /**
+     * Build a transaction to initialize an integrator fee vault for a specific market.
+     *
+     * This endpoint creates a transaction that initializes a vault where an integrator's
+     * fees will accumulate for a specific market (clearing house). This is a one-time
+     * setup operation that must be performed before the integrator can claim fees from
+     * that market. Once created, the vault will automatically collect fees as the
+     * integrator submits orders on behalf of users in that market.
+     *
+     * The resulting transaction must be signed by the integrator and executed on-chain.
+     *
+     * @param inputs - {@link ApiPerpetualsBuilderCodesCreateIntegratorVaultTxBody}.
+     * @returns {@link SdkTransactionResponse} with `tx`.
+     *
+     * @example
+     * ```ts
+     * const tx = await perps.getCreateBuilderCodeIntegratorVaultTx({
+     *   marketId: "0x...",
+     *   integratorAddress: "0x...",
+     * });
+     * ```
+     */
+    getCreateBuilderCodeIntegratorVaultTx(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApiTxObject("builder-codes/transactions/create-integrator-vault", inputs, undefined, {
+                txKind: true,
+            });
+        });
+    }
+    /**
+     * Build a transaction to claim accumulated integrator fees from a vault.
+     *
+     * This endpoint creates a transaction that allows an integrator to claim the fees
+     * they have earned from orders placed on behalf of users. Fees accumulate in a vault
+     * specific to each market (clearing house) and can be claimed at any moment by the
+     * integrator. The fees are proportional to the taker volume generated by the users'
+     * orders that the integrator submitted.
+     *
+     * If a `recipientAddress` is provided, the claimed fees will be automatically
+     * transferred to that address. Otherwise, the coin output is exposed as a transaction
+     * argument for further use in the transaction.
+     *
+     * The resulting transaction must be signed by the integrator and executed on-chain.
+     *
+     * @param inputs - {@link ApiPerpetualsBuilderCodesClaimIntegratorVaultFeesTxBody}.
+     * @returns {@link ApiPerpetualsBuilderCodesClaimIntegratorVaultFeesTxResponse} containing
+     *   `txKind` and optionally `coinOutArg`.
+     *
+     * @example
+     * ```ts
+     * // Claim with automatic transfer to recipient
+     * const response = await perps.getClaimBuilderCodeIntegratorVaultFeesTx({
+     *   marketId: "0x...",
+     *   integratorAddress: "0x...",
+     *   recipientAddress: "0x...",
+     * });
+     *
+     * // Claim with coin output for further use
+     * const response = await perps.getClaimBuilderCodeIntegratorVaultFeesTx({
+     *   marketId: "0x...",
+     *   integratorAddress: "0x...",
+     * });
+     * // response.coinOutArg can be used in subsequent transaction commands
+     * ```
+     */
+    getClaimBuilderCodeIntegratorVaultFeesTx(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApiTxObject("builder-codes/transactions/claim-integrator-vault-fees", inputs, undefined, {
+                txKind: true,
+            });
         });
     }
     // =========================================================================
-    //  Public Static Functions
+    //  Builder Codes Inspections
     // =========================================================================
+    /**
+     * Fetch integrator configuration for a specific account and integrator.
+     *
+     * This endpoint queries whether an integrator has been approved by an account to collect
+     * fees on orders placed on behalf of the account. If approved, it returns the maximum
+     * taker fee the integrator is authorized to charge. This information is useful for:
+     * - Verifying integrator permissions before placing orders
+     * - Displaying authorized integrators and their fee limits in UIs
+     * - Validating that an integrator's requested fee doesn't exceed the approved maximum
+     *
+     * @param inputs - {@link ApiPerpetualsBuilderCodesIntegratorConfigBody}.
+     * @returns {@link ApiPerpetualsBuilderCodesIntegratorConfigResponse} containing
+     *   `maxTakerFee` and `exists` flag.
+     *
+     * @example
+     * ```ts
+     * const config = await perps.getBuilderCodeIntegratorConfig({
+     *   accountId: 123n,
+     *   integratorAddress: "0x...",
+     * });
+     *
+     * if (config.exists) {
+     *   console.log(`Integrator is approved with max fee: ${config.maxTakerFee}`);
+     * } else {
+     *   console.log("Integrator is not approved for this account");
+     * }
+     * ```
+     */
+    getBuilderCodeIntegratorConfig(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("builder-codes/integrator-config", inputs);
+        });
+    }
+    /**
+     * Fetch accumulated integrator vault fees across multiple markets.
+     *
+     * This endpoint queries the total fees an integrator has earned and accumulated in their
+     * vaults across one or more markets (clearing houses). Integrators earn fees proportional
+     * to the taker volume generated by orders they submit on behalf of users. These fees
+     * accumulate in per-market vaults and can be claimed at any time using
+     * {@link getClaimIntegratorVaultFeesTx}.
+     *
+     * This information is useful for:
+     * - Displaying total claimable fees to integrators in dashboards
+     * - Monitoring fee accrual across different markets
+     * - Determining which markets have fees ready to be claimed
+     *
+     * @param inputs - {@link ApiPerpetualsBuilderCodesIntegratorVaultsBody}.
+     * @returns {@link ApiPerpetualsBuilderCodesIntegratorVaultsResponse} containing
+     *   a vector of market vault data with accumulated fees.
+     *
+     * @example
+     * ```ts
+     * const vaultFees = await perps.getBuilderCodeIntegratorVaults({
+     *   marketIds: ["0x...BTCUSD", "0x...SUIUSD"],
+     *   integratorAddress: "0x...",
+     * });
+     *
+     * for (const vault of vaultFees.integratorVaults) {
+     *   console.log(`Market ${vault.marketId}: ${vault.fees} collateral units claimable`);
+     * }
+     *
+     * const totalFees = vaultFees.integratorVaults.reduce((sum, vault) => sum + vault.fees, 0);
+     * console.log(`Total claimable: ${totalFees}`);
+     * ```
+     */
+    getBuilderCodeIntegratorVaults(inputs) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.fetchApi("builder-codes/integrator-vaults", inputs);
+        });
+    }
     // =========================================================================
-    //  Helpers
+    //  Public Static Helpers
     // =========================================================================
+    /**
+     * Determine the logical order side (Bid/Ask) from a signed base asset amount.
+     *
+     * @param inputs.baseAssetAmount - Position base size. Positive/zero => Bid (long), negative => Ask (short).
+     * @returns {@link PerpetualsOrderSide}.
+     */
     static positionSide(inputs) {
-        const baseAmount = iFixedUtils_1.IFixedUtils.numberFromIFixed(inputs.baseAssetAmount);
+        const baseAmount = inputs.baseAssetAmount;
         const isLong = Math.sign(baseAmount);
         const side = isLong >= 0 ? types_1.PerpetualsOrderSide.Bid : types_1.PerpetualsOrderSide.Ask;
         return side;
     }
-    static orderPrice(inputs) {
+    /**
+     * Compute the effective trade price from a {@link FilledTakerOrderEvent}.
+     *
+     * Uses the ratio: `quoteAssetDelta / baseAssetDelta`.
+     *
+     * @param inputs.orderEvent - Filled taker order event.
+     * @returns Trade price.
+     */
+    static orderPriceFromEvent(inputs) {
         const { orderEvent } = inputs;
-        return (iFixedUtils_1.IFixedUtils.numberFromIFixed(orderEvent.quoteAssetDelta) /
-            iFixedUtils_1.IFixedUtils.numberFromIFixed(orderEvent.baseAssetDelta));
+        return orderEvent.quoteAssetDelta / orderEvent.baseAssetDelta;
+    }
+    /**
+     * Extract the floating-point price from an encoded order ID.
+     *
+     * Internally uses {@link PerpetualsOrderUtils.price} and converts the fixed-point
+     * {@link PerpetualsOrderPrice} into a `number`.
+     *
+     * @param inputs.orderId - Encoded order ID.
+     * @returns Price as a `number`.
+     */
+    static orderPriceFromOrderId(inputs) {
+        const { orderId } = inputs;
+        const orderPrice = utils_1.PerpetualsOrderUtils.price(orderId);
+        return this.orderPriceToPrice({ orderPrice });
     }
+    /**
+     * Convert a fixed-point lot/tick size (9 decimals) to a `number`.
+     *
+     * @param lotOrTickSize - Fixed-point size as `bigint`.
+     * @returns Floating-point size.
+     */
     static lotOrTickSizeToNumber(lotOrTickSize) {
         return Number(lotOrTickSize) / fixedUtils_1.FixedUtils.fixedOneN9;
     }
+    /**
+     * Convert a floating-point lot/tick size to its fixed-point representation (9 decimals).
+     *
+     * @param lotOrTickSize - Floating-point size.
+     * @returns Fixed-point size as `bigint`.
+     */
     static lotOrTickSizeToBigInt(lotOrTickSize) {
         return BigInt(Math.round(lotOrTickSize * fixedUtils_1.FixedUtils.fixedOneN9));
     }
     // =========================================================================
-    //  Calculations
+    //  Websocket
     // =========================================================================
-    static calcEntryPrice(inputs) {
-        const { baseAssetAmount, quoteAssetNotionalAmount } = inputs;
-        const denominator = utils_1.Casting.IFixed.numberFromIFixed(baseAssetAmount);
-        if (!denominator)
-            return 0;
-        return Math.abs(utils_1.Casting.IFixed.numberFromIFixed(quoteAssetNotionalAmount) /
-            denominator);
+    /**
+     * Open the main updates websocket: `/perpetuals/ws/updates`.
+     *
+     * The stream emits {@link PerpetualsWsUpdatesResponseMessage} envelopes and supports
+     * multiple subscription types. This method returns a small controller with
+     * convenience subscribe/unsubscribe functions.
+     *
+     * Subscription types supported by the controller:
+     * - `market`: market state updates
+     * - `user`: user account updates (optionally including stop orders)
+     * - `oracle`: oracle price updates
+     * - `orderbook`: orderbook deltas
+     * - `marketOrders`: public market trades/orders
+     * - `userOrders`: user trade/order events
+     * - `userCollateralChanges`: user collateral change events
+     * - `topOfOrderbook`: bucketed orderbook snapshots (top of orderbook)
+     *
+     * @param args.onMessage - Handler for parsed messages from the websocket.
+     * @param args.onOpen - Optional handler for the `open` event.
+     * @param args.onError - Optional handler for the `error` event.
+     * @param args.onClose - Optional handler for the `close` event.
+     *
+     * @returns A controller object containing:
+     * - `ws`: underlying {@link WebSocket}
+     * - subscribe/unsubscribe helpers for each subscription type
+     * - `close()`: closes the websocket
+     */
+    openUpdatesWebsocketStream(args) {
+        const { onMessage, onOpen, onError, onClose } = args;
+        const ctl = this.openWsStream({
+            path: "ws/updates",
+            onMessage,
+            onOpen,
+            onError,
+            onClose,
+        });
+        /**
+         * Subscription helpers
+         *
+         * Each helper sends a structured subscription message of the form:
+         * `{ action: "subscribe" | "unsubscribe", subscriptionType: { ... } }`
+         */
+        const subscribeMarket = ({ marketId, }) => ctl.send({
+            action: "subscribe",
+            subscriptionType: { market: { marketId } },
+        });
+        const unsubscribeMarket = ({ marketId, }) => ctl.send({
+            action: "unsubscribe",
+            subscriptionType: { market: { marketId } },
+        });
+        const subscribeUser = ({ accountId, withStopOrders, }) => ctl.send({
+            action: "subscribe",
+            subscriptionType: { user: { accountId, withStopOrders } },
+        });
+        const unsubscribeUser = ({ accountId, withStopOrders, }) => ctl.send({
+            action: "unsubscribe",
+            subscriptionType: { user: { accountId, withStopOrders } },
+        });
+        const subscribeOracle = ({ marketId, }) => ctl.send({
+            action: "subscribe",
+            subscriptionType: { oracle: { marketId } },
+        });
+        const unsubscribeOracle = ({ marketId, }) => ctl.send({
+            action: "unsubscribe",
+            subscriptionType: { oracle: { marketId } },
+        });
+        const subscribeOrderbook = ({ marketId, }) => ctl.send({
+            action: "subscribe",
+            subscriptionType: { orderbook: { marketId } },
+        });
+        const unsubscribeOrderbook = ({ marketId, }) => ctl.send({
+            action: "unsubscribe",
+            subscriptionType: { orderbook: { marketId } },
+        });
+        const subscribeMarketOrders = ({ marketId, }) => ctl.send({
+            action: "subscribe",
+            subscriptionType: { marketOrders: { marketId } },
+        });
+        const unsubscribeMarketOrders = ({ marketId, }) => ctl.send({
+            action: "unsubscribe",
+            subscriptionType: { marketOrders: { marketId } },
+        });
+        const subscribeUserOrders = ({ accountId, }) => ctl.send({
+            action: "subscribe",
+            subscriptionType: { userOrders: { accountId } },
+        });
+        const unsubscribeUserOrders = ({ accountId, }) => ctl.send({
+            action: "unsubscribe",
+            subscriptionType: { userOrders: { accountId } },
+        });
+        const subscribeUserCollateralChanges = ({ accountId, }) => ctl.send({
+            action: "subscribe",
+            subscriptionType: { userCollateralChanges: { accountId } },
+        });
+        const unsubscribeUserCollateralChanges = ({ accountId, }) => ctl.send({
+            action: "unsubscribe",
+            subscriptionType: { userCollateralChanges: { accountId } },
+        });
+        const subscribeTopOfOrderbook = ({ marketId, priceBucketSize, bucketsNumber, }) => ctl.send({
+            action: "subscribe",
+            subscriptionType: {
+                topOfOrderbook: {
+                    marketId,
+                    priceBucketSize,
+                    bucketsNumber,
+                },
+            },
+        });
+        const unsubscribeTopOfOrderbook = ({ marketId, priceBucketSize, bucketsNumber, }) => ctl.send({
+            action: "unsubscribe",
+            subscriptionType: {
+                topOfOrderbook: {
+                    marketId,
+                    priceBucketSize,
+                    bucketsNumber,
+                },
+            },
+        });
+        return {
+            ws: ctl.ws,
+            subscribeMarket,
+            unsubscribeMarket,
+            subscribeUser,
+            unsubscribeUser,
+            subscribeOracle,
+            unsubscribeOracle,
+            subscribeOrderbook,
+            unsubscribeOrderbook,
+            subscribeMarketOrders,
+            unsubscribeMarketOrders,
+            subscribeUserOrders,
+            unsubscribeUserOrders,
+            subscribeUserCollateralChanges,
+            unsubscribeUserCollateralChanges,
+            subscribeTopOfOrderbook,
+            unsubscribeTopOfOrderbook,
+            close: ctl.close,
+        };
+    }
+    /**
+     * 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 A controller containing the raw websocket and a `close()` helper.
+     *
+     * @example
+     * ```ts
+     * const stream = perps.openMarketCandlesWebsocketStream({
+     *   marketId: "0x...",
+     *   intervalMs: 60_000,
+     *   onMessage: ({ lastCandle }) => console.log(lastCandle),
+     * });
+     * ```
+     */
+    openMarketCandlesWebsocketStream(args) {
+        const { marketId, intervalMs, onMessage, onOpen, onError, onClose } = args;
+        const path = `ws/market-candles/${encodeURIComponent(marketId)}/${intervalMs}`;
+        const ctl = this.openWsStream({
+            path,
+            onMessage,
+            onOpen,
+            onError,
+            onClose,
+        });
+        return {
+            ws: ctl.ws,
+            close: ctl.close,
+        };
     }
 }
 exports.Perpetuals = Perpetuals;
-_a = Perpetuals;
 // =========================================================================
 //  Constants
 // =========================================================================
-Perpetuals.OrderUtils = utils_2.PerpetualsOrderUtils;
+/**
+ * Helper namespace for order-specific utilities such as parsing order IDs,
+ * extracting price bits, etc.
+ *
+ * This is a direct alias of {@link PerpetualsOrderUtils}.
+ */
+Perpetuals.OrderUtils = utils_1.PerpetualsOrderUtils;
+/**
+ * Convert a floating-point price into a fixed-point {@link PerpetualsOrderPrice}
+ * using 9 decimal places of precision.
+ *
+ * @param inputs.price - Price as a float.
+ * @returns Fixed-point order price.
+ */
 Perpetuals.priceToOrderPrice = (inputs) => {
-    const { price, lotSize, tickSize } = inputs;
-    const priceFixed = fixedUtils_1.FixedUtils.directUncast(price);
-    // convert f18 to b9 (assuming the former is positive)
-    const price9 = priceFixed / fixedUtils_1.FixedUtils.fixedOneB9;
-    const denominator = fixedUtils_1.FixedUtils.fixedOneB9 /
-        (typeof lotSize === "number"
-            ? _a.lotOrTickSizeToBigInt(lotSize)
-            : lotSize);
-    if (denominator <= BigInt(0))
-        return BigInt(0);
-    return (price9 /
-        (typeof tickSize === "number"
-            ? _a.lotOrTickSizeToBigInt(tickSize)
-            : tickSize) /
-        denominator);
+    const { price } = inputs;
+    return BigInt(Math.round(price * fixedUtils_1.FixedUtils.fixedOneN9));
 };
+/**
+ * Convert a fixed-point {@link PerpetualsOrderPrice} to a float price.
+ *
+ * @param inputs.orderPrice - Fixed-point order price.
+ * @returns Price as a float.
+ */
 Perpetuals.orderPriceToPrice = (inputs) => {
-    const { orderPrice, lotSize, tickSize } = inputs;
-    const temp = fixedUtils_1.FixedUtils.fixedOneB9 /
-        (typeof lotSize === "number"
-            ? _a.lotOrTickSizeToBigInt(lotSize)
-            : lotSize);
-    return fixedUtils_1.FixedUtils.directCast(orderPrice *
-        (typeof tickSize === "number"
-            ? _a.lotOrTickSizeToBigInt(tickSize)
-            : tickSize) *
-        temp *
-        fixedUtils_1.FixedUtils.fixedOneB9);
+    const { orderPrice } = inputs;
+    return Number(orderPrice) / fixedUtils_1.FixedUtils.fixedOneN9;
 };
+/**
+ * Infer the order side from an encoded order ID.
+ *
+ * @param orderId - Encoded order ID.
+ * @returns {@link PerpetualsOrderSide}.
+ */
 Perpetuals.orderIdToSide = (orderId) => {
-    return _a.OrderUtils.isAsk(orderId)
+    return Perpetuals.OrderUtils.isAsk(orderId)
         ? types_1.PerpetualsOrderSide.Ask
         : types_1.PerpetualsOrderSide.Bid;
 };
+/**
+ * Construct a collateral-specialized Move event type string.
+ *
+ * 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.
+ */
+Perpetuals.eventTypeForCollateral = (inputs) => {
+    return `${inputs.eventType}<${inputs.collateralCoinType}>`;
+};