@augustdigital/sdk 8.3.2 → 8.6.0

package/lib/main.js

@@ -1,4 +1,9 @@
 "use strict";
+/**
+ * The main August SDK class.
+ *
+ * @module AugustSDK
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -45,11 +50,41 @@ const core_1 = require("./core");
 const vaults_1 = require("./modules/vaults");
 const analytics_1 = require("./core/analytics");
 const sub_accounts_1 = require("./modules/sub-accounts");
+const api_1 = require("./modules/api");
+/**
+ * Main SDK class for interacting with August Digital vaults and services.
+ * Provides unified access to EVM, Solana, Sui, and Stellar blockchain adapters.
+ */
 class AugustSDK extends core_1.AugustBase {
+    vaults;
+    subaccounts;
+    api;
+    solana;
+    sui;
+    stellar;
+    evm;
+    /**
+     * Initialize the August SDK with provider configuration.
+     * Automatically sets up EVM adapter and optionally initializes Solana if RPC URL is provided.
+     */
     constructor(baseConfig) {
         super(baseConfig);
+        // @todo: change this later when august key is required
         this.authorized = true;
+        // EVM adapter is always available
         this.evm = new evm_1.default();
+        // @solana: handle solana service initialization
+        //
+        // Two accepted entry points, treated as exclusive sources so url+network
+        // can never come from different configs:
+        //   1) `baseConfig.solana = { rpcUrl, network }` — preferred. Both fields
+        //      come from the same place; the caller controls the network.
+        //   2) `baseConfig.providers[-1] = rpcUrl` — legacy "Solana as another
+        //      EVM chain" shape. Network is derived from the URL substring.
+        //
+        // Without one of these `this.solana` stays undefined and every Solana
+        // vault is silently dropped from getVaults / getVaultPositions (the
+        // filter in modules/vaults/main.ts gates on `!!this.solanaService`).
         const solanaConfig = (() => {
             if (baseConfig.solana?.rpcUrl) {
                 return {
@@ -76,24 +111,50 @@ class AugustSDK extends core_1.AugustBase {
         this.stellar = new stellar_1.default();
         this.vaults = new vaults_1.AugustVaults(baseConfig, this.solana, this.sui);
         this.subaccounts = new sub_accounts_1.AugustSubAccounts(baseConfig);
+        this.api = new api_1.AugustApi();
+        // Instrument all SDK methods for analytics tracking
         (0, analytics_1.instrumentClass)(this, () => this.activeNetwork?.chainId);
         (0, analytics_1.instrumentClass)(this.evm, () => this.activeNetwork?.chainId);
         (0, analytics_1.instrumentClass)(this.sui, () => this.activeNetwork?.chainId);
         (0, analytics_1.instrumentClass)(this.stellar, () => core_1.SPECIAL_CHAINS.stellar?.chainId);
         (0, analytics_1.instrumentClass)(this.vaults, () => this.activeNetwork?.chainId);
         (0, analytics_1.instrumentClass)(this.subaccounts, () => this.activeNetwork?.chainId);
+        (0, analytics_1.instrumentClass)(this.api, () => this.activeNetwork?.chainId);
     }
+    /**
+     * Get the Sub-Accounts module instance.
+     */
     get subAccountsModule() {
         return this.subaccounts;
     }
+    /**
+     * Get the Vaults module instance.
+     */
     get vaultsModule() {
         return this.vaults;
     }
+    /**
+     * Get the backend API module instance ({@link AugustApi}) — read-only
+     * access to backend-computed data with no on-chain equivalent
+     * (unrealized-PnL series).
+     */
+    get apiModule() {
+        return this.api;
+    }
+    /**
+     * Switch the active network for vault operations.
+     * Updates the SDK's active chain and RPC provider.
+     */
     switchNetwork(chainId) {
         super.switchNetwork(chainId);
         this.vaults.switchNetwork(chainId);
+        // Track network switch for analytics
         (0, analytics_1.trackNetworkSwitch)(chainId);
     }
+    /**
+     * Set the active wallet address for tracking user-specific vault data.
+     * Updates monitoring headers with the wallet address.
+     */
     updateWallet(address) {
         if (!address)
             return;
@@ -102,12 +163,25 @@ class AugustSDK extends core_1.AugustBase {
         }
         this.vaults.updateWallet(address);
     }
+    /**
+     * Clear the active wallet address from the SDK state and monitoring headers.
+     */
     clearWallet() {
         if (this.monitoring) {
             this.monitoring['x-user-id'] = undefined;
         }
         this.vaults.clearWallet();
     }
+    /**
+     * Pricing and Market Data
+     */
+    /**
+     * Get the current USD price of a token by symbol or contract address.
+     * Falls back to CoinGecko if primary price source fails.
+     *
+     * @param symbol - Token symbol or contract address
+     * @returns Current price in USD
+     */
     async getPrice(symbol) {
         if (!this.authorized)
             throw new Error('Not authorized.');
@@ -115,90 +189,314 @@ class AugustSDK extends core_1.AugustBase {
             throw new Error(`Symbol input parameter is not defined.`);
         return await (0, core_1.fetchTokenPrice)(symbol, null, this.keys?.coingecko);
     }
+    /**
+     * Vault Data and Operations
+     */
+    /**
+     * Fetch all available vaults across configured networks.
+     * Optionally filter by chain IDs and include loan/allocation data.
+     * @param options - Configuration for filtering and enriching vault data
+     * @returns Array of vault objects with metadata and optional position data
+     */
     async getVaults(options) {
         return await this.vaults.getVaults(options);
     }
     async getTotalDeposited(options) {
         return await this.vaults.getTotalDeposited(options);
     }
+    /**
+     * Fetch all available vaults across configured networks.
+     * Optionally filter by chain IDs and include loan/allocation data.
+     * @param options - Configuration for filtering and enriching vault data
+     * @returns Array of vault objects with metadata and optional position data
+     */
     async vaultDeposit(signer, options) {
         return await this.vaults.vaultDeposit(signer, options);
     }
+    /**
+     * Fetch detailed information for a specific vault.
+     * @param props - Vault address, chain ID, and optional enrichment options
+     * @returns Single vault object with full metadata
+     */
     async getVault(props) {
         return await this.vaults.getVault(props);
     }
+    /**
+     * Get active loans deployed from a vault.
+     * @param props - Vault address and chain ID
+     * @returns Array of loan details including borrower, principal, APR
+     */
     async getVaultLoans(props) {
         return await this.vaults.getVaultLoans(props);
     }
+    /**
+     * Get vault asset allocations across DeFi protocols, CeFi, and OTC positions.
+     * @param props - Vault address and chain ID
+     * @returns Detailed breakdown of vault allocations by category
+     */
     async getVaultAllocations(props) {
         return await this.vaults.getVaultAllocations(props);
     }
+    /**
+     * Get current or historical APY for a vault.
+     *
+     * @deprecated use getVaultHistoricalTimeseries instead
+     *
+     * @param props - Vault address and optional historical lookback period
+     * @returns APY data including rewards breakdown
+     */
     async getVaultApy(props) {
         return await this.vaults.getVaultApy(props);
     }
+    /**
+     * Get current or historical TVL for a vault.
+     * @param props - Vault address and optional historical parameters
+     * @returns TVL in vault's base asset units
+     */
     async getVaultTvl(props) {
         return await this.vaults.getVaultTvl(props);
     }
+    /**
+     * Get historical timeseries data for a vault.
+     * @param props - Vault address and optional number of days
+     * @returns Historical timeseries data with TVL, APY, PnL, share price, and other metrics
+     */
     async getVaultHistoricalTimeseries(props) {
         return await this.vaults.getVaultHistoricalTimeseries(props);
     }
+    /**
+     * Get the timestamp when yield was last realized for a vault.
+     * @param props - Vault address and optional chain ID
+     * @returns Timestamp (Unix timestamp in seconds) when yield was last realized
+     */
     async getYieldLastRealizedOn(props) {
         return await this.vaults.getYieldLastRealizedOn(props);
     }
+    /**
+     * Get redemption requests that are ready to be claimed.
+     * @param props - Vault address, chain ID, and optional wallet filter
+     * @returns Array of available redemption requests with amounts and timestamps
+     */
     async getVaultAvailableRedemptions(props) {
         return await this.vaults.getVaultAvailableRedemptions(props);
     }
+    /**
+     * Get historical redemption requests for a vault (settled, cancelled,
+     * pending-but-out-of-window), optionally filtered to one wallet.
+     *
+     * @param props - Vault address, chain ID, optional wallet, and an
+     *   optional `lookbackBlocks` for how far back to scan.
+     * @returns Historical redemption records, newest first.
+     */
     async getVaultRedemptionHistory(props) {
         return await this.vaults.getVaultRedemptionHistory(props);
     }
+    /**
+     * Get user positions across vaults including shares and claimable redemptions.
+     * Supports both EVM and Solana vaults.
+     * @param props - Wallet address, chain ID, and optional vault filter
+     * @returns Array of positions with balances and pending redemptions
+     */
     async getVaultPositions(props) {
         return await this.vaults.getVaultPositions(props);
     }
+    /**
+     * Get user's historical vault interactions including deposits and withdrawals.
+     * @param props - Wallet address and optional vault/chain filters
+     * @returns Array of historical transactions with amounts and timestamps
+     */
     async getVaultUserHistory(props) {
         return await this.vaults.getUserHistory(props);
     }
+    /**
+     * Get user's vault share transfer history from subgraph.
+     * @param props - Wallet address and optional vault/chain filters
+     * @returns Array of transfer events
+     */
     async getVaultUserTransfers(props) {
         return await this.vaults.getUserTransfers(props);
     }
+    /**
+     * Get lifetime PnL for a user in a specific vault.
+     * Calculates realized and unrealized PnL based on deposit/withdrawal history and current position.
+     * @param props - Vault address, wallet address, and optional chain ID
+     * @returns Lifetime PnL data including realized and unrealized PnL in both native token and USD
+     */
     async getVaultUserLifetimePnl(props) {
         return await this.vaults.getVaultUserLifetimePnl(props);
     }
+    /**
+     * Get PnL for a vault (vault-level, not user-specific).
+     * Returns the vault's overall profit and loss across all users.
+     * @param props - Vault address and optional chain ID
+     * @returns Vault PnL in USD and notional value
+     */
     async getVaultPnl(props) {
         return await this.vaults.getVaultPnl(props);
     }
+    /**
+     * Get user's staking positions for vault receipt tokens.
+     * @param props - Wallet address and optional chain ID
+     * @returns Array of staking positions with rewards
+     */
     async getVaultStakingPositions(props) {
         return await this.vaults.getStakingPositions(props.wallet, props.chainId);
     }
+    /**
+     * Get the borrower's health factor by vault.
+     *
+     * Pass `vault` whenever the caller knows which pool it cares about — it
+     * skips the all-vaults cross-chain fanout and only reads the loans for
+     * that one pool. The response map is keyed by **lowercased** vault
+     * address; look entries up with `address.toLowerCase()`.
+     *
+     * @param props.chainId Optional chain to scope the read to.
+     * @param props.vault Optional vault address. When provided alongside
+     *   `chainId`, only that vault's borrower-health-factor data is fetched.
+     * @returns Object containing the borrower's health factor by vault.
+     */
     async getVaultBorrowerHealthFactor(props) {
         return await this.vaults.getVaultBorrowerHealthFactor(props?.chainId, props?.vault);
     }
+    /**
+     * Get user points from the backend API.
+     * This fetches processed points data directly from the backend,
+     * removing the need for client-side points calculation.
+     * @param userAddress - User wallet address
+     * @returns Points data from the backend API
+     */
     async getUserPoints(userAddress) {
         return await this.vaults.getUserPoints(userAddress);
     }
+    /**
+     * Register a user for the points program, authenticated by a wallet signature.
+     *
+     * The caller produces a personal_sign signature over a canonical message
+     * containing the user address, referrer (or `"none"`), chain, nonce, and
+     * expiry — see `AugustVaults.registerUserForPoints` for the exact template.
+     *
+     * @param userAddress - EVM wallet address being registered.
+     * @param referrerAddress - Optional EVM referrer address.
+     * @param chainId - Chain on which the wallet signed; powers the EIP-1271
+     *   fallback for smart-contract wallets and pins the signature cross-chain.
+     * @param signature - 0x-prefixed personal_sign signature over the canonical message.
+     * @param nonce - Single-use random string (8–128 chars).
+     * @param expiry - Unix seconds; must be in the future, within the backend's TTL.
+     * @returns Raw `Response` from the backend.
+     */
     async registerUserForPoints(userAddress, referrerAddress, chainId, signature, nonce, expiry) {
         return await this.vaults.registerUserForPoints(userAddress, referrerAddress, chainId, signature, nonce, expiry);
     }
+    /**
+     * Fetch the points leaderboard data.
+     * @param params - Optional parameters for pagination and sorting
+     * @returns Leaderboard response data
+     */
     async fetchPointsLeaderboard(params) {
         return await this.vaults.fetchPointsLeaderboard(params);
     }
+    /**
+     * Fetch the historical unrealized-PnL series for a vault, newest first.
+     * Delegates to {@link AugustApi.getVaultUnrealizedPnlHistory} — see it for
+     * parameter semantics and thrown errors.
+     */
+    async getVaultUnrealizedPnlHistory(params) {
+        return await this.api.getVaultUnrealizedPnlHistory(params);
+    }
+    /**
+     * Fetch the latest unrealized-PnL snapshot for every tracked vault.
+     * Delegates to {@link AugustApi.getLatestUnrealizedPnl} — see it for
+     * return shape and thrown errors.
+     */
+    async getLatestUnrealizedPnl() {
+        return await this.api.getLatestUnrealizedPnl();
+    }
+    /**
+     * Get annualized APY metrics for a vault.
+     *
+     * Supported Vaults: cUSDO, tETH, wstETH, rsETH
+     *
+     * @deprecated The `hgETH30dLiquidAPY` and `hgETH7dLiquidAPY` response fields are deprecated.
+     * These fields will be removed on 2026-01-01.
+     * Use `liquidAPY30Day` and `liquidAPY7Day` fields instead.
+     *
+     * @param props - Vault address
+     * @returns Annualized APY data including liquidity APY
+     */
     async getVaultAnnualizedApy(props) {
         return await this.vaults.getVaultAnnualizedApy(props.vault);
     }
+    /**
+     * Get summary data for a vault (name, type, chain, recent returns).
+     * @param props - Vault address
+     * @returns Vault summary data
+     */
     async getVaultSummary(props) {
         return await this.vaults.getVaultSummary(props.vault);
     }
+    /**
+     * Get withdrawal summary and pending queue for a vault.
+     * @param props - Vault address and optional chain ID
+     * @returns Withdrawal summary and pending queue
+     */
     async getVaultWithdrawals(props) {
         return await this.vaults.getVaultWithdrawals(props.vault, props.chainId);
     }
+    /**
+     * Preview the amount of assets that would be received for redeeming shares (queued redemption).
+     * @param props - Vault contract address, shares amount, and optional chain ID
+     * @returns The amount of assets as {@link INormalizedNumber}
+     */
     async previewRedemption(props) {
         return await this.vaults.previewRedemption(props);
     }
+    /**
+     * Query LayerZero USDC deposits from the august-layerzero subgraphs.
+     * Returns all deposits or filters by sender wallet address if provided.
+     *
+     * **Important Notes:**
+     * - Only deposit transactions are tracked (not withdrawals or other operations)
+     * - Sender and recipient addresses are stored in bytes32 format in the subgraph
+     * - Timestamps are available from the subgraph
+     *
+     * **Supported Vaults:**
+     * - `upusdc`: 0x80E1048eDE66ec4c364b4F22C8768fc657FF6A42
+     * - `coreusdc`: 0xE9B725010A9E419412ed67d0fA5f3A5f40159D32
+     * - `earnausd`: 0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA
+     *
+     * @param props - Receipt token type ('upusdc', 'coreusdc', or 'earnausd') and optional wallet address to filter by sender
+     * @returns Array of deposit events with the following structure:
+     * - `assetAmt`: Amount of assets deposited (as string)
+     * - `shareAmt`: Amount of shares received (as string)
+     * - `sender`: Sender address in bytes32 format
+     * - `recipient`: Recipient address in bytes32 format
+     * - `dstEid`: Destination endpoint ID (LayerZero chain identifier)
+     * - `transactionHash_`: Transaction hash
+     *
+     * @throws Error if receipt token is invalid or GraphQL request fails
+     *
+     * @example
+     * ```typescript
+     * // Get all coreUSDC deposits
+     * const allDeposits = await sdk.getLayerZeroDeposits({
+     *   receiptToken: 'coreusdc'
+     * });
+     *
+     * // Get deposits for a specific wallet
+     * const userDeposits = await sdk.getLayerZeroDeposits({
+     *   receiptToken: 'upusdc',
+     *   wallet: '0xb0280B58F541131b29D1B33319CD440a99eA0305'
+     * });
+     * ```
+     */
     async getLayerZeroDeposits(props) {
+        // Runtime validation for receipt token
         const validTokens = ['upusdc', 'coreusdc', 'earnausd'];
         if (!validTokens.includes(props.receiptToken)) {
             throw new Error(`Invalid receiptToken: ${props.receiptToken}. Must be 'upusdc', 'coreusdc', or 'earnausd'.`);
         }
         const { queryLayerZeroDeposits } = await Promise.resolve().then(() => __importStar(require('./services/layerzero/deposits')));
+        // Map receipt token to vault key
         const vaultKeyMap = {
             upusdc: 'upUSDC',
             coreusdc: 'coreUSDC',
@@ -207,6 +505,20 @@ class AugustSDK extends core_1.AugustBase {
         const vaultKey = vaultKeyMap[props.receiptToken];
         return await queryLayerZeroDeposits(vaultKey, props.wallet);
     }
+    /**
+     * Get LayerZero redeems for earnAUSD vault
+     *
+     * @example
+     * ```typescript
+     * // Get all earnAUSD redeems
+     * const allRedeems = await sdk.getLayerZeroRedeems();
+     *
+     * // Get redeems for a specific wallet
+     * const userRedeems = await sdk.getLayerZeroRedeems({
+     *   wallet: '0x2de1DCB8EaAd40fAd327fa3eE3F48774b8e20649'
+     * });
+     * ```
+     */
     async getLayerZeroRedeems(props) {
         const { queryLayerZeroRedeems } = await Promise.resolve().then(() => __importStar(require('./services/layerzero/redeems')));
         return await queryLayerZeroRedeems(props?.wallet);

package/lib/modules/api/index.d.ts

@@ -0,0 +1 @@
+export { AugustApi } from './main';

package/lib/modules/api/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AugustApi = void 0;
+var main_1 = require("./main");
+Object.defineProperty(exports, "AugustApi", { enumerable: true, get: function () { return main_1.AugustApi; } });
+//# sourceMappingURL=index.js.map

package/lib/modules/api/main.d.ts

@@ -0,0 +1,52 @@
+import type { IUnrealizedPnlSnapshot } from '../../types';
+/**
+ * Read-only client for August backend REST endpoints that have no on-chain
+ * equivalent — currently the unrealized-PnL series the backend computes
+ * from periodic vault snapshots.
+ *
+ * Every method makes exactly one HTTPS request to the public
+ * (unauthenticated) August API and zero RPC calls. Responses are not cached
+ * by the SDK: this is time-sensitive PnL state where staleness is worse
+ * than request latency.
+ *
+ * Accessible as `apiModule` on the SDK instance; the same methods are also
+ * exposed directly on the SDK class.
+ */
+export declare class AugustApi {
+    /**
+     * Fetch the historical unrealized-PnL series for a vault, newest first,
+     * as computed by the August backend from periodic vault snapshots.
+     *
+     * Makes one HTTPS request to the public August API; no RPC calls.
+     *
+     * @param params.vault Vault address (EVM `0x…`, Solana, or Stellar).
+     * @param params.limit Maximum number of snapshots to return (1–1000). Backend default applies when omitted.
+     * @returns Array of {@link IUnrealizedPnlSnapshot}; empty when the backend has no history for the vault.
+     * @throws AugustValidationError When `vault` is not a valid address or `limit` is out of range.
+     * @throws AugustServerError When the API responds with a 5xx, or returns a body that is not a snapshot array.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     *   const series = await sdk.getVaultUnrealizedPnlHistory({ vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA', limit: 30 });
+     *   console.log(series[0]?.unrealizedPnlInAsset);
+     */
+    getVaultUnrealizedPnlHistory(params: {
+        vault: string;
+        limit?: number;
+    }): Promise<IUnrealizedPnlSnapshot[]>;
+    /**
+     * Fetch the latest unrealized-PnL snapshot for every vault the backend
+     * tracks — one entry per vault.
+     *
+     * Makes one HTTPS request to the public August API; no RPC calls.
+     *
+     * @returns Array of {@link IUnrealizedPnlSnapshot}, one per tracked vault.
+     * @throws AugustServerError When the API responds with a 5xx, or returns a body that is not a snapshot array.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     *   const all = await sdk.getLatestUnrealizedPnl();
+     *   const losing = all.filter((s) => s.unrealizedPnl < 0);
+     */
+    getLatestUnrealizedPnl(): Promise<IUnrealizedPnlSnapshot[]>;
+}

package/lib/modules/api/main.js

@@ -0,0 +1,130 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AugustApi = void 0;
+const ethers_1 = require("ethers");
+const core_1 = require("../../core/constants/core");
+const errors_1 = require("../../core/errors");
+const fetcher_1 = require("../../core/fetcher");
+const chain_address_1 = require("../../core/helpers/chain-address");
+function toUnrealizedPnlSnapshot(raw) {
+    return {
+        timestamp: raw.timestamp,
+        vaultName: raw.vault_name,
+        vaultAddress: raw.vault_address,
+        strategistName: raw.strategist_name ?? null,
+        referenceAsset: raw.reference_asset,
+        assetPrice: raw.asset_price,
+        tvlOnVault: raw.tvl_on_vault,
+        currentRedeemRatio: raw.current_redeem_ratio,
+        actualTvl: raw.actual_tvl,
+        adjustedRedeemRatio: raw.adjusted_redeem_ratio,
+        unrealizedPnl: raw.unrealized_pnl,
+        unrealizedPnlInAsset: raw.unrealized_pnl_in_asset,
+    };
+}
+function assertVaultAddress(vault, method) {
+    const valid = typeof vault === 'string' &&
+        vault.length > 0 &&
+        ((0, ethers_1.isAddress)(vault) || (0, chain_address_1.isSolanaAddress)(vault) || (0, chain_address_1.isStellarAddress)(vault));
+    if (!valid) {
+        throw new errors_1.AugustValidationError('INVALID_ADDRESS', `${method}: "${vault}" is not a valid vault address — pass the vault's EVM (0x…), Solana, or Stellar address.`);
+    }
+}
+const SNAPSHOT_STRING_FIELDS = [
+    'timestamp',
+    'vault_name',
+    'vault_address',
+    'reference_asset',
+];
+const SNAPSHOT_NUMBER_FIELDS = [
+    'asset_price',
+    'tvl_on_vault',
+    'current_redeem_ratio',
+    'actual_tvl',
+    'adjusted_redeem_ratio',
+    'unrealized_pnl',
+    'unrealized_pnl_in_asset',
+];
+function isRawSnapshot(item) {
+    if (!item || typeof item !== 'object')
+        return false;
+    const record = item;
+    return (SNAPSHOT_STRING_FIELDS.every((field) => typeof record[field] === 'string') &&
+        SNAPSHOT_NUMBER_FIELDS.every((field) => typeof record[field] === 'number'));
+}
+function assertSnapshotArray(data, method) {
+    const valid = Array.isArray(data) && data.every(isRawSnapshot);
+    if (!valid) {
+        throw new errors_1.AugustServerError(200, `${method}: unexpected response shape from the August API — expected an array of PnL snapshots. The backend contract may have changed; refresh packages/sdk/api-spec and update the SDK.`);
+    }
+}
+/**
+ * Read-only client for August backend REST endpoints that have no on-chain
+ * equivalent — currently the unrealized-PnL series the backend computes
+ * from periodic vault snapshots.
+ *
+ * Every method makes exactly one HTTPS request to the public
+ * (unauthenticated) August API and zero RPC calls. Responses are not cached
+ * by the SDK: this is time-sensitive PnL state where staleness is worse
+ * than request latency.
+ *
+ * Accessible as `apiModule` on the SDK instance; the same methods are also
+ * exposed directly on the SDK class.
+ */
+class AugustApi {
+    /**
+     * Fetch the historical unrealized-PnL series for a vault, newest first,
+     * as computed by the August backend from periodic vault snapshots.
+     *
+     * Makes one HTTPS request to the public August API; no RPC calls.
+     *
+     * @param params.vault Vault address (EVM `0x…`, Solana, or Stellar).
+     * @param params.limit Maximum number of snapshots to return (1–1000). Backend default applies when omitted.
+     * @returns Array of {@link IUnrealizedPnlSnapshot}; empty when the backend has no history for the vault.
+     * @throws AugustValidationError When `vault` is not a valid address or `limit` is out of range.
+     * @throws AugustServerError When the API responds with a 5xx, or returns a body that is not a snapshot array.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     *   const series = await sdk.getVaultUnrealizedPnlHistory({ vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA', limit: 30 });
+     *   console.log(series[0]?.unrealizedPnlInAsset);
+     */
+    async getVaultUnrealizedPnlHistory(params) {
+        const method = 'getVaultUnrealizedPnlHistory';
+        assertVaultAddress(params.vault, method);
+        if (params.limit !== undefined &&
+            (!Number.isInteger(params.limit) ||
+                params.limit < 1 ||
+                params.limit > 1000)) {
+            throw new errors_1.AugustValidationError('INVALID_INPUT', `${method}: limit must be an integer between 1 and 1000, got ${params.limit}.`);
+        }
+        const endpoint = core_1.WEBSERVER_ENDPOINTS.public.pnl.unrealizedHistory(params.vault, params.limit);
+        const response = await (0, fetcher_1.fetchAugustPublic)(endpoint);
+        const data = await response.json();
+        assertSnapshotArray(data, method);
+        return data.map(toUnrealizedPnlSnapshot);
+    }
+    /**
+     * Fetch the latest unrealized-PnL snapshot for every vault the backend
+     * tracks — one entry per vault.
+     *
+     * Makes one HTTPS request to the public August API; no RPC calls.
+     *
+     * @returns Array of {@link IUnrealizedPnlSnapshot}, one per tracked vault.
+     * @throws AugustServerError When the API responds with a 5xx, or returns a body that is not a snapshot array.
+     * @throws AugustRateLimitError When the API responds 429.
+     * @throws AugustTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     *   const all = await sdk.getLatestUnrealizedPnl();
+     *   const losing = all.filter((s) => s.unrealizedPnl < 0);
+     */
+    async getLatestUnrealizedPnl() {
+        const method = 'getLatestUnrealizedPnl';
+        const response = await (0, fetcher_1.fetchAugustPublic)(core_1.WEBSERVER_ENDPOINTS.public.pnl.unrealizedLatest);
+        const data = await response.json();
+        assertSnapshotArray(data, method);
+        return data.map(toUnrealizedPnlSnapshot);
+    }
+}
+exports.AugustApi = AugustApi;
+//# sourceMappingURL=main.js.map

package/lib/modules/sub-accounts/fetcher.d.ts

@@ -1,11 +1,26 @@
-import { IFetchAugustOptions } from '../../core';
-import { IAddress, IOTCPosition, IWSSubaccountCefi, IWSSubAccountHealthFactor, IWSSubaccountLoan, IWSSubaccountSummary } from '../../types';
+import { type IFetchAugustOptions } from '../../core';
+import type { IAddress, IOTCPosition, IWSSubaccountCefi, IWSSubAccountHealthFactor, IWSSubaccountLoan, IWSSubaccountSummary } from '../../types';
+/**
+ * Fetch subaccount health factor for a given subaccount address
+ */
 export declare const fetchSubaccountHeathFactor: (address: IAddress, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<IWSSubAccountHealthFactor>;
+/**
+ * Fetch subaccount loans details
+ */
 export declare const fetchSubaccountLoans: (payload: {
     address: IAddress;
     side?: "BOTH" | "BORROWER" | "LENDER";
     active?: boolean;
 }, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<IWSSubaccountLoan[]>;
+/**
+ * Fetch the subaccount CeFi positions
+ */
 export declare const fetchSubaccountCefiPositions: (address: IAddress, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<IWSSubaccountCefi[]>;
+/**
+ * Fetch the subaccount OTC positions
+ */
 export declare const fetchSubaccountOtcPositions: (address: IAddress, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<IOTCPosition[]>;
+/**
+ * Fetch the subaccount summary view
+ */
 export declare const fetchSubaccountSummary: (address: IAddress, augustKey: string, headers?: IFetchAugustOptions["headers"]) => Promise<IWSSubaccountSummary>;