@augustdigital/sdk 9.1.0 → 9.2.1

package/lib/core/analytics/version.d.ts

@@ -3,4 +3,4 @@
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-export declare const SDK_VERSION = "9.1.0";
+export declare const SDK_VERSION = "9.2.1";

package/lib/core/analytics/version.js

@@ -6,5 +6,5 @@ exports.SDK_VERSION = void 0;
  * Generated during publish from package.json version
  * This file is gitignored and created at publish time
  */
-exports.SDK_VERSION = '9.1.0';
+exports.SDK_VERSION = '9.2.1';
 //# sourceMappingURL=version.js.map

package/lib/main.d.ts

@@ -126,6 +126,12 @@ export declare class AugustSDK extends AugustBase {
      * `cefi` / `otc` arrays back the drill-downs. See the "Rendering the Vault
      * Exposure section" guide in the vaults docs for a faithful reproduction.
      *
+     * Stellar vaults resolve their DeFi exposure through the Untangled portfolio
+     * API instead of DeBank — one extra HTTP call, covering the idle buffer,
+     * Stellar protocol positions, custody wallets and bridged capital. If that
+     * call fails the exposure legs come back empty rather than throwing, so CeFi,
+     * OTC and loan allocations still resolve.
+     *
      * @param props - Vault address and chain ID
      * @returns Detailed breakdown of vault allocations by category
      * @example

package/lib/main.js

@@ -254,6 +254,12 @@ class AugustSDK extends core_1.AugustBase {
      * `cefi` / `otc` arrays back the drill-downs. See the "Rendering the Vault
      * Exposure section" guide in the vaults docs for a faithful reproduction.
      *
+     * Stellar vaults resolve their DeFi exposure through the Untangled portfolio
+     * API instead of DeBank — one extra HTTP call, covering the idle buffer,
+     * Stellar protocol positions, custody wallets and bridged capital. If that
+     * call fails the exposure legs come back empty rather than throwing, so CeFi,
+     * OTC and loan allocations still resolve.
+     *
      * @param props - Vault address and chain ID
      * @returns Detailed breakdown of vault allocations by category
      * @example

package/lib/modules/vaults/getters.d.ts

@@ -20,8 +20,12 @@ import type { IVaultBaseOptions } from './types';
  * Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version.
  * Optionally enriches with loan and allocation data.
  * @param vault - Vault contract address (EVM hex, Stellar C-address, or Solana program ID)
- * @param loans - Include active loan data
- * @param allocations - Include DeFi/CeFi allocation breakdowns
+ * @param loans - Include active loan data. EVM vaults only — there is no
+ *   non-EVM loan book to read, so other families keep the empty default.
+ * @param allocations - Include DeFi/CeFi allocation breakdowns. Resolved for EVM
+ *   vaults (via DeBank) and Stellar vaults (via the Untangled portfolio API).
+ *   Solana and Sui have no vault-level portfolio provider and keep the empty
+ *   default.
  * @param options - RPC and service configuration
  * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
  *   caller already holds the row (e.g. `getVaults` fetched the whole list one
@@ -55,6 +59,15 @@ export declare function getVaultSubaccountLoans(vault: VaultAddress | IVault, op
  * Fetch comprehensive vault asset allocation breakdown.
  * Includes DeFi protocols (via DeBank), CeFi balances, OTC positions, and loans.
  * Categorizes exposures by borrowing, supplying, lending, and wallet holdings.
+ *
+ * DeFi exposure resolves per chain family: EVM vaults via DeBank, Solana
+ * borrowers via Octav.fi, and Stellar vaults via the Untangled portfolio API —
+ * one vault-level call covering the idle buffer, Stellar protocol positions,
+ * custody wallets, and capital bridged to other chains. The Stellar path adds
+ * exactly 1 HTTP call and zero for every other chain; when it fails, the
+ * exposure section comes back empty and the CeFi, OTC and loan allocations are
+ * still returned.
+ *
  * @param vault - Vault address
  * @param options - RPC configuration
  * @returns Detailed allocation data with exposure categorization

package/lib/modules/vaults/getters.js

@@ -84,6 +84,7 @@ const TokenizedVaultV2_1 = require("../../abis/TokenizedVaultV2");
 const TokenizedVaultV2Receipt_1 = require("../../abis/TokenizedVaultV2Receipt");
 const ethereum_block_by_date_1 = __importDefault(require("ethereum-block-by-date"));
 const octavfi_1 = require("../../services/octavfi");
+const untangled_1 = require("../../services/untangled");
 const date_utils_1 = require("./utils/date-utils");
 const call_data_decoder_1 = require("./utils/call-data-decoder");
 const deposits_1 = require("../../services/layerzero/deposits");
@@ -109,8 +110,12 @@ const errors_1 = require("../../core/errors");
  * Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version.
  * Optionally enriches with loan and allocation data.
  * @param vault - Vault contract address (EVM hex, Stellar C-address, or Solana program ID)
- * @param loans - Include active loan data
- * @param allocations - Include DeFi/CeFi allocation breakdowns
+ * @param loans - Include active loan data. EVM vaults only — there is no
+ *   non-EVM loan book to read, so other families keep the empty default.
+ * @param allocations - Include DeFi/CeFi allocation breakdowns. Resolved for EVM
+ *   vaults (via DeBank) and Stellar vaults (via the Untangled portfolio API).
+ *   Solana and Sui have no vault-level portfolio provider and keep the empty
+ *   default.
  * @param options - RPC and service configuration
  * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
  *   caller already holds the row (e.g. `getVaults` fetched the whole list one
@@ -152,24 +157,33 @@ async function getVault({ vault, loans = false, allocations = false, options, lo
         core_1.Logger.log.error('getVault', err, { vault });
         throw new Error(`#getVault::${vault}: ${err?.message}`);
     }
-    // Loans/allocations enrichment is only supported for EVM vaults.
-    // Non-EVM vaults already include empty defaults.
+    // Loans enrichment stays EVM-only — there is no non-EVM loan book to read.
+    // Allocations additionally covers Stellar, whose exposure resolves through the
+    // Untangled portfolio API rather than DeBank; gating it on `isEvmVault` left
+    // `getVaultAllocations` unreachable for the one chain family that needed the
+    // new path, so callers got the empty default while the standalone getter
+    // returned real data. Solana and Sui have no vault-level provider, so they
+    // keep the empty defaults.
     const isEvmVault = returnedVault.version !== 'sol-0' &&
         returnedVault.version !== 'stellar-0' &&
         returnedVault.version !== 'sui-0';
-    if (!isEvmVault && (loans || allocations)) {
-        core_1.Logger.log.warn('getVault', 'Loans/allocations enrichment is not supported for non-EVM vaults — skipping', { vault, version: returnedVault.version });
+    const supportsLoans = isEvmVault;
+    const supportsAllocations = isEvmVault || returnedVault.version === 'stellar-0';
+    const readLoans = loans && supportsLoans;
+    const readAllocations = allocations && supportsAllocations;
+    if ((loans && !supportsLoans) || (allocations && !supportsAllocations)) {
+        core_1.Logger.log.warn('getVault', 'Loans/allocations enrichment is not supported for this vault — skipping', { vault, version: returnedVault.version });
     }
-    if (isEvmVault && !(0, core_1.isBadVault)(vault) && (loans || allocations)) {
+    if (!(0, core_1.isBadVault)(vault) && (readLoans || readAllocations)) {
         const [loansResult, allocationsResult] = await Promise.allSettled([
-            loans
+            readLoans
                 ? getVaultLoans(returnedVault, options)
                 : Promise.resolve(undefined),
-            allocations
+            readAllocations
                 ? getVaultAllocations(vault, options)
                 : Promise.resolve(undefined),
         ]);
-        if (loans) {
+        if (readLoans) {
             if (loansResult.status === 'fulfilled') {
                 returnedVault = {
                     ...returnedVault,
@@ -182,7 +196,7 @@ async function getVault({ vault, loans = false, allocations = false, options, lo
                 });
             }
         }
-        if (allocations) {
+        if (readAllocations) {
             if (allocationsResult.status === 'fulfilled') {
                 returnedVault = {
                     ...returnedVault,
@@ -433,6 +447,15 @@ function httpStatusFromError(error) {
  * Fetch comprehensive vault asset allocation breakdown.
  * Includes DeFi protocols (via DeBank), CeFi balances, OTC positions, and loans.
  * Categorizes exposures by borrowing, supplying, lending, and wallet holdings.
+ *
+ * DeFi exposure resolves per chain family: EVM vaults via DeBank, Solana
+ * borrowers via Octav.fi, and Stellar vaults via the Untangled portfolio API —
+ * one vault-level call covering the idle buffer, Stellar protocol positions,
+ * custody wallets, and capital bridged to other chains. The Stellar path adds
+ * exactly 1 HTTP call and zero for every other chain; when it fails, the
+ * exposure section comes back empty and the CeFi, OTC and loan allocations are
+ * still returned.
+ *
  * @param vault - Vault address
  * @param options - RPC configuration
  * @returns Detailed allocation data with exposure categorization
@@ -532,6 +555,21 @@ async function getVaultAllocations(vault, options) {
                 }
             }
         }
+        else if ((0, core_1.getAddressChainType)(vault) === 'stellar') {
+            // Untangled reconciles the whole Stellar vault in one call — idle buffer,
+            // Stellar protocol positions, custody wallets, and value bridged to other
+            // chains. It is keyed by vault, not by borrower, so it runs here rather
+            // than in the per-borrower loop below, which would multiply the totals.
+            const untangledExposure = await (0, untangled_1.fetchUntangledVaultExposure)(vault);
+            // A miss leaves the exposure section empty — never `debankErr`. See the
+            // `no_fetcher` branch below for why throwing here was wrong.
+            if (untangledExposure) {
+                const untangledRes = (0, untangled_1.transformUntangledToDebank)(untangledExposure);
+                (0, debank_1.parseVaultLevelDebank)(untangledRes, protocolExposure, tokenExposure, vault, exposurePerCategory, netValue);
+                unfilteredTokens = untangledRes.subaccount.tokens;
+                defiPerBorrower[vault] = (0, debank_1.parseLoanLevelDebank)(untangledRes);
+            }
+        }
         // Fetch portfolio data for non-EVM borrowers (EVM handled by fetchVaultDebankResponse above).
         // CeFi and OTC fetches below run for ALL borrowers regardless of chain type.
         for (const borrower of uniqueBorrowers) {

package/lib/sdk.d.ts

@@ -16071,6 +16071,12 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                    * `cefi` / `otc` arrays back the drill-downs. See the "Rendering the Vault
                    * Exposure section" guide in the vaults docs for a faithful reproduction.
                    *
+                   * Stellar vaults resolve their DeFi exposure through the Untangled portfolio
+                   * API instead of DeBank — one extra HTTP call, covering the idle buffer,
+                   * Stellar protocol positions, custody wallets and bridged capital. If that
+                   * call fails the exposure legs come back empty rather than throwing, so CeFi,
+                   * OTC and loan allocations still resolve.
+                   *
                    * @param props - Vault address and chain ID
                    * @returns Detailed breakdown of vault allocations by category
                    * @example
@@ -19366,8 +19372,12 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   * Routes to appropriate chain adapter (EVM v1/v2, Solana, or Stellar) based on vault version.
                                   * Optionally enriches with loan and allocation data.
                                   * @param vault - Vault contract address (EVM hex, Stellar C-address, or Solana program ID)
-                                  * @param loans - Include active loan data
-                                  * @param allocations - Include DeFi/CeFi allocation breakdowns
+                                  * @param loans - Include active loan data. EVM vaults only — there is no
+                                  *   non-EVM loan book to read, so other families keep the empty default.
+                                  * @param allocations - Include DeFi/CeFi allocation breakdowns. Resolved for EVM
+                                  *   vaults (via DeBank) and Stellar vaults (via the Untangled portfolio API).
+                                  *   Solana and Sui have no vault-level portfolio provider and keep the empty
+                                  *   default.
                                   * @param options - RPC and service configuration
                                   * @param tokenizedVault - Optional pre-fetched backend row for `vault`. When a
                                   *   caller already holds the row (e.g. `getVaults` fetched the whole list one
@@ -19399,6 +19409,15 @@ declare type AsArray<T> = T extends readonly unknown[] ? T : never;
                                   * Fetch comprehensive vault asset allocation breakdown.
                                   * Includes DeFi protocols (via DeBank), CeFi balances, OTC positions, and loans.
                                   * Categorizes exposures by borrowing, supplying, lending, and wallet holdings.
+                                  *
+                                  * DeFi exposure resolves per chain family: EVM vaults via DeBank, Solana
+                                  * borrowers via Octav.fi, and Stellar vaults via the Untangled portfolio API —
+                                  * one vault-level call covering the idle buffer, Stellar protocol positions,
+                                  * custody wallets, and capital bridged to other chains. The Stellar path adds
+                                  * exactly 1 HTTP call and zero for every other chain; when it fails, the
+                                  * exposure section comes back empty and the CeFi, OTC and loan allocations are
+                                  * still returned.
+                                  *
                                   * @param vault - Vault address
                                   * @param options - RPC configuration
                                   * @returns Detailed allocation data with exposure categorization

package/lib/services/untangled/fetcher.d.ts

@@ -0,0 +1,40 @@
+import type { IUntangledVaultExposure } from './types';
+/**
+ * Fetch a vault's full capital exposure from the Untangled portfolio API.
+ *
+ * Untangled reconciles Stellar vaults end to end — the vault's idle buffer,
+ * capital deployed into Stellar protocols, custody wallet balances, and value
+ * bridged to other chains. DeBank and Octav.fi cover none of that, which is why
+ * Stellar vaults previously rendered an empty exposure breakdown.
+ *
+ * The endpoint is keyed by **vault** address and already aggregates every
+ * borrower, so it must be called once per vault — never once per borrower, which
+ * would multiply the same totals.
+ *
+ * Requests are plain `GET`s with no custom headers. That is deliberate: it keeps
+ * them preflight-free in the browser, where the API's `access-control-allow-origin: *`
+ * covers the simple request but a bare `OPTIONS` is rejected.
+ *
+ * Never throws. Every failure — unknown vault, upstream error, transport
+ * failure, malformed body — resolves to `null` so callers can degrade to an
+ * empty exposure section instead of losing the rest of their response.
+ *
+ * Worst case: exactly **1 HTTP call**. No retry, no caching (the API is edge
+ * cached at `s-maxage=60`, well inside its 60 req/min budget for one call per
+ * vault page load).
+ *
+ * @param vault - Vault address, e.g. a Stellar contract address (`C…`).
+ * @returns The resolved exposure report, or `null` when Untangled does not
+ *   reconcile this vault or the request failed.
+ *
+ * @example
+ * ```typescript
+ * const exposure = await fetchUntangledVaultExposure(
+ *   'CCL3WITWFFXIHV2I52ECV5DPIEOFSTU3PBPR53ILPLF2IP5KHECXRUTY',
+ * );
+ * // exposure?.tvlUsd     → 24845637.05
+ * // exposure?.byProtocol → [{ protocolId: 'stellar-wallet', … }, { protocolId: 'blend', … }, …]
+ * const normalized = transformUntangledToDebank(exposure);
+ * ```
+ */
+export declare function fetchUntangledVaultExposure(vault: string): Promise<IUntangledVaultExposure | null>;

package/lib/services/untangled/fetcher.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchUntangledVaultExposure = fetchUntangledVaultExposure;
+const core_1 = require("../../core");
+const BASE_URL = 'https://api-portfolio-octopos-mainnet.untangled.finance';
+/**
+ * Read a response body as JSON without throwing.
+ *
+ * Used on the error path, where a malformed or empty body must not mask the
+ * HTTP status we actually want to report.
+ *
+ * @param response - The fetch response to drain.
+ * @returns The parsed body, or `null` when it is absent or not JSON.
+ */
+async function readJsonSafely(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch a vault's full capital exposure from the Untangled portfolio API.
+ *
+ * Untangled reconciles Stellar vaults end to end — the vault's idle buffer,
+ * capital deployed into Stellar protocols, custody wallet balances, and value
+ * bridged to other chains. DeBank and Octav.fi cover none of that, which is why
+ * Stellar vaults previously rendered an empty exposure breakdown.
+ *
+ * The endpoint is keyed by **vault** address and already aggregates every
+ * borrower, so it must be called once per vault — never once per borrower, which
+ * would multiply the same totals.
+ *
+ * Requests are plain `GET`s with no custom headers. That is deliberate: it keeps
+ * them preflight-free in the browser, where the API's `access-control-allow-origin: *`
+ * covers the simple request but a bare `OPTIONS` is rejected.
+ *
+ * Never throws. Every failure — unknown vault, upstream error, transport
+ * failure, malformed body — resolves to `null` so callers can degrade to an
+ * empty exposure section instead of losing the rest of their response.
+ *
+ * Worst case: exactly **1 HTTP call**. No retry, no caching (the API is edge
+ * cached at `s-maxage=60`, well inside its 60 req/min budget for one call per
+ * vault page load).
+ *
+ * @param vault - Vault address, e.g. a Stellar contract address (`C…`).
+ * @returns The resolved exposure report, or `null` when Untangled does not
+ *   reconcile this vault or the request failed.
+ *
+ * @example
+ * ```typescript
+ * const exposure = await fetchUntangledVaultExposure(
+ *   'CCL3WITWFFXIHV2I52ECV5DPIEOFSTU3PBPR53ILPLF2IP5KHECXRUTY',
+ * );
+ * // exposure?.tvlUsd     → 24845637.05
+ * // exposure?.byProtocol → [{ protocolId: 'stellar-wallet', … }, { protocolId: 'blend', … }, …]
+ * const normalized = transformUntangledToDebank(exposure);
+ * ```
+ */
+async function fetchUntangledVaultExposure(vault) {
+    try {
+        const response = await fetch(`${BASE_URL}/v1/vaults/${encodeURIComponent(vault)}/exposure`, { method: 'GET' });
+        if (!response.ok) {
+            const body = await readJsonSafely(response);
+            // 404 is the documented "we don't reconcile this vault" answer, not a
+            // fault — most vaults are not Untangled-covered. Keep it a breadcrumb so
+            // a known, permanent gap does not fill Sentry.
+            if (response.status === 404) {
+                core_1.Logger.log.warn('fetchUntangledVaultExposure:unresolved', {
+                    vault,
+                    status: response.status,
+                    reason: body?.reason ?? 'unknown_vault',
+                });
+                return null;
+            }
+            core_1.Logger.log.error('fetchUntangledVaultExposure', new Error(`HTTP ${response.status} ${response.statusText}`), { vault, status: response.status });
+            return null;
+        }
+        const data = await response.json();
+        if (!data || typeof data !== 'object' || Array.isArray(data)) {
+            core_1.Logger.log.error('fetchUntangledVaultExposure.unexpected-type', new Error(`unexpected response type: ${typeof data}`), { vault });
+            return null;
+        }
+        if (data.resolved !== true) {
+            core_1.Logger.log.warn('fetchUntangledVaultExposure:unresolved', {
+                vault,
+                status: response.status,
+                reason: data.reason ?? 'unknown_vault',
+            });
+            return null;
+        }
+        if (!Array.isArray(data.byProtocol)) {
+            core_1.Logger.log.error('fetchUntangledVaultExposure.malformed', new Error('resolved response is missing byProtocol[]'), { vault });
+            return null;
+        }
+        if (data.stale) {
+            core_1.Logger.log.warn('fetchUntangledVaultExposure:stale', {
+                vault,
+                asOf: data.asOf,
+            });
+        }
+        return data;
+    }
+    catch (error) {
+        core_1.Logger.log.error('fetchUntangledVaultExposure', error, { vault });
+        return null;
+    }
+}
+//# sourceMappingURL=fetcher.js.map

package/lib/services/untangled/index.d.ts

@@ -0,0 +1,3 @@
+export * from './fetcher';
+export * from './types';
+export * from './utils';

package/lib/services/untangled/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./fetcher"), exports);
+__exportStar(require("./types"), exports);
+__exportStar(require("./utils"), exports);
+//# sourceMappingURL=index.js.map

package/lib/services/untangled/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Response types for the Untangled portfolio API.
+ *
+ * Shape verified live on 2026-09-01 against
+ * `GET https://api-portfolio-octopos-mainnet.untangled.finance/v1/vaults/{address}/exposure`
+ * for the Gami earnUSDC Stellar vault.
+ */
+/**
+ * One protocol slice of a vault's TVL.
+ *
+ * Untangled reports the whole vault, so the slices cover capital held in the
+ * vault contract itself, in custody wallets, and bridged to other chains — not
+ * just on-chain Stellar protocol positions.
+ */
+export interface IUntangledProtocolExposure {
+    /**
+     * Untangled protocol slug, e.g. `blend`, `templar`, `aquarius`. Two slugs are
+     * not protocols: `stellar-wallet` (custody wallets) and `upshift` (the vault's
+     * own idle buffer).
+     */
+    protocolId: string;
+    /** USD value held in this protocol. */
+    valueUsd: number;
+    /** Share of the vault's `tvlUsd`, as a percentage (`23.54` means 23.54%). */
+    pct: number;
+}
+/**
+ * One asset slice of a vault's TVL. Vault-wide — the API does not currently
+ * break assets down per protocol.
+ */
+export interface IUntangledAssetExposure {
+    /** Asset ticker, e.g. `USDC`, `XLM`. */
+    symbol: string;
+    /** USD value held in this asset across the whole vault. */
+    valueUsd: number;
+    /** Share of the vault's `tvlUsd`, as a percentage. */
+    pct: number;
+}
+/**
+ * One address holding part of a vault's capital — the vault contract, a custody
+ * wallet, or a bridged account on another chain.
+ */
+export interface IUntangledLocation {
+    /** Address on `chain`. Not necessarily a Stellar address (NEAR accounts appear here). */
+    address: string;
+    /** Chain slug the address lives on, e.g. `stellar`, `near`. */
+    chain: string;
+    /** Human-readable label, e.g. `idle`, `ForDefi`, `Templar`. */
+    label: string;
+    /** USD value held at this address. */
+    valueUsd: number;
+    /** ISO-8601 timestamp this location was last reconciled. */
+    asOf: string;
+}
+/**
+ * A resolved vault exposure report.
+ *
+ * Untangled answers with `{ resolved: false, reason }` and HTTP 404 for vaults
+ * it does not reconcile; `fetchUntangledVaultExposure` maps that to `null`, so
+ * `resolved` is always `true` on values that reach a caller.
+ */
+export interface IUntangledVaultExposure {
+    /** Always `true` — unresolved reports never reach callers. */
+    resolved: true;
+    /** The vault this report describes. */
+    vault: {
+        address: string;
+        chain: string;
+    };
+    /** Total USD value Untangled reconciled across every location. */
+    tvlUsd: number;
+    /** Protocol-level split of `tvlUsd`. */
+    byProtocol: IUntangledProtocolExposure[];
+    /** Asset-level split of `tvlUsd`, vault-wide. */
+    byAsset: IUntangledAssetExposure[];
+    /** Per-address drill-down of where the capital sits. */
+    locations: IUntangledLocation[];
+    /** ISO-8601 timestamp the report was assembled. */
+    asOf: string;
+    /** `true` when Untangled served a report it could not refresh in time. */
+    stale: boolean;
+}

package/lib/services/untangled/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Response types for the Untangled portfolio API.
+ *
+ * Shape verified live on 2026-09-01 against
+ * `GET https://api-portfolio-octopos-mainnet.untangled.finance/v1/vaults/{address}/exposure`
+ * for the Gami earnUSDC Stellar vault.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/lib/services/untangled/utils.d.ts

@@ -0,0 +1,55 @@
+import type { IDebankNormalizedResponse } from '../debank/utils';
+import type { IUntangledVaultExposure } from './types';
+/** Display metadata for an Untangled protocol slug. */
+export interface IUntangledProtocolMetadata {
+    /** Name rendered in the exposure breakdown. */
+    name: string;
+    /** Chain the protocol position lives on — not always the vault's own chain. */
+    chain: string;
+}
+/**
+ * Display metadata for the protocol slugs Untangled reports today.
+ *
+ * Untangled does not return protocol names or chains, so they are mapped here.
+ * Unknown slugs fall back to a capitalized slug on the vault's chain rather than
+ * being dropped, so a newly integrated protocol still shows up (unlabelled)
+ * instead of silently vanishing from the breakdown.
+ */
+export declare const UNTANGLED_PROTOCOL_REGISTRY: Record<string, IUntangledProtocolMetadata>;
+/**
+ * Transform an Untangled vault exposure report into the DeBank-normalized shape
+ * that `parseVaultLevelDebank` and `parseLoanLevelDebank` consume.
+ *
+ * This is the Stellar equivalent of `transformOctavfiToDebank`: a foreign
+ * portfolio shape is mapped onto the one normalized structure the vault
+ * allocation parser understands, so Stellar vaults populate the same
+ * `exposurePerCategory` / `protocolExposure` / `tokenExposure` outputs as EVM
+ * vaults with no parser changes.
+ *
+ * Mapping:
+ * - Each `byProtocol` entry becomes one position with a single supplying token,
+ *   valued in USD (`price: 1`), on the chain from
+ *   {@link UNTANGLED_PROTOCOL_REGISTRY}.
+ * - `stellar-wallet` and `upshift` are summed into one wallet token, because
+ *   both are undeployed capital rather than protocol exposure.
+ * - Dust is left in place: `filterOutBySize` in the parser applies the same
+ *   threshold Stellar and EVM vaults share.
+ *
+ * `locations`, `asOf`, `stale` and `tvlUsd` are not consumed — TVL already comes
+ * from `getVaultTvl`, and freshness is not yet surfaced on `IVaultAllocations`.
+ *
+ * @param exposure - A resolved Untangled report, or `null`/`undefined` when the
+ *   fetch failed.
+ * @returns A DeBank-normalized response. Empty positions and tokens when
+ *   `exposure` is absent, so callers can pass a failed fetch straight through.
+ *
+ * @example
+ * ```typescript
+ * const exposure = await fetchUntangledVaultExposure(vault);
+ * const normalized = transformUntangledToDebank(exposure);
+ * parseVaultLevelDebank(
+ *   normalized, protocolExposure, tokenExposure, vault, exposurePerCategory, netValue,
+ * );
+ * ```
+ */
+export declare function transformUntangledToDebank(exposure: IUntangledVaultExposure | null | undefined): IDebankNormalizedResponse;

package/lib/services/untangled/utils.js

@@ -0,0 +1,157 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UNTANGLED_PROTOCOL_REGISTRY = void 0;
+exports.transformUntangledToDebank = transformUntangledToDebank;
+/**
+ * Display metadata for the protocol slugs Untangled reports today.
+ *
+ * Untangled does not return protocol names or chains, so they are mapped here.
+ * Unknown slugs fall back to a capitalized slug on the vault's chain rather than
+ * being dropped, so a newly integrated protocol still shows up (unlabelled)
+ * instead of silently vanishing from the breakdown.
+ */
+exports.UNTANGLED_PROTOCOL_REGISTRY = {
+    blend: { name: 'Blend', chain: 'stellar' },
+    templar: { name: 'Templar (NEAR)', chain: 'near' },
+    aquarius: { name: 'Aquarius', chain: 'stellar' },
+};
+/**
+ * Slugs that are not protocol positions: `stellar-wallet` is custody wallet
+ * cash and `upshift` is the vault's own idle buffer. Both are undeployed
+ * capital, which the exposure breakdown renders as wallet holdings — the same
+ * treatment EVM vaults get for funds sitting outside a protocol.
+ */
+const WALLET_PROTOCOL_IDS = new Set(['stellar-wallet', 'upshift']);
+const DEFAULT_CHAIN = 'stellar';
+/**
+ * Stellar's asset precision, carried only to satisfy the DeBank token shape.
+ * The synthesized tokens hold USD values (`price: 1`), so no consumer scales by
+ * this.
+ */
+const SYNTHETIC_TOKEN_DECIMALS = 7;
+/**
+ * Build a DeBank-shaped token carrying a USD value.
+ *
+ * `parseVaultLevelDebank` computes USD as `price * amount`, so a value already
+ * denominated in dollars is expressed as `price: 1, amount: <usd>`.
+ */
+function toDebankToken(symbol, chain, valueUsd, exposureType, protocolId) {
+    return {
+        id: symbol,
+        chain,
+        name: symbol,
+        symbol,
+        optimized_symbol: symbol,
+        decimals: SYNTHETIC_TOKEN_DECIMALS,
+        logo_url: '',
+        amount: valueUsd,
+        price: 1,
+        protocol_id: protocolId ?? '',
+        supplying_exposure: exposureType === 'supply' ? 'true' : undefined,
+    };
+}
+/**
+ * The asset holding most of the vault's value.
+ *
+ * Untangled splits assets vault-wide rather than per protocol, so every
+ * synthesized position is tagged with this one symbol. For the Gami vaults it is
+ * an exact description (earnUSDC is ~100% USDC); an exact per-protocol split
+ * needs `byProtocol[].assets[]` from Untangled.
+ */
+function dominantAssetSymbol(exposure) {
+    const dominant = (exposure.byAsset || []).reduce((best, asset) => !best || Number(asset?.valueUsd || 0) > Number(best.valueUsd || 0)
+        ? asset
+        : best, null);
+    return dominant?.symbol || 'UNKNOWN';
+}
+/**
+ * Transform an Untangled vault exposure report into the DeBank-normalized shape
+ * that `parseVaultLevelDebank` and `parseLoanLevelDebank` consume.
+ *
+ * This is the Stellar equivalent of `transformOctavfiToDebank`: a foreign
+ * portfolio shape is mapped onto the one normalized structure the vault
+ * allocation parser understands, so Stellar vaults populate the same
+ * `exposurePerCategory` / `protocolExposure` / `tokenExposure` outputs as EVM
+ * vaults with no parser changes.
+ *
+ * Mapping:
+ * - Each `byProtocol` entry becomes one position with a single supplying token,
+ *   valued in USD (`price: 1`), on the chain from
+ *   {@link UNTANGLED_PROTOCOL_REGISTRY}.
+ * - `stellar-wallet` and `upshift` are summed into one wallet token, because
+ *   both are undeployed capital rather than protocol exposure.
+ * - Dust is left in place: `filterOutBySize` in the parser applies the same
+ *   threshold Stellar and EVM vaults share.
+ *
+ * `locations`, `asOf`, `stale` and `tvlUsd` are not consumed — TVL already comes
+ * from `getVaultTvl`, and freshness is not yet surfaced on `IVaultAllocations`.
+ *
+ * @param exposure - A resolved Untangled report, or `null`/`undefined` when the
+ *   fetch failed.
+ * @returns A DeBank-normalized response. Empty positions and tokens when
+ *   `exposure` is absent, so callers can pass a failed fetch straight through.
+ *
+ * @example
+ * ```typescript
+ * const exposure = await fetchUntangledVaultExposure(vault);
+ * const normalized = transformUntangledToDebank(exposure);
+ * parseVaultLevelDebank(
+ *   normalized, protocolExposure, tokenExposure, vault, exposurePerCategory, netValue,
+ * );
+ * ```
+ */
+function transformUntangledToDebank(exposure) {
+    if (!exposure) {
+        return { subaccount: { positions: [], tokens: [] } };
+    }
+    const symbol = dominantAssetSymbol(exposure);
+    const vaultChain = exposure.vault?.chain || DEFAULT_CHAIN;
+    const positions = [];
+    let walletValueUsd = 0;
+    (exposure.byProtocol || []).forEach((entry) => {
+        if (!entry?.protocolId)
+            return;
+        const valueUsd = Number(entry.valueUsd) || 0;
+        if (WALLET_PROTOCOL_IDS.has(entry.protocolId)) {
+            walletValueUsd += valueUsd;
+            return;
+        }
+        const metadata = exports.UNTANGLED_PROTOCOL_REGISTRY[entry.protocolId];
+        const chain = metadata?.chain || vaultChain;
+        const name = metadata?.name ||
+            entry.protocolId.charAt(0).toUpperCase() + entry.protocolId.slice(1);
+        positions.push({
+            id: entry.protocolId,
+            chain,
+            name,
+            logo_url: '',
+            site_url: '',
+            portfolio_item_list: [
+                {
+                    name,
+                    stats: {
+                        asset_usd_value: valueUsd,
+                        debt_usd_value: 0,
+                        net_usd_value: valueUsd,
+                    },
+                    detail: {
+                        supply_token_list: [
+                            toDebankToken(symbol, chain, valueUsd, 'supply', entry.protocolId),
+                        ],
+                        borrow_token_list: [],
+                    },
+                },
+            ],
+        });
+    });
+    const tokens = [];
+    if (walletValueUsd > 0) {
+        tokens.push({
+            ...toDebankToken(symbol, vaultChain, walletValueUsd, 'wallet'),
+            is_wallet: true,
+            is_core: true,
+        });
+    }
+    return { subaccount: { positions, tokens } };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@augustdigital/sdk",
-  "version": "9.1.0",
+  "version": "9.2.1",
   "main": "lib/index.js",
   "types": "lib/sdk.d.ts",
   "keywords": [