@cygnus-wealth/data-models 1.2.0 → 1.4.0

package/dist/enums/IntegrationSource.js

@@ -61,6 +61,14 @@ export var IntegrationSource;
     IntegrationSource["MANUAL_ENTRY"] = "MANUAL_ENTRY";
     /** Data fetched directly from blockchain via RPC */
     IntegrationSource["BLOCKCHAIN_DIRECT"] = "BLOCKCHAIN_DIRECT";
+    /** SUI blockchain integration */
+    IntegrationSource["SUI"] = "SUI";
+    /** Bitcoin blockchain integration */
+    IntegrationSource["BITCOIN"] = "BITCOIN";
+    /** Cosmos ecosystem integration */
+    IntegrationSource["COSMOS"] = "COSMOS";
+    /** Aptos blockchain integration */
+    IntegrationSource["APTOS"] = "APTOS";
     /** Other or unclassified data source */
     IntegrationSource["OTHER"] = "OTHER";
 })(IntegrationSource || (IntegrationSource = {}));

package/dist/index.d.ts

@@ -1,10 +1,14 @@
 export { AssetType } from './enums/AssetType';
 export { Chain } from './enums/Chain';
+export { ChainFamily } from './enums/ChainFamily';
 export { IntegrationSource } from './enums/IntegrationSource';
 export { TransactionType } from './enums/TransactionType';
 export { AccountType } from './enums/AccountType';
 export { LendingPositionType } from './enums/LendingPositionType';
 export { VaultStrategyType } from './enums/VaultStrategyType';
+export { DeFiPositionType } from './enums/DeFiPositionType';
+export { DeFiProtocol } from './enums/DeFiProtocol';
+export { DeFiDiscoverySource } from './enums/DeFiDiscoverySource';
 export { BaseEntity } from './interfaces/BaseEntity';
 export { Metadata } from './interfaces/Metadata';
 export { Asset } from './interfaces/Asset';
@@ -16,9 +20,28 @@ export { LiquidityPosition } from './interfaces/LiquidityPosition';
 export { StakedPosition } from './interfaces/StakedPosition';
 export { LendingPosition } from './interfaces/LendingPosition';
 export { VaultPosition } from './interfaces/VaultPosition';
+export { DeFiPosition } from './interfaces/DeFiPosition';
 export { Account } from './interfaces/Account';
 export { Portfolio } from './interfaces/Portfolio';
 export { PortfolioAsset } from './interfaces/PortfolioAsset';
+export type { WalletProviderId } from './types/WalletProviderId';
+export type { WalletConnectionId } from './types/WalletConnectionId';
+export type { AccountId } from './types/AccountId';
+export type { Caip2ChainId } from './types/Caip2ChainId';
+export type { WalletConnection } from './interfaces/WalletConnection';
+export type { ConnectedAccount } from './interfaces/ConnectedAccount';
+export type { WatchAddress } from './interfaces/WatchAddress';
+export type { AccountGroup } from './interfaces/AccountGroup';
+export type { AccountPortfolio } from './interfaces/AccountPortfolio';
+export type { WalletPortfolio } from './interfaces/WalletPortfolio';
+export type { GroupPortfolio } from './interfaces/GroupPortfolio';
+export type { AccountSummary } from './interfaces/AccountSummary';
+export type { AssetDistribution } from './interfaces/AssetDistribution';
+export type { AccountAssetEntry } from './interfaces/AccountAssetEntry';
+export type { TrackedAddress } from './interfaces/TrackedAddress';
+export type { AccountMetadata } from './interfaces/AccountMetadata';
+export type { AddressRequest } from './interfaces/AddressRequest';
+export type { AccountBalanceList, AccountBalance, AccountError } from './interfaces/AccountBalanceList';
 export { Transaction } from './interfaces/Transaction';
 export { IntegrationCredentials } from './interfaces/IntegrationCredentials';
 export { SyncStatus } from './interfaces/SyncStatus';

package/dist/index.js

@@ -1,8 +1,12 @@
 // Enums
 export { AssetType } from './enums/AssetType';
 export { Chain } from './enums/Chain';
+export { ChainFamily } from './enums/ChainFamily';
 export { IntegrationSource } from './enums/IntegrationSource';
 export { TransactionType } from './enums/TransactionType';
 export { AccountType } from './enums/AccountType';
 export { LendingPositionType } from './enums/LendingPositionType';
 export { VaultStrategyType } from './enums/VaultStrategyType';
+export { DeFiPositionType } from './enums/DeFiPositionType';
+export { DeFiProtocol } from './enums/DeFiProtocol';
+export { DeFiDiscoverySource } from './enums/DeFiDiscoverySource';

package/dist/interfaces/AccountAssetEntry.d.ts

@@ -0,0 +1,42 @@
+import { AccountId } from '../types/AccountId';
+import { Balance } from './Balance';
+import { Price } from './Price';
+/**
+ * A single account's holding of an asset within an asset distribution.
+ *
+ * Used as part of {@link AssetDistribution} to show how much of a specific
+ * asset is held in each account and what percentage of the total it represents.
+ *
+ * @example
+ * ```typescript
+ * import { AccountAssetEntry } from '@cygnus-wealth/data-models';
+ *
+ * const entry: AccountAssetEntry = {
+ *   accountId: 'metamask:a1b2:0xAbc',
+ *   accountLabel: 'Main DeFi',
+ *   connectionLabel: 'My MetaMask',
+ *   quantity: { assetId: 'eth', asset: ethAsset, amount: '7.0' },
+ *   value: { value: 14000, currency: 'USD', timestamp: new Date() },
+ *   percentage: 66.67
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AssetDistribution} for the parent distribution context
+ */
+export interface AccountAssetEntry {
+    /** Account holding this portion of the asset */
+    accountId: AccountId;
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Label of the parent wallet connection */
+    connectionLabel: string;
+    /** Quantity of the asset in this account */
+    quantity: Balance;
+    /** Value of this account's holding */
+    value: Price;
+    /** Percentage of total for this asset (e.g., 66.67 = 66.67%) */
+    percentage: number;
+}

package/dist/interfaces/AccountAssetEntry.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/AccountBalanceList.d.ts

@@ -0,0 +1,85 @@
+import { AccountId } from '../types/AccountId';
+import { Chain } from '../enums/Chain';
+import { Balance } from './Balance';
+/**
+ * A single account's balance result for a specific chain.
+ *
+ * Contains the native balance and token balances for one account
+ * on one chain, with the AccountId for attribution.
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountBalanceList} for the container type
+ */
+export interface AccountBalance {
+    /** Account this balance belongs to */
+    accountId: AccountId;
+    /** Checksummed address */
+    address: string;
+    /** Chain this balance was fetched from */
+    chainId: Chain;
+    /** Native token balance (e.g., ETH on Ethereum) */
+    nativeBalance: Balance;
+    /** ERC-20 and other token balances */
+    tokenBalances: Balance[];
+}
+/**
+ * Error encountered while fetching data for a specific account.
+ *
+ * Supports partial failure: some accounts may succeed while others fail.
+ *
+ * @since 1.3.0
+ * @stability extended
+ */
+export interface AccountError {
+    /** Account that encountered the error */
+    accountId: AccountId;
+    /** Chain where the error occurred */
+    chainId: Chain;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code?: string;
+}
+/**
+ * Account-attributed balance results with support for partial failure.
+ *
+ * Returned by integration contracts when fetching balances for multiple
+ * accounts. Each balance carries its AccountId for attribution, and
+ * per-account errors are reported separately.
+ *
+ * @example
+ * ```typescript
+ * import { AccountBalanceList } from '@cygnus-wealth/data-models';
+ *
+ * const result: AccountBalanceList = {
+ *   balances: [
+ *     {
+ *       accountId: 'metamask:a1b2:0xAbc',
+ *       address: '0xAbc',
+ *       chainId: Chain.ETHEREUM,
+ *       nativeBalance: ethBalance,
+ *       tokenBalances: [usdcBalance, daiBalance]
+ *     }
+ *   ],
+ *   errors: [],
+ *   timestamp: '2026-02-19T08:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AddressRequest} for the request format
+ * @see {@link AccountBalance} for individual balance results
+ * @see {@link AccountError} for per-account errors
+ */
+export interface AccountBalanceList {
+    /** Successful balance results */
+    balances: AccountBalance[];
+    /** Per-account errors (partial failure) */
+    errors: AccountError[];
+    /** ISO 8601 timestamp of the fetch */
+    timestamp: string;
+}

package/dist/interfaces/AccountBalanceList.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/AccountGroup.d.ts

@@ -0,0 +1,37 @@
+import { AccountId } from '../types/AccountId';
+/**
+ * User-defined grouping of accounts for organizational purposes.
+ *
+ * Allows users to create custom groups like "DeFi Accounts", "Long-term Holdings",
+ * or "Family" that span across wallet connections and watch addresses.
+ *
+ * @example
+ * ```typescript
+ * import { AccountGroup } from '@cygnus-wealth/data-models';
+ *
+ * const group: AccountGroup = {
+ *   groupId: 'group-defi-1',
+ *   groupName: 'DeFi Accounts',
+ *   accountIds: [
+ *     'metamask:a1b2c3d4:0xAbC...123',
+ *     'rabby:e5f6g7h8:0xDef...456'
+ *   ],
+ *   createdAt: '2026-02-10T09:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountId} for account identifier format
+ */
+export interface AccountGroup {
+    /** Unique group identifier */
+    groupId: string;
+    /** User-assigned group name */
+    groupName: string;
+    /** References to accounts from any connection or watch addresses */
+    accountIds: AccountId[];
+    /** ISO 8601 timestamp when the group was created */
+    createdAt: string;
+}

package/dist/interfaces/AccountGroup.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/AccountMetadata.d.ts

@@ -0,0 +1,54 @@
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
+import { WalletProviderId } from '../types/WalletProviderId';
+/**
+ * Full metadata for an account, including group membership and lifecycle status.
+ *
+ * Provides comprehensive account context for portfolio aggregation and UI
+ * display, combining identity, labeling, and status information.
+ *
+ * @example
+ * ```typescript
+ * import { AccountMetadata } from '@cygnus-wealth/data-models';
+ *
+ * const metadata: AccountMetadata = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   address: '0xAbCdEf1234567890',
+ *   accountLabel: 'Main DeFi',
+ *   connectionLabel: 'My MetaMask',
+ *   providerId: 'metamask',
+ *   walletConnectionId: 'metamask:a1b2c3d4',
+ *   groups: ['group-defi-1'],
+ *   discoveredAt: '2026-01-15T10:30:00Z',
+ *   isStale: false,
+ *   isActive: true
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link TrackedAddress} for the lightweight address tracking variant
+ */
+export interface AccountMetadata {
+    /** Account identifier */
+    accountId: AccountId;
+    /** Checksummed address */
+    address: string;
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Label of the parent wallet connection */
+    connectionLabel: string;
+    /** Wallet provider identifier, or 'watch' for watch addresses */
+    providerId: WalletProviderId | 'watch';
+    /** Wallet connection identifier, or 'watch' for watch addresses */
+    walletConnectionId: WalletConnectionId | 'watch';
+    /** Group IDs this account belongs to */
+    groups: string[];
+    /** ISO 8601 timestamp when first discovered */
+    discoveredAt: string;
+    /** Whether the provider no longer exposes this account */
+    isStale: boolean;
+    /** Whether this is the currently active account in the provider */
+    isActive: boolean;
+}

package/dist/interfaces/AccountMetadata.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/AccountPortfolio.d.ts

@@ -0,0 +1,47 @@
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
+import { Asset } from './Asset';
+import { Price } from './Price';
+/**
+ * Portfolio slice for a single account.
+ *
+ * Represents the holdings attributed to one specific account, whether
+ * it's a connected wallet account or a watch address.
+ *
+ * @example
+ * ```typescript
+ * import { AccountPortfolio } from '@cygnus-wealth/data-models';
+ *
+ * const accountPortfolio: AccountPortfolio = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   accountLabel: 'Main DeFi',
+ *   walletConnectionId: 'metamask:a1b2c3d4',
+ *   providerName: 'MetaMask',
+ *   assets: [],
+ *   totalValue: { value: 25000, currency: 'USD', timestamp: new Date() },
+ *   lastUpdated: '2026-02-19T08:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link WalletPortfolio} for per-wallet rollup
+ * @see {@link Portfolio} for aggregate portfolio
+ */
+export interface AccountPortfolio {
+    /** Account this portfolio slice belongs to */
+    accountId: AccountId;
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Wallet connection this account belongs to, or 'watch' for watch addresses */
+    walletConnectionId: WalletConnectionId | 'watch';
+    /** Human-readable provider name */
+    providerName: string;
+    /** Assets held in this account */
+    assets: Asset[];
+    /** Total value of this account's holdings */
+    totalValue: Price;
+    /** ISO 8601 timestamp of last data update */
+    lastUpdated: string;
+}

package/dist/interfaces/AccountPortfolio.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/AccountSummary.d.ts

@@ -0,0 +1,49 @@
+import { AccountId } from '../types/AccountId';
+import { WalletProviderId } from '../types/WalletProviderId';
+import { Chain } from '../enums/Chain';
+import { Price } from './Price';
+/**
+ * Summary view of an account for cross-account analysis.
+ *
+ * Lightweight representation containing key metrics for each account,
+ * suitable for dashboard summary views and account comparison.
+ *
+ * @example
+ * ```typescript
+ * import { AccountSummary } from '@cygnus-wealth/data-models';
+ *
+ * const summary: AccountSummary = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   accountLabel: 'Main DeFi',
+ *   connectionLabel: 'My MetaMask',
+ *   providerId: 'metamask',
+ *   totalValue: { value: 25000, currency: 'USD', timestamp: new Date() },
+ *   assetCount: 12,
+ *   chains: [Chain.ETHEREUM, Chain.POLYGON],
+ *   lastUpdated: '2026-02-19T08:00:00Z'
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountPortfolio} for full account portfolio details
+ */
+export interface AccountSummary {
+    /** Account identifier */
+    accountId: AccountId;
+    /** User-assigned account label */
+    accountLabel: string;
+    /** Label of the parent wallet connection */
+    connectionLabel: string;
+    /** Wallet provider identifier, or 'watch' for watch addresses */
+    providerId: WalletProviderId | 'watch';
+    /** Total value of the account's holdings */
+    totalValue: Price;
+    /** Number of distinct assets held */
+    assetCount: number;
+    /** Chains this account has activity on */
+    chains: Chain[];
+    /** ISO 8601 timestamp of last data update */
+    lastUpdated: string;
+}

package/dist/interfaces/AccountSummary.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/AddressRequest.d.ts

@@ -0,0 +1,36 @@
+import { AccountId } from '../types/AccountId';
+import { Chain } from '../enums/Chain';
+import { ChainFamily } from '../enums/ChainFamily';
+/**
+ * Request to query data for a specific account address.
+ *
+ * Used by integration contracts to request data with account attribution.
+ * Carries the AccountId so results can be attributed back to the originating
+ * account, and includes chain scope for per-account chain filtering.
+ *
+ * @example
+ * ```typescript
+ * import { AddressRequest, Chain } from '@cygnus-wealth/data-models';
+ *
+ * const request: AddressRequest = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   address: '0xAbCdEf1234567890',
+ *   chainScope: [Chain.ETHEREUM, Chain.POLYGON, Chain.ARBITRUM]
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountBalanceList} for the response format
+ */
+export interface AddressRequest {
+    /** Account identifier for result attribution */
+    accountId: AccountId;
+    /** Checksummed address to query */
+    address: string;
+    /** Chain family for routing to the correct integration */
+    chainFamily: ChainFamily;
+    /** Chains to query for this address */
+    chainScope: Chain[];
+}

package/dist/interfaces/AddressRequest.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/Asset.d.ts

@@ -1,5 +1,7 @@
 import { AssetType } from '../enums/AssetType';
 import { Chain } from '../enums/Chain';
+import { AccountId } from '../types/AccountId';
+import { WalletConnectionId } from '../types/WalletConnectionId';
 import { Metadata } from './Metadata';
 /**
  * Universal asset representation normalizing data from multiple sources.
@@ -72,6 +74,10 @@ export interface Asset {
     cusip?: string;
     /** ISIN identifier for international securities */
     isin?: string;
+    /** Account holding this asset (for multi-wallet multi-account attribution) */
+    accountId?: AccountId;
+    /** Wallet connection this asset belongs to, or 'watch' for watch addresses */
+    walletConnectionId?: WalletConnectionId | 'watch';
     /** Source-specific additional data and custom fields */
     metadata?: Metadata;
 }

package/dist/interfaces/AssetDistribution.d.ts

@@ -0,0 +1,45 @@
+import { Balance } from './Balance';
+import { Price } from './Price';
+import { AccountAssetEntry } from './AccountAssetEntry';
+/**
+ * Distribution of a specific asset across multiple accounts.
+ *
+ * Shows how holdings of a single asset (by symbol) are distributed
+ * across the user's accounts, useful for concentration analysis.
+ *
+ * @example
+ * ```typescript
+ * import { AssetDistribution } from '@cygnus-wealth/data-models';
+ *
+ * const ethDistribution: AssetDistribution = {
+ *   symbol: 'ETH',
+ *   totalQuantity: { assetId: 'eth', asset: ethAsset, amount: '10.5' },
+ *   totalValue: { value: 21000, currency: 'USD', timestamp: new Date() },
+ *   distribution: [
+ *     {
+ *       accountId: 'metamask:a1b2:0xAbc',
+ *       accountLabel: 'Main',
+ *       connectionLabel: 'MetaMask',
+ *       quantity: { assetId: 'eth', asset: ethAsset, amount: '7.0' },
+ *       value: { value: 14000, currency: 'USD', timestamp: new Date() },
+ *       percentage: 66.67
+ *     }
+ *   ]
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link AccountAssetEntry} for per-account breakdown
+ */
+export interface AssetDistribution {
+    /** Asset trading symbol */
+    symbol: string;
+    /** Total quantity across all accounts */
+    totalQuantity: Balance;
+    /** Total value across all accounts */
+    totalValue: Price;
+    /** Per-account breakdown of this asset's distribution */
+    distribution: AccountAssetEntry[];
+}

package/dist/interfaces/AssetDistribution.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/ConnectedAccount.d.ts

@@ -0,0 +1,52 @@
+import { AccountId } from '../types/AccountId';
+import { Chain } from '../enums/Chain';
+import { ChainFamily } from '../enums/ChainFamily';
+/**
+ * A single account within a wallet connection.
+ *
+ * Represents an address discovered via a wallet provider (EIP-1193) or
+ * manually added to a connection's account list. Tracks discovery time,
+ * staleness, and active status relative to the wallet provider.
+ *
+ * @example
+ * ```typescript
+ * import { ConnectedAccount } from '@cygnus-wealth/data-models';
+ *
+ * const account: ConnectedAccount = {
+ *   accountId: 'metamask:a1b2c3d4:0xAbCdEf1234567890',
+ *   address: '0xAbCdEf1234567890',
+ *   accountLabel: 'Main DeFi',
+ *   chainScope: [Chain.ETHEREUM, Chain.POLYGON],
+ *   source: 'provider',
+ *   discoveredAt: '2026-01-15T10:30:00Z',
+ *   isStale: false,
+ *   isActive: true
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link WalletConnection} for the parent connection
+ * @see {@link AccountId} for identifier format
+ */
+export interface ConnectedAccount {
+    /** Unique account identifier: `{walletConnectionId}:{checksummedAddress}` */
+    accountId: AccountId;
+    /** Checksummed EVM address */
+    address: string;
+    /** User-assigned label (default: truncated address) */
+    accountLabel: string;
+    /** Chain family this account belongs to */
+    chainFamily: ChainFamily;
+    /** Chains to track this account on (default: all supported by the connection) */
+    chainScope: Chain[];
+    /** How this account was added: 'provider' = discovered via EIP-1193; 'manual' = user typed the address */
+    source: 'provider' | 'manual';
+    /** ISO 8601 timestamp when first seen */
+    discoveredAt: string;
+    /** True if the provider no longer includes this account in eth_requestAccounts responses */
+    isStale: boolean;
+    /** True if this is the currently selected account in the wallet provider */
+    isActive: boolean;
+}

package/dist/interfaces/ConnectedAccount.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/DeFiPosition.d.ts

@@ -0,0 +1,79 @@
+import { Chain } from '../enums/Chain';
+import { DeFiPositionType } from '../enums/DeFiPositionType';
+import { DeFiProtocol } from '../enums/DeFiProtocol';
+import { DeFiDiscoverySource } from '../enums/DeFiDiscoverySource';
+import { AccountId } from '../types/AccountId';
+import { Balance } from './Balance';
+import { Price } from './Price';
+import { Metadata } from './Metadata';
+/**
+ * Base interface for all DeFi positions across protocols and chains.
+ *
+ * Provides a unified shape for any DeFi position — vaults, lending, liquidity
+ * pools, staking, farming, and perp positions. Concrete subtypes
+ * ({@link VaultPosition}, {@link LendingPosition}, {@link LiquidityPosition},
+ * {@link StakedPosition}) add protocol-specific fields.
+ *
+ * **Discovery Paths:**
+ * - `WALLET_TOKEN_SCAN` — position inferred from receipt tokens in wallet
+ * - `CONTRACT_QUERY` — position read from protocol contract state
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   DeFiPosition,
+ *   DeFiPositionType,
+ *   DeFiProtocol,
+ *   DeFiDiscoverySource,
+ *   Chain
+ * } from '@cygnus-wealth/data-models';
+ *
+ * const position: DeFiPosition = {
+ *   id: 'aave-supply-usdc-1',
+ *   type: DeFiPositionType.LENDING_SUPPLY,
+ *   protocol: DeFiProtocol.AAVE,
+ *   chain: Chain.ETHEREUM,
+ *   underlyingAssets: [{
+ *     assetId: 'ethereum-usdc',
+ *     asset: { id: 'ethereum-usdc', symbol: 'USDC', name: 'USD Coin', type: 'CRYPTOCURRENCY', decimals: 6 },
+ *     amount: '50000'
+ *   }],
+ *   value: { value: 50125.50, currency: 'USD', timestamp: new Date() },
+ *   apy: 3.5,
+ *   rewards: [],
+ *   discoverySource: DeFiDiscoverySource.CONTRACT_QUERY
+ * };
+ * ```
+ *
+ * @since 1.3.0
+ * @stability extended
+ *
+ * @see {@link VaultPosition} for vault-specific fields
+ * @see {@link LendingPosition} for lending-specific fields
+ * @see {@link LiquidityPosition} for LP-specific fields
+ * @see {@link StakedPosition} for staking-specific fields
+ */
+export interface DeFiPosition {
+    /** Unique identifier for this position */
+    id: string;
+    /** Classification of the DeFi position */
+    type: DeFiPositionType;
+    /** Protocol where the position exists */
+    protocol: DeFiProtocol;
+    /** Blockchain network where the position exists */
+    chain: Chain;
+    /** Underlying assets in this position (tokens deposited, staked, or provided) */
+    underlyingAssets: Balance[];
+    /** Current total value of the position */
+    value?: Price;
+    /** Annual Percentage Yield or Rate (e.g., 8.5 = 8.5%) */
+    apy?: number;
+    /** Earned rewards (claimable or accrued incentive tokens) */
+    rewards: Balance[];
+    /** How this position was discovered during portfolio scanning */
+    discoverySource?: DeFiDiscoverySource;
+    /** Account identifier for multi-wallet attribution (alongside ownerAddress) */
+    accountId?: AccountId;
+    /** Protocol-specific metadata (version, contract addresses, TVL, etc.) */
+    metadata?: Metadata;
+}

package/dist/interfaces/DeFiPosition.js

@@ -0,0 +1 @@
+export {};