@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/modules/api/main.js

@@ -0,0 +1,911 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpshiftApi = void 0;
+/**
+ * The Upshift backend API Module — read-only client for public backend
+ * endpoints (transparency dashboard, unrealized PnL) and authenticated
+ * loan-book / risk / OTC reads. Accessible as `sdk.apiModule`.
+ *
+ * @module UpshiftApi
+ */
+const ethers_1 = require("ethers");
+const fetcher_1 = require("./fetcher");
+const base_class_1 = require("../../core/base.class");
+const core_1 = require("../../core/constants/core");
+const errors_1 = require("../../core/errors");
+const fetcher_2 = 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) ||
+            (0, chain_address_1.isSuiAddress)(vault));
+    if (!valid) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: "${vault}" is not a valid vault address — pass the vault's EVM (0x…), Solana, Stellar, or Sui (0x… 64 hex chars) address.`);
+    }
+}
+/** Transparency endpoints are EVM-only and require a positive integer chain id. */
+function assertTransparencyArgs(method, vault, chainId) {
+    if (!(0, ethers_1.isAddress)(vault)) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: vault must be an EVM address (transparency endpoints are EVM-only), got ${String(vault)}.`);
+    }
+    if (!Number.isInteger(chainId) || chainId <= 0) {
+        throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: chainId must be a positive integer EVM chain id, got ${chainId}. Transparency endpoints are EVM-only.`);
+    }
+}
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Date-window params are plain `YYYY-MM-DD` strings; anything else is rejected before the request. */
+function assertIsoDate(method, name, value) {
+    if (value !== undefined && !ISO_DATE.test(value)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: ${name} must be YYYY-MM-DD, got "${value}".`);
+    }
+}
+/**
+ * Cheap contract-drift guard for the chain-scoped transparency responses.
+ * Every one of them (`positions`, `historical_allocations`, `fees`,
+ * `governance/*`) is an object keyed by `vault_address` + `chain_id`; if the
+ * body is not that, the backend contract has changed and partner code must
+ * not receive a silently-malformed object. Leaves are deliberately NOT
+ * validated — full validation of eight nested shapes is not worth the
+ * weight, and the top-level check catches the common drift (envelope
+ * wrapping, error-object-over-200, renamed root).
+ */
+function assertTransparencyEnvelope(data, method) {
+    const valid = data !== null &&
+        typeof data === 'object' &&
+        !Array.isArray(data) &&
+        typeof data.vault_address === 'string' &&
+        typeof data.chain_id === 'number';
+    if (!valid) {
+        throw new errors_1.UpshiftServerError(200, `${method}: unexpected response shape from the Upshift API — expected an object with vault_address and chain_id. The backend contract may have changed; refresh packages/sdk/api-spec and update the SDK.`);
+    }
+}
+/**
+ * Same guard for the backing-series endpoint, whose body is a bare array of
+ * ratio points (no envelope). Anything else is contract drift.
+ */
+function assertTransparencyArray(data, method) {
+    if (!Array.isArray(data)) {
+        throw new errors_1.UpshiftServerError(200, `${method}: unexpected response shape from the Upshift API — expected an array of ratio points. The backend contract may have changed; refresh packages/sdk/api-spec and update the SDK.`);
+    }
+}
+/** Runtime mirror of {@link ITransparencyTimelockStatus} (+ `'all'`) — plain-JS callers bypass the type. */
+const TRANSPARENCY_TIMELOCK_STATUSES = [
+    'scheduled',
+    'executed',
+    'cancelled',
+    'all',
+];
+/** Runtime mirror of {@link ITransparencyAuditCategory} — plain-JS callers bypass the type. */
+const TRANSPARENCY_AUDIT_CATEGORIES = [
+    'Strategy',
+    'Role',
+    'Permission',
+    'Attestation',
+];
+/** Rejects a filter value outside its allowlist before any request is made (types only guard TS callers). */
+function assertOneOf(method, name, value, allowed) {
+    if (value !== undefined && !allowed.includes(value)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: ${name} must be one of ${allowed.map((v) => `'${v}'`).join(', ')}, got "${String(value)}".`);
+    }
+}
+function assertAddressArg(value, label, method) {
+    const valid = typeof value === 'string' &&
+        value.length > 0 &&
+        ((0, ethers_1.isAddress)(value) ||
+            (0, chain_address_1.isSolanaAddress)(value) ||
+            (0, chain_address_1.isStellarAddress)(value) ||
+            (0, chain_address_1.isSuiAddress)(value));
+    if (!valid) {
+        throw new errors_1.UpshiftValidationError('INVALID_ADDRESS', `${method}: "${value}" is not a valid ${label} — pass an EVM (0x…), Solana, Stellar, or Sui (0x… 64 hex chars) 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.UpshiftServerError(200, `${method}: unexpected response shape from the Upshift 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 Upshift backend REST endpoints that have no on-chain
+ * equivalent: the unrealized-PnL series, the transparency dashboard
+ * (position snapshot, backing series, smoothed APY, allocations, fee config,
+ * governance), plus authenticated loan-book / risk / OTC reads.
+ *
+ * Every public method makes exactly one HTTPS request to the Upshift API and
+ * zero RPC calls. Responses are not cached by the SDK: this is time-sensitive
+ * state where staleness is worse than a request. Accessible as
+ * `sdk.apiModule`; only the unrealized-PnL methods are also mirrored on the
+ * root `UpshiftSDK` class.
+ */
+class UpshiftApi extends base_class_1.UpshiftBase {
+    headers = null;
+    constructor(baseConfig) {
+        super(baseConfig);
+        this.headers = {
+            'x-environment': this.monitoring?.['x-environment'],
+            'x-user-id': this.monitoring?.['x-user-id'],
+        };
+    }
+    /**
+     * Retrieve the global loan-book aggregate across every active client
+     * subaccount — one {@link ILoanBookInfo} entry per loan, with principal /
+     * interest amounts, APRs, state, and the next upcoming payment.
+     *
+     * Backed by the admin-only `GET /dashboard/loans` backend endpoint (60-second
+     * server-side cache), so the Upshift API key configured on the SDK must
+     * belong to an admin user. Makes exactly one HTTP request and no RPC calls.
+     *
+     * @returns Array of loan-book entries; empty when there are no active loans.
+     * @throws UpshiftAuthError When the API key is missing or not admin-scoped.
+     * @throws UpshiftServerError When the API responds with a non-2xx status.
+     * @example
+     *   const loans = await sdk.apiModule.getDashboardLoans();
+     *   const active = loans.filter((l) => l.state === 'ACTIVE');
+     */
+    async getDashboardLoans() {
+        return (0, fetcher_1.fetchDashboardLoans)(this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * Retrieve every token discount-factor ladder the risk engine applies when
+     * valuing collateral.
+     *
+     * Backed by `GET /risk/discount_factors` (60-second server-side cache),
+     * which requires an authenticated Upshift user; an admin-scoped API key
+     * works. Makes exactly one HTTP request and no RPC calls.
+     *
+     * @returns Array of {@link IDiscountFactorLadder}, one per whitelisted token that has a configured ladder.
+     * @throws UpshiftAuthError When the API key is missing or not authorized.
+     * @throws UpshiftServerError When the API responds with a non-2xx status.
+     * @example
+     *   const ladders = await sdk.apiModule.getDiscountFactors();
+     *   console.log(ladders.map((d) => `${d.address}@${d.chain}`));
+     */
+    async getDiscountFactors() {
+        return (0, fetcher_1.fetchDiscountFactors)(this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * Compute how much collateral a subaccount has in excess of — or is short
+     * of — what it needs to hold a target health factor, for one collateral
+     * token.
+     *
+     * Backed by `GET /risk/collateral_excess_or_deficit` (60-second server-side
+     * cache), which resolves the subaccount and reads its current health factor.
+     * The backend serves this route to anonymous callers today, so no Upshift API
+     * key is needed; pass one if you get `AUTH_UNAUTHORIZED`. Makes exactly one
+     * HTTP request and no RPC calls.
+     *
+     * @param params.subaccount Subaccount (smart-contract wallet) address.
+     * @param params.tokenAddress Collateral token address to evaluate.
+     * @param params.tokenChain Numeric Upshift chain id of the token (e.g. `1` for Ethereum mainnet).
+     * @param params.targetHealthFactor Health factor to solve for. Defaults server-side to the minimum healthy factor (1.2); when supplied must be a finite number greater than 0.
+     * @returns The signed excess (positive) or deficit (negative) in USD and token units. Zeroes when the subaccount has no debt.
+     * @throws UpshiftValidationError When an address is invalid, `tokenChain` is not an integer, or `targetHealthFactor` is out of range.
+     * @throws UpshiftServerError When the token has no discount factor (backend 404) or the API otherwise responds non-2xx.
+     * @example
+     *   const r = await sdk.apiModule.getCollateralExcessOrDeficit({
+     *     subaccount: '0xabc…',
+     *     tokenAddress: '0xdef…',
+     *     tokenChain: 1,
+     *   });
+     *   console.log(r.amount_usd > 0 ? 'excess' : 'deficit');
+     */
+    async getCollateralExcessOrDeficit(params) {
+        const method = 'getCollateralExcessOrDeficit';
+        assertAddressArg(params.subaccount, 'subaccount address', method);
+        assertAddressArg(params.tokenAddress, 'token address', method);
+        if (!Number.isInteger(params.tokenChain)) {
+            throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: tokenChain must be an integer Upshift chain id, got ${params.tokenChain}.`);
+        }
+        if (params.targetHealthFactor !== undefined &&
+            (!Number.isFinite(params.targetHealthFactor) ||
+                params.targetHealthFactor <= 0)) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: targetHealthFactor must be a finite number greater than 0, got ${params.targetHealthFactor}.`);
+        }
+        return (0, fetcher_1.fetchCollateralExcessOrDeficit)(params, this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * Simulate the collateral required to open a hypothetical loan against a
+     * chosen basket of collateral tokens.
+     *
+     * This is a pure, read-only simulation: the backend `POST
+     * /risk/collateral_simulation` endpoint (60-second server-side cache)
+     * computes required collateral and effective discount factors and changes
+     * no state. The route is public, so no Upshift API key is needed. Makes
+     * exactly one HTTP request and no RPC calls.
+     *
+     * @param input Simulation parameters — see {@link ICollateralSimulationInput}. `collateral_tokens` and `collateral_token_allocation` must be non-empty and equal length; when `on_platform` is `true`, both `loan_redeployed_token_*` fields are required.
+     * @returns The simulated {@link ICollateralSimulationResults}: total debt, required collateral, resulting health factor, and a per-token breakdown.
+     * @throws UpshiftValidationError When addresses are invalid, `loan_amount` is not a finite non-negative number, the collateral arrays are empty / mismatched, or `on_platform` is set without redeployed-token details.
+     * @throws UpshiftServerError When the API responds with a non-2xx status (e.g. a token missing a discount factor).
+     * @example
+     *   const sim = await sdk.apiModule.simulateCollateral({
+     *     loan_token_chain: 1,
+     *     loan_token_address: '0xloan…',
+     *     loan_amount: 1_000_000,
+     *     collateral_tokens: [[1, '0xcol…']],
+     *     collateral_token_allocation: [1],
+     *   });
+     *   console.log(sim.total_required_collateral_usd);
+     */
+    async simulateCollateral(input) {
+        const method = 'simulateCollateral';
+        assertAddressArg(input.loan_token_address, 'loan token address', method);
+        if (!Number.isFinite(input.loan_amount) || input.loan_amount < 0) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: loan_amount must be a finite non-negative number, got ${input.loan_amount}.`);
+        }
+        if (!Array.isArray(input.collateral_tokens) ||
+            input.collateral_tokens.length === 0 ||
+            !Array.isArray(input.collateral_token_allocation) ||
+            input.collateral_token_allocation.length === 0) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: collateral_tokens and collateral_token_allocation must both be non-empty.`);
+        }
+        if (input.collateral_tokens.length !==
+            input.collateral_token_allocation.length) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: collateral_tokens (${input.collateral_tokens.length}) and collateral_token_allocation (${input.collateral_token_allocation.length}) must be the same length.`);
+        }
+        for (const [, address] of input.collateral_tokens) {
+            assertAddressArg(address, 'collateral token address', method);
+        }
+        if (input.on_platform &&
+            (input.loan_redeployed_token_chain === undefined ||
+                input.loan_redeployed_token_chain === null ||
+                !input.loan_redeployed_token_address)) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: on_platform requires both loan_redeployed_token_chain and loan_redeployed_token_address.`);
+        }
+        return (0, fetcher_1.fetchCollateralSimulation)(input, this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * Fetch the decoded revert reason(s) for a transaction — error messages,
+     * revert strings, and recognized universal-subaccount errors extracted from
+     * a `debug_traceTransaction` call tree.
+     *
+     * Backed by the public (unauthenticated) `GET /revert_reason` endpoint; no
+     * API key required. The backend relies on the target chain's RPC supporting
+     * `debug_trace*`; on chains/RPCs without it the backend returns a 5xx whose
+     * detail explains why, surfaced here as an {@link UpshiftServerError}. Makes
+     * exactly one HTTP request and no RPC calls from the SDK itself.
+     *
+     * @param txHash Transaction hash to trace.
+     * @param chain Numeric Upshift chain id the transaction is on (e.g. `1` for Ethereum mainnet).
+     * @returns The decoded {@link IRevertReason}; all arrays empty when the trace yielded no matching signal.
+     * @throws UpshiftValidationError When `txHash` is empty or `chain` is not an integer.
+     * @throws UpshiftServerError When the chain/RPC does not support tracing, or the API otherwise responds non-2xx.
+     * @example
+     *   const r = await sdk.apiModule.getRevertReason('0xabc…', 1);
+     *   console.log(r.revert_reasons);
+     */
+    async getRevertReason(txHash, chain) {
+        const method = 'getRevertReason';
+        if (typeof txHash !== 'string' || txHash.trim().length === 0) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: txHash must be a non-empty transaction hash.`);
+        }
+        if (!Number.isInteger(chain)) {
+            throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: chain must be an integer Upshift chain id, got ${chain}.`);
+        }
+        return (0, fetcher_1.fetchRevertReason)(txHash, chain, this.headers ?? undefined);
+    }
+    /**
+     * Retrieve every tracked OTC position.
+     *
+     * Backed by the admin-only `GET /otc/position` backend endpoint, so the
+     * configured Upshift API key must belong to an admin user. Makes exactly one
+     * HTTP request and no RPC calls.
+     *
+     * @returns Array of {@link IOtcPositionRead}; empty when there are no OTC positions.
+     * @throws UpshiftAuthError When the API key is missing or not admin-scoped.
+     * @throws UpshiftServerError When the API responds with a non-2xx status.
+     * @example
+     *   const positions = await sdk.apiModule.getOtcPositions();
+     */
+    async getOtcPositions() {
+        return (0, fetcher_1.fetchOtcPositions)(this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * Retrieve OTC margin requirements, optionally filtered by counterparty
+     * and/or payer.
+     *
+     * Backed by the admin-only `GET /otc/margin_requirement` backend endpoint,
+     * so the configured Upshift API key must belong to an admin user. Makes
+     * exactly one HTTP request and no RPC calls.
+     *
+     * @param options - Optional filters
+     * @param options.otcCounterpartyId - Restrict to a single counterparty (UUID)
+     * @param options.payer - Restrict to a single payer address
+     * @returns Array of {@link IOtcMarginRequirement} matching the filters (all when none given).
+     * @throws UpshiftAuthError When the API key is missing or not admin-scoped.
+     * @throws UpshiftServerError When the API responds with a non-2xx status.
+     * @example
+     *   const reqs = await sdk.apiModule.getOtcMarginRequirements({ payer: '0xabc…' });
+     */
+    async getOtcMarginRequirements(options = {}) {
+        return (0, fetcher_1.fetchOtcMarginRequirements)(options, this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * List the subaccounts linked to a vault (curator surface).
+     *
+     * Backed by the curator-or-admin `GET
+     * /curator/vaults/{vault_address}/subaccounts` backend endpoint, so the
+     * configured Upshift API key must belong to the vault's curator or an admin.
+     * Makes exactly one HTTP request and no RPC calls.
+     *
+     * @param vaultAddress - The vault address (EVM `0x…`, Solana, or Stellar)
+     * @returns Array of subaccount records linked to the vault (same shape as the subaccount directory); empty when none are linked.
+     * @throws UpshiftValidationError When `vaultAddress` is not a valid address.
+     * @throws UpshiftAuthError When the API key is missing or not curator/admin for the vault.
+     * @throws UpshiftServerError When the API responds with a non-2xx status.
+     * @example
+     *   const subs = await sdk.apiModule.getCuratorVaultSubaccounts('0xvault…');
+     */
+    async getCuratorVaultSubaccounts(vaultAddress) {
+        assertVaultAddress(vaultAddress, 'getCuratorVaultSubaccounts');
+        return (0, fetcher_1.fetchCuratorVaultSubaccounts)(vaultAddress, this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * Get on-chain whitelist status for every subaccount linked to a vault
+     * (curator surface).
+     *
+     * Backed by the curator-or-admin `GET
+     * /curator/vaults/{vault_address}/whitelist` backend endpoint. EVM vaults
+     * only — non-EVM vaults manage access internally and the backend returns a
+     * 400 (surfaced as {@link UpshiftServerError}). Makes exactly one HTTP
+     * request and no RPC calls from the SDK.
+     *
+     * @param vaultAddress - The EVM vault address (`0x…`)
+     * @returns Array of {@link ICuratorWhitelistStatus}, one per linked subaccount; empty when the vault has no subaccounts.
+     * @throws UpshiftValidationError When `vaultAddress` is not a valid address.
+     * @throws UpshiftAuthError When the API key is missing or not curator/admin for the vault.
+     * @throws UpshiftServerError When the vault is non-EVM (backend 400) or the API otherwise responds non-2xx.
+     * @example
+     *   const status = await sdk.apiModule.getCuratorVaultWhitelist('0xvault…');
+     *   console.log(status.filter((s) => !s.is_whitelisted));
+     */
+    async getCuratorVaultWhitelist(vaultAddress) {
+        assertVaultAddress(vaultAddress, 'getCuratorVaultWhitelist');
+        return (0, fetcher_1.fetchCuratorVaultWhitelist)(vaultAddress, this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * List timelock (governance) requests for a vault on a chain, optionally
+     * filtered by status.
+     *
+     * Backed by the `GET /timelock-requests` backend endpoint. Makes exactly one
+     * HTTP request and no RPC calls.
+     *
+     * @param params.vaultAddress The vault address the requests target.
+     * @param params.chainId Numeric Upshift chain id (must be a positive integer).
+     * @param params.status Status filter: `"scheduled"` (backend default), `"executed"`, `"cancelled"`, or `"all"`. Omit to use the backend default.
+     * @returns Array of {@link ITimelockRequest}; empty when the vault has no matching requests.
+     * @throws UpshiftValidationError When `vaultAddress` is invalid or `chainId` is not a positive integer.
+     * @throws UpshiftServerError When the API responds with a non-2xx status (e.g. an invalid status filter).
+     * @example
+     *   const reqs = await sdk.apiModule.getTimelockRequests({ vaultAddress: '0xvault…', chainId: 1 });
+     */
+    async getTimelockRequests(params) {
+        const method = 'getTimelockRequests';
+        assertVaultAddress(params.vaultAddress, method);
+        if (!Number.isInteger(params.chainId) || params.chainId <= 0) {
+            throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: chainId must be a positive integer Upshift chain id, got ${params.chainId}.`);
+        }
+        return (0, fetcher_1.fetchTimelockRequests)(params, this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * Compute a vault's performance fees over a period (backend-computed from
+     * its snapshot history).
+     *
+     * Backed by `GET /metrics/vault_performance_fees`. The backend runs pandas
+     * over the vault's full snapshot history, so the first call is slow; results
+     * are cached server-side for 20 minutes. Makes exactly one HTTP request and
+     * no RPC calls.
+     *
+     * @param params.vault The vault address (EVM `0x…`, Solana, or Stellar).
+     * @param params.annualizedFeesPct Annualized performance-fee percentage. Defaults to 20.
+     * @param params.nativeDenominated Whether to denominate in the vault's native token. Defaults to `true`.
+     * @param params.calculationPeriod Period preset — `"YearToDate"` (default) or `"MonthToDate"`. Ignored by the backend when a custom `startDate`/`endDate` range is supplied.
+     * @param params.startDate ISO-8601 datetime range start. Must be supplied together with `endDate`.
+     * @param params.endDate ISO-8601 datetime range end. Must be supplied together with `startDate`.
+     * @returns The vault's {@link IVaultPerformanceFees} computation.
+     * @throws UpshiftValidationError When `vault` is invalid, or exactly one of `startDate`/`endDate` is supplied.
+     * @throws UpshiftServerError When there is insufficient snapshot data for the period, or the API otherwise responds non-2xx.
+     * @example
+     *   const fees = await sdk.apiModule.getVaultPerformanceFees({ vault: '0xvault…' });
+     *   console.log(fees.total_perf_fees_asset);
+     */
+    async getVaultPerformanceFees(params) {
+        const method = 'getVaultPerformanceFees';
+        assertVaultAddress(params.vault, method);
+        const hasStart = params.startDate !== undefined;
+        const hasEnd = params.endDate !== undefined;
+        if (hasStart !== hasEnd) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: startDate and endDate must be supplied together (both or neither).`);
+        }
+        return (0, fetcher_1.fetchVaultPerformanceFees)({
+            vaultAddress: params.vault,
+            annualizedFeesPct: params.annualizedFeesPct ?? 20,
+            nativeDenominated: params.nativeDenominated ?? true,
+            calculationPeriod: params.calculationPeriod ?? 'YearToDate',
+            startDate: params.startDate,
+            endDate: params.endDate,
+        }, this.keys.upshift, this.headers ?? undefined);
+    }
+    /**
+     * Fetch a vault's NAV-oracle classification table — how each position/token
+     * is priced (Primary / Secondary Market / CeFi) and its USD value, plus
+     * warnings for tokens that could not be resolved.
+     *
+     * Backed by the public (unauthenticated) `GET
+     * /upshift/oracle_classification/{vault_address}` endpoint; no API key
+     * required. Reads the newest daily snapshot. Makes exactly one HTTP request
+     * and no RPC calls from the SDK.
+     *
+     * @param vault The vault address (EVM `0x…`, Solana, or Stellar).
+     * @param chainId Numeric Upshift chain id the vault lives on.
+     * @returns The vault's {@link IOracleClassification}.
+     * @throws UpshiftValidationError When `vault` is invalid or `chainId` is not an integer.
+     * @throws UpshiftServerError When the vault or its snapshot is not found, or the API otherwise responds non-2xx.
+     * @example
+     *   const cls = await sdk.apiModule.getVaultOracleClassification('0xvault…', 1);
+     *   console.log(cls.warnings);
+     */
+    async getVaultOracleClassification(vault, chainId) {
+        const method = 'getVaultOracleClassification';
+        assertVaultAddress(vault, method);
+        if (!Number.isInteger(chainId)) {
+            throw new errors_1.UpshiftValidationError('INVALID_CHAIN', `${method}: chainId must be an integer Upshift chain id, got ${chainId}.`);
+        }
+        return (0, fetcher_1.fetchVaultOracleClassification)(vault, chainId, this.headers ?? undefined);
+    }
+    // -------------------------------------------------------------------------
+    // Transparency dashboard
+    //
+    // One method per card/tab of the Upshift per-vault transparency page so a
+    // partner can compose exactly the subset they want (e.g. Performance without
+    // the collateral-ratio card). Every method: public endpoint, no API key, one
+    // HTTPS request, zero RPC, snapshot-backed (hourly-ish; cache ≥60s).
+    // -------------------------------------------------------------------------
+    /**
+     * Fetch the latest position snapshot for a vault, grouped per wallet — the
+     * data behind the transparency Overview tab (strategy breakdown, backing
+     * composition, vault buffer, per-wallet table, headline TVL).
+     *
+     * Public `GET /upshift/positions/{vault_address}`; no API key. One HTTPS
+     * request, no RPC. Snapshots land hourly; every field is from the single
+     * `snapshot_at` instant. Vault buffer = `total_nav − Σ subaccounts[].total_usd`;
+     * `reported_tvl` is the vault-contract-reported total assets from the same snapshot.
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id the vault lives on.
+     * @returns {@link ITransparencyPositions}.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const p = await sdk.apiModule.getVaultPositionSnapshot({ vault: '0x36eDbF0C834591BFdfCaC0Ef9605528c75c406aA', chainId: 143 });
+     * const buffer = p.total_nav - p.subaccounts.reduce((a, s) => a + s.total_usd, 0);
+     * ```
+     */
+    async getVaultPositionSnapshot(params) {
+        const method = 'getVaultPositionSnapshot';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        const data = await (0, fetcher_1.fetchTransparencyPositions)(params.vault, params.chainId, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the backing / supply / collateral-ratio time series behind the
+     * Performance tab's "Backing vs Supply" and "Collateral Ratio" charts, and
+     * the Overview sidebar's 7-day deltas.
+     *
+     * Public `GET /upshift/unrealized_pnl?fields=ratio`; no API key. One HTTPS
+     * request, no RPC. Points are hourly, returned newest-first — sort before
+     * charting. `actual_tvl` = backing (mark-to-market), `tvl_on_vault` = supply
+     * (vault-reported), `adjusted_redeem_ratio` = collateral ratio.
+     *
+     * Unlike the chain-scoped transparency endpoints (positions, fees,
+     * governance…), this one is keyed by vault address only and accepts
+     * non-EVM (Solana / Stellar) vaults — same contract as
+     * {@link UpshiftApi.getVaultUnrealizedPnlHistory}, which it shares a route with.
+     *
+     * @param params.vault Vault address (EVM, Solana, or Stellar).
+     * @param params.startDate Optional inclusive lower bound, `YYYY-MM-DD`.
+     * @param params.endDate Optional inclusive upper bound, `YYYY-MM-DD`.
+     * @param params.limit Optional max points.
+     * @returns Array of {@link ITransparencyRatioPoint}; empty when no history.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const pts = await sdk.apiModule.getVaultBackingSeries({ vault, startDate: '2026-08-01' });
+     * const ratio = pts.map((p) => p.adjusted_redeem_ratio * 100); // percent
+     * ```
+     */
+    async getVaultBackingSeries(params) {
+        const method = 'getVaultBackingSeries';
+        assertVaultAddress(params.vault, method);
+        assertIsoDate(method, 'startDate', params.startDate);
+        assertIsoDate(method, 'endDate', params.endDate);
+        if (params.limit !== undefined &&
+            (!Number.isInteger(params.limit) ||
+                params.limit < 1 ||
+                params.limit > 1000)) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: limit must be an integer between 1 and 1000, got ${params.limit}.`);
+        }
+        const data = await (0, fetcher_1.fetchTransparencyRatioSeries)(params.vault, params.startDate, params.endDate, params.limit, this.headers ?? undefined);
+        assertTransparencyArray(data, method);
+        return data;
+    }
+    /**
+     * Fetch the smoothed 7-day APY series — the exact series the Upshift app
+     * charts (Overview "APY last 30 days" and Performance "APY Over Time").
+     *
+     * Public `GET /upshift/historical_apy/chart`; no API key. One HTTPS request,
+     * no RPC. The backend marks this route deprecated in its OpenAPI spec but it
+     * remains the series the Upshift app itself charts; this wrapper tracks it.
+     * The backend applies a rolling-median/mean smoothing filter server-side
+     * when `applySmoothing` is true (the app default); computing APY locally from
+     * raw share ratios will NOT match the published figures.
+     *
+     * Unlike the chain-scoped transparency endpoints (positions, fees,
+     * governance…), this one is keyed by vault address only and accepts
+     * non-EVM (Solana / Stellar) vaults.
+     *
+     * @param params.vault Vault address (EVM, Solana, or Stellar).
+     * @param params.daysAgo Window length in days; pass `-1` for the full history since inception. Default 30.
+     * @param params.averagingPeriodDays Rolling window for the annualized return; must be ≥ 2. Default 7 (the app's "7D APY").
+     * @param params.applySmoothing Apply the backend smoothing filter. Default true.
+     * @returns {@link ITransparencyApySeries} — `labels` are `M/D/YYYY`, `values` are decimal fractions (0.0245 = 2.45%). Empty arrays when the vault has no data.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const apy = await sdk.apiModule.getVaultSmoothedApy({ vault, daysAgo: 30 });
+     * console.log(apy.values.at(-1)); // latest 7D APY as a fraction
+     * ```
+     */
+    async getVaultSmoothedApy(params) {
+        const method = 'getVaultSmoothedApy';
+        assertVaultAddress(params.vault, method);
+        const daysAgo = params.daysAgo ?? 30;
+        // `0` is deliberately rejected: the backend happens to treat `days_ago=0`
+        // as "full history" (same as -1) but only -1 is documented, and a caller
+        // passing 0 almost certainly means "today", not "everything". Forcing the
+        // explicit sentinel avoids silently returning the whole series.
+        if (!Number.isInteger(daysAgo) || (daysAgo < 1 && daysAgo !== -1)) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: daysAgo must be a positive integer (≥ 1) or -1 for full history, got ${params.daysAgo}. 0 is not accepted — pass -1 for the full series.`);
+        }
+        const averaging = params.averagingPeriodDays ?? 7;
+        if (!Number.isInteger(averaging) || averaging < 2) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: averagingPeriodDays must be an integer ≥ 2, got ${params.averagingPeriodDays}.`);
+        }
+        const envelope = await (0, fetcher_1.fetchTransparencySmoothedApy)(params.vault, daysAgo, averaging, params.applySmoothing ?? true, this.headers ?? undefined);
+        // The endpoint reports not-found / bad-args IN-BODY over HTTP 200. The
+        // live shape for those is
+        //   { data: { labels: [], values: [] }, average_apy: null, status: 404|400, error: "…" }
+        // i.e. `data` is never null — it passes `shapeOk` below and falls through
+        // to the normal return as an empty series (charts render their empty
+        // state). The `!shapeOk && status 404/400` branch is a defensive mirror
+        // in case the backend ever sends `data: null` with those statuses.
+        // `data: null` with `status: 200` has never been observed; if it shows up
+        // it IS a contract change and must fail loudly rather than hand partners
+        // a bogus empty chart.
+        const data = envelope?.data;
+        const shapeOk = data !== null &&
+            typeof data === 'object' &&
+            Array.isArray(data.labels) &&
+            Array.isArray(data.values);
+        if (!shapeOk) {
+            if (envelope?.status === 404 || envelope?.status === 400) {
+                return { labels: [], values: [], average_apy: null };
+            }
+            throw new errors_1.UpshiftServerError(200, `${method}: unexpected response shape from the Upshift API — expected { data: { labels, values } }. The backend contract may have changed; refresh packages/sdk/api-spec and update the SDK.`);
+        }
+        return {
+            labels: data.labels,
+            values: data.values,
+            // average_apy sits at the envelope top level, beside `data`.
+            average_apy: envelope?.average_apy ?? null,
+        };
+    }
+    /**
+     * Fetch daily allocation history per protocol — the Performance tab's
+     * "Allocation Over Time" chart.
+     *
+     * Public `GET /upshift/historical_allocations/{vault_address}`; no API key.
+     * One HTTPS request, no RPC.
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @param params.startDate Optional inclusive lower bound, `YYYY-MM-DD`.
+     * @param params.endDate Optional inclusive upper bound, `YYYY-MM-DD`.
+     * @returns {@link ITransparencyHistoricalAllocations}.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const h = await sdk.apiModule.getVaultHistoricalAllocations({ vault, chainId: 143, startDate: '2026-08-01' });
+     * const byDate = Map.groupBy(h.points, (p) => p.date);
+     * ```
+     */
+    async getVaultHistoricalAllocations(params) {
+        const method = 'getVaultHistoricalAllocations';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        assertIsoDate(method, 'startDate', params.startDate);
+        assertIsoDate(method, 'endDate', params.endDate);
+        const data = await (0, fetcher_1.fetchTransparencyHistoricalAllocations)(params.vault, params.chainId, params.startDate, params.endDate, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch a vault's fee configuration — the Performance tab's fee card.
+     *
+     * Public `GET /upshift/fees/{vault_address}`; no API key. One HTTPS
+     * request, no RPC. Percent fields are already scaled (`management_fee_pct`
+     * of `1.5` means 1.5%).
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @returns {@link ITransparencyFees}.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const fees = await sdk.apiModule.getVaultFeeConfig({ vault, chainId: 143 });
+     * console.log(`${fees.management_fee_pct}% mgmt / ${fees.performance_fee_pct}% perf`);
+     * ```
+     */
+    async getVaultFeeConfig(params) {
+        const method = 'getVaultFeeConfig';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        const data = await (0, fetcher_1.fetchTransparencyFees)(params.vault, params.chainId, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the vault's privileged addresses (owner / operators) with custody
+     * enrichment — the Governance tab's "Vault Roles" card.
+     *
+     * Public `GET /upshift/governance/{vault_address}/roles`; no API key. One
+     * HTTPS request from the SDK (the backend performs the on-chain reads).
+     * Third-party enrichment failures (Safe / Fordefi) degrade rows and append
+     * to `warnings` rather than failing.
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @returns {@link ITransparencyGovernanceRoles}.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const { roles, warnings } = await sdk.apiModule.getVaultGovernanceRoles({ vault, chainId: 143 });
+     * const owner = roles.find((r) => r.role === 'owner'); // owner?.is_safe → Safe threshold in safe_threshold
+     * ```
+     */
+    async getVaultGovernanceRoles(params) {
+        const method = 'getVaultGovernanceRoles';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        const data = await (0, fetcher_1.fetchTransparencyGovernanceRoles)(params.vault, params.chainId, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the integrations each vault wallet is whitelisted to operate —
+     * the Governance tab's "Vault Permissions" table.
+     *
+     * Public `GET /upshift/governance/{vault_address}/permissions`; no API key.
+     * One HTTPS request, no RPC.
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @returns {@link ITransparencyGovernancePermissions}.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const { permissions } = await sdk.apiModule.getVaultGovernancePermissions({ vault, chainId: 143 });
+     * for (const p of permissions) console.log(p.integration, p.functions.join(','));
+     * ```
+     */
+    async getVaultGovernancePermissions(params) {
+        const method = 'getVaultGovernancePermissions';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        const data = await (0, fetcher_1.fetchTransparencyGovernancePermissions)(params.vault, params.chainId, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the vault's timelock queue — the Governance tab's "Pending
+     * Timelocks" table. Defaults to pending (`scheduled`) requests.
+     *
+     * Public `GET /upshift/governance/{vault_address}/timelocks`; no API key.
+     * `executable_at` is `scheduled_at + TIMELOCK_DURATION()` read live from
+     * the timelock contract; null (plus a warning) when that read failed.
+     * The default filter is pending only — the list is often empty; pass
+     * `status: 'all'` for history. `getTimelockRequests` returns the raw
+     * backend rows; this returns the dashboard view (labels, `executable_at`,
+     * warnings).
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @param params.status Filter: a single {@link ITransparencyTimelockStatus} or `'all'`. Default `'scheduled'`. Any other string is rejected with `UpshiftValidationError` before a request is made.
+     * @returns {@link ITransparencyTimelocks}.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * const { timelocks } = await sdk.apiModule.getVaultGovernanceTimelocks({ vault, chainId: 1 }); // pending only
+     * const ready = timelocks.filter((t) => t.executable_at && Date.parse(`${t.executable_at}Z`) <= Date.now());
+     * ```
+     */
+    async getVaultGovernanceTimelocks(params) {
+        const method = 'getVaultGovernanceTimelocks';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        assertOneOf(method, 'status', params.status, TRANSPARENCY_TIMELOCK_STATUSES);
+        const data = await (0, fetcher_1.fetchTransparencyGovernanceTimelocks)(params.vault, params.chainId, params.status, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch one page of the vault's governance audit log, newest first — the
+     * Governance tab's "Audit Log" timeline. Merges live timelock events with
+     * manually recorded entries (attestations, permission changes).
+     *
+     * Public `GET /upshift/governance/{vault_address}/audit_log`; no API key.
+     * Paginate with `before` = the last returned entry's `timestamp` while
+     * `has_more` is true (exclusive cursor; ties at the exact boundary
+     * timestamp are skipped, never duplicated).
+     *
+     * @param params.vault EVM vault address.
+     * @param params.chainId Numeric chain id.
+     * @param params.category Optional {@link ITransparencyAuditCategory} filter. Any other string is rejected with `UpshiftValidationError` before a request is made.
+     * @param params.before Optional exclusive cursor — pass the previous page's last `entry.timestamp` back verbatim (naive-UTC, no offset).
+     * @param params.limit Page size, 1–200. Backend default 50.
+     * @returns {@link ITransparencyAuditLog}.
+     * @throws UpshiftValidationError When arguments fail validation (no request is made).
+     * @throws UpshiftServerError When the API responds non-2xx (e.g. unknown vault 404, non-EVM vault 422).
+     * @throws UpshiftServerError (status 200) When the body is not the documented shape — backend contract drift.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError When the request exceeds the SDK request timeout.
+     * @example
+     * ```ts
+     * // Walk the whole log, newest first.
+     * let before: string | undefined;
+     * do {
+     *   const page = await sdk.apiModule.getVaultGovernanceAuditLog({ vault, chainId: 1, before, limit: 50 });
+     *   for (const e of page.entries) console.log(e.timestamp, e.type, e.summary);
+     *   before = page.has_more ? page.entries.at(-1)?.timestamp : undefined;
+     * } while (before);
+     * ```
+     */
+    async getVaultGovernanceAuditLog(params) {
+        const method = 'getVaultGovernanceAuditLog';
+        assertTransparencyArgs(method, params.vault, params.chainId);
+        assertOneOf(method, 'category', params.category, TRANSPARENCY_AUDIT_CATEGORIES);
+        if (params.limit !== undefined &&
+            (!Number.isInteger(params.limit) ||
+                params.limit < 1 ||
+                params.limit > 200)) {
+            throw new errors_1.UpshiftValidationError('INVALID_INPUT', `${method}: limit must be an integer between 1 and 200, got ${params.limit}.`);
+        }
+        const data = await (0, fetcher_1.fetchTransparencyGovernanceAuditLog)(params.vault, params.chainId, params.category, params.before, params.limit, this.headers ?? undefined);
+        assertTransparencyEnvelope(data, method);
+        return data;
+    }
+    /**
+     * Fetch the historical unrealized-PnL series for a vault, newest first,
+     * as computed by the Upshift backend from periodic vault snapshots.
+     *
+     * Makes one HTTPS request to the public Upshift 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 UpshiftValidationError When `vault` is not a valid address or `limit` is out of range.
+     * @throws UpshiftServerError When the API responds with a 5xx, or returns a body that is not a snapshot array.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError 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.UpshiftValidationError('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_2.fetchUpshiftPublic)(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 Upshift API; no RPC calls.
+     *
+     * @returns Array of {@link IUnrealizedPnlSnapshot}, one per tracked vault.
+     * @throws UpshiftServerError When the API responds with a 5xx, or returns a body that is not a snapshot array.
+     * @throws UpshiftRateLimitError When the API responds 429.
+     * @throws UpshiftTimeoutError 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_2.fetchUpshiftPublic)(core_1.WEBSERVER_ENDPOINTS.public.pnl.unrealizedLatest);
+        const data = await response.json();
+        assertSnapshotArray(data, method);
+        return data.map(toUnrealizedPnlSnapshot);
+    }
+}
+exports.UpshiftApi = UpshiftApi;
+//# sourceMappingURL=main.js.map