@upshiftfinance/sdk 0.0.0-stage → 0.1.0

package/lib/services/swap-quotes/index.d.ts

@@ -0,0 +1,105 @@
+/** @module core/services/swap-quotes */
+import type { IAddress } from '../../types';
+/** Quote-provider discriminant. Will widen as new providers are added. */
+export type ISwapQuoteProvider = 'paraswap';
+/**
+ * Input to {@link fetchSwapQuote}.
+ */
+export interface ISwapQuoteRequest {
+    /** EVM chain ID where the swap will execute. */
+    chainId: number;
+    /** ERC-20 the user holds. */
+    srcToken: IAddress;
+    /** `srcToken.decimals()`. */
+    srcDecimals: number;
+    /** ERC-20 the SwapRouter should produce — typically the vault's `referenceAsset`. */
+    destToken: IAddress;
+    /** `destToken.decimals()`. */
+    destDecimals: number;
+    /** Input amount in `srcToken`'s smallest unit. */
+    amount: bigint;
+    /**
+     * Address that will execute the resulting calldata. For SwapRouter use,
+     * pass the SwapRouter's address — the aggregator's calldata is bound to
+     * this address, so it must hold the tokens at swap time.
+     */
+    receiver: IAddress;
+    /**
+     * Slippage tolerance in bps (1 bp = 0.01%). Defaults to 100 (1%). Must be
+     * in `[0, 10_000)` — 10_000 disables protection entirely and is rejected.
+     */
+    slippageBps?: number;
+    /**
+     * Optional aggregator contract-method filter. When set, the aggregator is
+     * constrained to this single method (ParaSwap's `/prices`
+     * `includeContractMethods`), so the returned calldata's leading 4-byte
+     * selector is deterministic — required when the on-chain SwapRouter only
+     * authorizes one selector per router. When omitted, the aggregator picks the
+     * optimal method freely and the selector may vary between quotes.
+     */
+    contractMethod?: string;
+    /** Aggregator partner key. Defaults to `'upshift'`. */
+    partner?: string;
+    /** Aggregator partner-fee receiver. Defaults to the Upshift partner address. */
+    partnerAddress?: IAddress;
+    /**
+     * `fetch`-compatible function override. Defaults to `globalThis.fetch`.
+     * Exposed so callers in Node environments lacking a global `fetch` can
+     * inject one, and so tests can mock without touching the global.
+     */
+    fetchImpl?: typeof fetch;
+    /** Optional AbortSignal to cancel the in-flight Paraswap requests. */
+    signal?: AbortSignal;
+}
+/**
+ * Output of {@link fetchSwapQuote}. The `router` + `payload` pair maps
+ * directly into one entry of an `ISwapParams[]` passed to
+ * `SwapRouter.swapAndDeposit`.
+ *
+ * Modeled as a discriminated union on `provider` so adding 1inch/0x is an
+ * additive change rather than a breaking widening.
+ */
+export type ISwapQuoteResult = {
+    /** Quote provider that produced this calldata. */
+    provider: 'paraswap';
+    /** DEX router that will execute the swap (the contract `payload` is calldata for). */
+    router: IAddress;
+    /** ABI-encoded calldata for `router`. */
+    payload: `0x${string}`;
+    /** Expected output in `destToken` units before slippage. */
+    expectedAmountOut: bigint;
+    /** Slippage-adjusted minimum output. Below this the on-chain call reverts. */
+    minAmountOut: bigint;
+    /**
+     * Epoch ms when the quote was fetched. Callers that prefetch a quote
+     * before submitting should re-fetch when this is older than ~60s — DEX
+     * pool state moves and a stale `minAmountOut` may have been computed
+     * against a price that no longer holds.
+     */
+    fetchedAt: number;
+};
+/**
+ * Fetch a swap quote and the calldata required for the on-chain SwapRouter
+ * to execute it.
+ *
+ * @throws {@link UpshiftValidationError} on invalid input (slippage out of
+ * range, zero amount, src===dst).
+ * @throws {@link UpshiftNetworkError} on transport failure.
+ * @throws {@link UpshiftServerError} on aggregator-side errors.
+ *
+ * @example
+ * ```ts
+ * const quote = await fetchSwapQuote({
+ *   chainId: 1,
+ *   srcToken: WBTC,
+ *   srcDecimals: 8,
+ *   destToken: USDC,
+ *   destDecimals: 6,
+ *   amount: 100_000_000n,
+ *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+ * });
+ * // quote.router  -> Paraswap augustor
+ * // quote.payload -> calldata
+ * ```
+ */
+export declare function fetchSwapQuote(request: ISwapQuoteRequest): Promise<ISwapQuoteResult>;

package/lib/services/swap-quotes/index.js

@@ -0,0 +1,77 @@
+"use strict";
+/** @module core/services/swap-quotes */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchSwapQuote = fetchSwapQuote;
+const errors_1 = require("../../core/errors");
+const paraswap_1 = require("./paraswap");
+const DEFAULT_SLIPPAGE_BPS = 100;
+const BPS_DENOMINATOR = 10000n;
+/**
+ * Fetch a swap quote and the calldata required for the on-chain SwapRouter
+ * to execute it.
+ *
+ * @throws {@link UpshiftValidationError} on invalid input (slippage out of
+ * range, zero amount, src===dst).
+ * @throws {@link UpshiftNetworkError} on transport failure.
+ * @throws {@link UpshiftServerError} on aggregator-side errors.
+ *
+ * @example
+ * ```ts
+ * const quote = await fetchSwapQuote({
+ *   chainId: 1,
+ *   srcToken: WBTC,
+ *   srcDecimals: 8,
+ *   destToken: USDC,
+ *   destDecimals: 6,
+ *   amount: 100_000_000n,
+ *   receiver: SWAP_ROUTER_ADDRESSES[1]!,
+ * });
+ * // quote.router  -> Paraswap augustor
+ * // quote.payload -> calldata
+ * ```
+ */
+async function fetchSwapQuote(request) {
+    validateRequest(request);
+    const slippageBps = request.slippageBps ?? DEFAULT_SLIPPAGE_BPS;
+    const fetchImpl = request.fetchImpl ?? globalThis.fetch;
+    const { router, payload, expectedAmountOut, fetchedAt } = await (0, paraswap_1.fetchParaswapQuote)({
+        chainId: request.chainId,
+        srcToken: request.srcToken,
+        srcDecimals: request.srcDecimals,
+        destToken: request.destToken,
+        destDecimals: request.destDecimals,
+        amount: request.amount,
+        receiver: request.receiver,
+        slippageBps,
+        partner: request.partner ?? paraswap_1.PARASWAP_DEFAULTS.partner,
+        partnerAddress: request.partnerAddress ?? paraswap_1.PARASWAP_DEFAULTS.partnerAddress,
+        contractMethod: request.contractMethod,
+        fetchImpl,
+        signal: request.signal,
+    });
+    const minAmountOut = applySlippage(expectedAmountOut, slippageBps);
+    return {
+        provider: 'paraswap',
+        router,
+        payload,
+        expectedAmountOut,
+        minAmountOut,
+        fetchedAt,
+    };
+}
+function validateRequest(req) {
+    if (req.slippageBps !== undefined &&
+        (req.slippageBps < 0 || req.slippageBps >= 10_000)) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', `fetchSwapQuote: slippageBps must be in [0, 10000), got ${req.slippageBps}. 10000 bps = 100% slippage and disables protection entirely; use a tighter bound.`);
+    }
+    if (req.amount === 0n) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', 'fetchSwapQuote: amount must be greater than zero');
+    }
+    if (req.srcToken.toLowerCase() === req.destToken.toLowerCase()) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', 'fetchSwapQuote: srcToken and destToken are identical — no swap needed');
+    }
+}
+function applySlippage(amount, slippageBps) {
+    return (amount * (BPS_DENOMINATOR - BigInt(slippageBps))) / BPS_DENOMINATOR;
+}
+//# sourceMappingURL=index.js.map

package/lib/services/swap-quotes/paraswap.d.ts

@@ -0,0 +1,51 @@
+import type { IAddress } from '../../types';
+export interface IParaswapQuoteInput {
+    chainId: number;
+    srcToken: IAddress;
+    srcDecimals: number;
+    destToken: IAddress;
+    destDecimals: number;
+    amount: bigint;
+    receiver: IAddress;
+    /**
+     * Slippage tolerance in bps (1 bp = 0.01%). Used to derive the
+     * `destAmount` minimum baked into the resulting Paraswap calldata, so the
+     * on-chain DEX leg enforces the same tolerance the SwapRouter does
+     * (otherwise the leg reverts at the aggregator's exact-out check before
+     * the SwapRouter's `minAmountOut` is ever evaluated).
+     */
+    slippageBps: number;
+    partner: string;
+    partnerAddress: IAddress;
+    /**
+     * Optional `includeContractMethods` value passed to Paraswap's `/prices`. When
+     * set, Paraswap is restricted to this single contract method so the resulting
+     * calldata's leading selector is deterministic and matches the one the
+     * SwapRouter authorizes for this router. When omitted, Paraswap is free to
+     * pick whichever method is optimal for the route.
+     */
+    contractMethod?: string;
+    fetchImpl: typeof fetch;
+    signal?: AbortSignal;
+}
+export interface IParaswapQuoteOutput {
+    router: IAddress;
+    payload: `0x${string}`;
+    expectedAmountOut: bigint;
+    fetchedAt: number;
+}
+/**
+ * Fetch a Paraswap quote and the calldata to execute it on behalf of the
+ * SwapRouter. Throws `UpshiftNetworkError` on fetch-layer failure and
+ * `UpshiftServerError` on Paraswap-side error responses or malformed bodies.
+ *
+ * `fetchedAt` is the wall-clock timestamp captured *after* the calldata
+ * response — callers downstream can use it to decide whether the leg is
+ * fresh enough to broadcast (DEX pool state moves; stale calldata may
+ * silently revert at the on-chain slippage check).
+ */
+export declare function fetchParaswapQuote(input: IParaswapQuoteInput): Promise<IParaswapQuoteOutput>;
+export declare const PARASWAP_DEFAULTS: {
+    readonly partner: "upshift";
+    readonly partnerAddress: `0x${string}`;
+};

package/lib/services/swap-quotes/paraswap.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PARASWAP_DEFAULTS = void 0;
+exports.fetchParaswapQuote = fetchParaswapQuote;
+const errors_1 = require("../../core/errors");
+const web3_1 = require("../../core/helpers/web3");
+const PARASWAP_PRICES_URL = 'https://api.paraswap.io/prices';
+const PARASWAP_TRANSACTIONS_BASE_URL = 'https://api.paraswap.io/transactions';
+const DEFAULT_PARTNER = 'upshift';
+const DEFAULT_PARTNER_ADDRESS = '0xb60ee0FA5B6bA917255A03e744967E0Bda531dD0';
+const PARASWAP_VERSION = '6.2';
+const BPS_DENOMINATOR = 10000n;
+/**
+ * Fetch a Paraswap quote and the calldata to execute it on behalf of the
+ * SwapRouter. Throws `UpshiftNetworkError` on fetch-layer failure and
+ * `UpshiftServerError` on Paraswap-side error responses or malformed bodies.
+ *
+ * `fetchedAt` is the wall-clock timestamp captured *after* the calldata
+ * response — callers downstream can use it to decide whether the leg is
+ * fresh enough to broadcast (DEX pool state moves; stale calldata may
+ * silently revert at the on-chain slippage check).
+ */
+async function fetchParaswapQuote(input) {
+    const priceRoute = await getPriceRoute(input);
+    const destAmountRaw = priceRoute.destAmount;
+    if (typeof destAmountRaw !== 'string' || !/^\d+$/.test(destAmountRaw)) {
+        throw new errors_1.UpshiftServerError(200, `fetchSwapQuote: Paraswap /prices returned non-numeric destAmount: ${String(destAmountRaw)}`, { context: { destAmount: destAmountRaw } });
+    }
+    const expectedAmountOut = BigInt(destAmountRaw);
+    const { router, payload } = await getTransactionData(input, priceRoute);
+    return { router, payload, expectedAmountOut, fetchedAt: Date.now() };
+}
+async function getPriceRoute(input) {
+    const params = new URLSearchParams({
+        network: String(input.chainId),
+        srcToken: input.srcToken,
+        srcDecimals: String(input.srcDecimals),
+        destToken: input.destToken,
+        destDecimals: String(input.destDecimals),
+        amount: input.amount.toString(),
+        partner: input.partner,
+        partnerAddress: input.partnerAddress,
+        version: PARASWAP_VERSION,
+    });
+    // Restrict the route to a single contract method when the caller pins one,
+    // so the calldata's selector is deterministic and matches the SwapRouter's
+    // per-router authorized selector. Without this the aggregator may return a
+    // route-optimized method (e.g. swapExactAmountInOnUniswapV3) whose selector
+    // the SwapRouter has not whitelisted, reverting with InvalidNotWhitelisted().
+    if (input.contractMethod) {
+        params.append('includeContractMethods', input.contractMethod);
+    }
+    const url = `${PARASWAP_PRICES_URL}?${params.toString()}`;
+    let response;
+    try {
+        response = await input.fetchImpl(url, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+            signal: input.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.UpshiftNetworkError('fetchSwapQuote: Paraswap /prices fetch failed', { cause, context: { url } });
+    }
+    if (!response.ok) {
+        throw new errors_1.UpshiftServerError(response.status, `fetchSwapQuote: Paraswap /prices returned HTTP ${response.status}`, { context: { url } });
+    }
+    const body = (await response.json());
+    if (body.error) {
+        throw new errors_1.UpshiftServerError(response.status, `fetchSwapQuote: Paraswap /prices error: ${body.error}`, { context: { providerError: body.error } });
+    }
+    if (!body.priceRoute) {
+        throw new errors_1.UpshiftServerError(response.status, 'fetchSwapQuote: Paraswap /prices returned no priceRoute', { context: { body } });
+    }
+    return body.priceRoute;
+}
+async function getTransactionData(input, priceRoute) {
+    const url = `${PARASWAP_TRANSACTIONS_BASE_URL}/${input.chainId}/?ignoreChecks=true&ignoreGasEstimate=true&onlyParams=false`;
+    // Bake slippage into the destAmount Paraswap embeds as the aggregator's
+    // own min-out, so the DEX leg enforces the same lower bound the
+    // SwapRouter will check. Without this the aggregator uses the exact
+    // priceRoute quote (0% tolerance) and reverts on any adverse movement.
+    const expectedDestAmount = BigInt(priceRoute.destAmount);
+    const minDestAmount = (expectedDestAmount * (BPS_DENOMINATOR - BigInt(input.slippageBps))) /
+        BPS_DENOMINATOR;
+    const requestBody = {
+        userAddress: input.receiver,
+        srcToken: input.srcToken,
+        destToken: input.destToken,
+        srcDecimals: input.srcDecimals,
+        destDecimals: input.destDecimals,
+        srcAmount: input.amount.toString(),
+        destAmount: minDestAmount.toString(),
+        priceRoute,
+        partner: input.partner,
+        partnerAddress: input.partnerAddress,
+    };
+    let response;
+    try {
+        response = await input.fetchImpl(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(requestBody),
+            signal: input.signal,
+        });
+    }
+    catch (cause) {
+        throw new errors_1.UpshiftNetworkError('fetchSwapQuote: Paraswap /transactions fetch failed', { cause, context: { url } });
+    }
+    if (!response.ok) {
+        throw new errors_1.UpshiftServerError(response.status, `fetchSwapQuote: Paraswap /transactions returned HTTP ${response.status}`, { context: { url } });
+    }
+    const body = (await response.json());
+    if (body.error) {
+        throw new errors_1.UpshiftServerError(response.status, `fetchSwapQuote: Paraswap /transactions error: ${body.error}`, { context: { providerError: body.error } });
+    }
+    if (!body.to || !body.data) {
+        throw new errors_1.UpshiftServerError(response.status, 'fetchSwapQuote: Paraswap /transactions returned no to/data', { context: { body } });
+    }
+    if (!(0, web3_1.checkAddress)(body.to, console, 'contract')) {
+        throw new errors_1.UpshiftServerError(response.status, `fetchSwapQuote: Paraswap /transactions returned an invalid router address: ${body.to}`, { context: { to: body.to } });
+    }
+    if (!/^0x[0-9a-fA-F]+$/.test(body.data) || body.data.length % 2 !== 0) {
+        throw new errors_1.UpshiftServerError(response.status, `fetchSwapQuote: Paraswap /transactions returned malformed calldata (${body.data.length} chars)`, { context: { dataPrefix: body.data.slice(0, 16) } });
+    }
+    if (body.data.length < 10) {
+        throw new errors_1.UpshiftValidationError('INVALID_INPUT', 'fetchSwapQuote: Paraswap /transactions returned calldata shorter than a 4-byte selector');
+    }
+    return {
+        router: body.to,
+        payload: body.data,
+    };
+}
+exports.PARASWAP_DEFAULTS = {
+    partner: DEFAULT_PARTNER,
+    partnerAddress: DEFAULT_PARTNER_ADDRESS,
+};
+//# sourceMappingURL=paraswap.js.map

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,83 @@
+/**
+ * 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
+     * special: `stellar-wallet` is custody wallet cash, and `upshift` is the
+     * vault's own idle buffer plus any position it holds in another Upshift
+     * vault — only the part beyond the `idle` location is deployed capital.
+     */
+    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