@liberfi.io/client 0.1.189 → 0.3.0

package/README.md

@@ -8,6 +8,7 @@ DEX API client for the Liberfi React SDK. This package wraps `@chainstream-io/sd
 - **Centralized DTO conversion** — All mapping functions live in `utils.ts`, separating data transformation from client orchestration.
 - **Interface conformance** — `Client implements API.IClient, API.ISubscribeClient` ensures compile-time contract enforcement.
 - **Composite subscriptions** — WebSocket methods compose multiple backend channels into a single `ISubscription` with a unified `unsubscribe()`.
+- **Phase 3 bypass layer** — For endpoints the upstream `@chainstream-io/sdk` has not yet upgraded (`getTokenHolders`, `getTokenActivities`, `getWalletActivities`, `getWalletPortfoliosByTokens`, `getWalletPortfolioPnls`), `Client` uses an internal `phase3Http` fetch helper that calls the server directly and maps the raw DTOs back to domain types. Consumers keep the same `IClient` interface.
 
 ## Installation
 

package/dist/index.d.mts

@@ -1,5 +1,6 @@
+import * as _liberfi_io_types from '@liberfi.io/types';
 import { API, Chain, Token, TokenResolution, TokenCandle, TokenSecurity, TokenStats, TokenHolder, TokenMarketData, WalletPortfolios, WalletPnl, WalletPortfolioPnls, Portfolio, PortfolioPnl, Trade, Activity, TokenCreator as TokenCreator$1, TokenLiquidity } from '@liberfi.io/types';
-import { ChainSymbol, Resolution, RangeFilterCondition, TokenCreator, Token as Token$1, TokenStats as TokenStats$1, DexPool, TokenMarketData as TokenMarketData$1, TokenCandle as TokenCandle$1, SwapRouteInput, SendTxInput, PageResponseTokenHolder, TokenPage, SwapRouteResponse, BlockchainLatestBlock, SendTxResponse, WalletNetWorthPage, WalletPnlSummary, PnlDetailsResult, NetWorthByTokensResult, PageResponseTradeDetail, WsNewToken, WsTokenMetadata, WsCandle, WsTokenStat, WsTokenSupply, WsTokenHolder, WsTokenLiquidity, WsTokenBondingCurve, WsTokenMaxLiquidity, WsTokenTotalLiquidity, WsTradeActivity } from '@chainstream-io/sdk';
+import { ChainSymbol, Resolution, RangeFilterCondition, TokenCreator, Token as Token$1, TokenStats as TokenStats$1, DexPool, TokenMarketData as TokenMarketData$1, TokenCandle as TokenCandle$1, SwapRouteInput, SendTxInput, TokenPage, SwapRouteResponse, BlockchainLatestBlock, SendTxResponse, WalletNetWorthPage, WalletPnlSummary, PnlDetailsResult, PageResponseTradeDetail, WsNewToken, WsTokenMetadata, WsCandle, WsTokenStat, WsTokenSupply, WsTokenHolder, WsTokenLiquidity, WsTokenBondingCurve, WsTokenMaxLiquidity, WsTokenTotalLiquidity, WsTradeActivity } from '@chainstream-io/sdk';
 
 declare global {
     interface Window {
@@ -8,7 +9,7 @@ declare global {
         };
     }
 }
-declare const _default: "0.1.189";
+declare const _default: "0.3.0";
 
 /** Async or sync token provider for authentication. */
 interface ClientTokenProviderFn {
@@ -33,13 +34,14 @@ declare class Client implements API.IClient, API.ISubscribeClient {
     private readonly accessToken;
     private readonly options?;
     private readonly _client;
+    private readonly _phase3;
     constructor(accessToken: ClientTokenProvider, options?: ClientOptions | undefined);
     getToken(chain: Chain, address: string): Promise<Token>;
     getTokens(chain: Chain, addresses: Array<string>): Promise<Array<Token>>;
     getTokenCandles(chain: Chain, address: string, resolution: TokenResolution, options?: API.GetTokenCandlesOptions): Promise<Array<TokenCandle>>;
     getTokenSecurity(chain: Chain, address: string): Promise<TokenSecurity>;
     getTokenStats(chain: Chain, address: string): Promise<TokenStats>;
-    getTokenHolders(chain: Chain, address: string, options?: API.CursorListOptions): Promise<API.CursorList<TokenHolder>>;
+    getTokenHolders(chain: Chain, address: string, options?: API.GetTokenHoldersOptions): Promise<API.CursorList<TokenHolder>>;
     getTokenMarketData(chain: Chain, address: string): Promise<TokenMarketData>;
     getNewTokens(chain: Chain, options?: API.GetTokenListOptions): Promise<Array<Token>>;
     getFinalStretchTokens(chain: Chain, options?: API.GetTokenListOptions): Promise<Array<Token>>;
@@ -56,10 +58,7 @@ declare class Client implements API.IClient, API.ISubscribeClient {
         limit?: number;
     }): Promise<WalletPortfolios>;
     getWalletPnl(chain: Chain, address: string, resolution?: string): Promise<WalletPnl>;
-    getWalletPortfolioPnls(chain: Chain, address: string, options?: {
-        cursor?: string;
-        limit?: number;
-    }): Promise<WalletPortfolioPnls>;
+    getWalletPortfolioPnls(chain: Chain, address: string, options?: API.GetWalletPortfolioPnlsOptions): Promise<WalletPortfolioPnls>;
     getWalletPortfoliosByTokens(chain: Chain, address: string, tokenAddresses: Array<string>): Promise<Array<Portfolio>>;
     getWalletPortfolioPnlsByTokens(chain: Chain, address: string, tokenAddresses: Array<string>): Promise<Array<PortfolioPnl>>;
     getWalletTrades(chain: Chain, address: string, options?: API.GetTradesOptions): Promise<API.CursorList<Trade>>;
@@ -67,6 +66,8 @@ declare class Client implements API.IClient, API.ISubscribeClient {
     getWalletActivities(chain: Chain, address: string, options?: API.GetActivitiesOptions): Promise<API.CursorList<Activity>>;
     getTokenActivities(chain: Chain, address: string, options?: API.GetActivitiesOptions): Promise<API.CursorList<Activity>>;
     getPresignedUploadUrl(): Promise<string>;
+    getWalletLimitOrders(_chain: Chain, _address: string, _options?: API.GetWalletLimitOrdersOptions): Promise<API.CursorList<_liberfi_io_types.LimitOrder>>;
+    getTokensByCreator(_chain: Chain, _creator: string, _options?: API.GetTokensByCreatorOptions): Promise<API.CursorList<Token>>;
     subscribeToken(chain: Chain, address: string, callback: (data: Array<API.TokenSubscribed>) => void): API.ISubscription;
     subscribeTokenCandles(chain: Chain, address: string, resolution: TokenResolution, callback: (candles: Array<TokenCandle>) => void): API.ISubscription;
     subscribeWalletPnl(chain: Chain, address: string, callback: (pnls: Array<API.WalletPnlSubscribed>) => void): API.ISubscription;
@@ -98,6 +99,167 @@ declare class Client implements API.IClient, API.ISubscribeClient {
     private _subscribeRankingTokens;
 }
 
+/**
+ * Error thrown when a Client method is called against a server endpoint
+ * that has not yet shipped. This is distinct from a network / auth error:
+ * the SDK is structurally ready to call the endpoint but the backend
+ * side is not.
+ *
+ * Widgets can use `instanceof NotImplementedError` (or check `code`) to
+ * render a "coming soon" empty state instead of a generic error surface.
+ */
+declare class NotImplementedError extends Error {
+    /** Stable discriminant, useful across package boundaries where `instanceof` may be brittle. */
+    readonly code: "NotImplemented";
+    constructor(method: string, detail?: string);
+}
+/** Type guard using the stable code so it survives bundling across realms. */
+declare function isNotImplementedError(error: unknown): error is NotImplementedError;
+
+/**
+ * Phase 3 HTTP helpers.
+ *
+ * The bundled `@chainstream-io/sdk` version pins an older schema that does not
+ * recognize the Phase 3 parameters (`sortBy`, `positionState`, `resolution`) or
+ * response fields (`gasFee`, `traderTags`, `tags`, `lastActiveAt`, `avgCostUsd`,
+ * `isActive`, `walletTokenTags`, `isClosed`, `firstBuyAt`, `lastSellAt`).
+ *
+ * Rather than wait for the SDK to be regenerated, this module issues direct
+ * `fetch` calls against the same REST endpoints the SDK would have hit, and
+ * types the raw DTOs as described in the 2026-05-01 Phase 3 spec. Mapping from
+ * DTO → domain type stays in `utils.ts`.
+ *
+ * Once the SDK adopts Phase 3, this module can be deleted and Client can call
+ * the SDK methods again without touching any consumer code.
+ */
+
+interface CursorPageDTO<T> {
+    data: Array<T>;
+    hasNext: boolean;
+    hasPrev: boolean;
+    startCursor?: string | null;
+    endCursor?: string | null;
+}
+interface Phase3TokenHolderDTO {
+    walletAddress: string;
+    amount: string;
+    amountInUsd: string;
+    percentage: string;
+    tags?: Array<string>;
+    lastActiveAt?: number | null;
+    startHoldingAt?: number | null;
+}
+interface Phase3ActivityDTO {
+    transactionSignature: string;
+    chain: string;
+    blockHeight?: number;
+    blockTimestamp: number;
+    type: string;
+    tokenAddress: string;
+    tokenName?: string;
+    tokenSymbol: string;
+    tokenImageUrl?: string | null;
+    tokenAmount: string;
+    tokenAmountInUsd: string;
+    tokenPriceInUsd?: string;
+    tokenAmountInNative?: string;
+    tokenPriceInNative?: string;
+    sideTokenAddress: string;
+    sideTokenName?: string;
+    sideTokenSymbol: string;
+    sideTokenImageUrl?: string | null;
+    sideTokenAmount: string;
+    sideTokenAmountInUsd: string;
+    sideTokenPriceInUsd?: string;
+    accountOwnerAddress: string;
+    gasFee?: number | null;
+    traderTags?: Array<string>;
+    poolAddress?: string | null;
+    dexProgramAddress?: string | null;
+    dexProtocolFamily?: string | null;
+    dexImage?: string | null;
+    status?: string;
+}
+interface Phase3NetWorthTokenDTO {
+    chain: string;
+    tokenAddress: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    logoUri?: string | null;
+    amount: string;
+    priceInUsd: string;
+    priceInNative: string;
+    valueInUsd: string;
+    valueInNative: string;
+    isActive?: boolean;
+    avgCostUsd?: string | null;
+    lastActiveAt?: number | null;
+    walletTokenTags?: Array<string>;
+}
+interface Phase3NetWorthByTokensDTO {
+    walletAddress: string;
+    totalValueInUsd: string;
+    totalValueInNative: string;
+    currentTimestamp?: number;
+    data: Array<Phase3NetWorthTokenDTO>;
+}
+interface Phase3PnlSummaryDTO {
+    tokens?: number | string;
+    totalTrades?: number | string;
+    buys?: number | string;
+    sells?: number | string;
+    wins?: number | string;
+    losses?: number | string;
+    winRate?: string | null;
+    realizedProfitInUsd?: string | null;
+    unrealizedProfitInUsd?: string | null;
+    totalProfitInUsd?: string | null;
+    totalProfitRatio?: string | null;
+    currentValue?: string | null;
+    buyAmountInUsd?: string | null;
+    sellAmountInUsd?: string | null;
+    totalCostInUsd?: string;
+    avgProfitPerTradeInUsd?: string | null;
+}
+interface Phase3PnlItemDTO {
+    tokenAddress: string;
+    symbol?: string;
+    name?: string;
+    decimals?: number;
+    logoUri?: string | null;
+    walletAddress?: string;
+    chain?: string;
+    balance: string;
+    priceInUsd: string;
+    currentValue: string;
+    realizedProfitInUsd?: string;
+    realizedProfitRatio?: string;
+    unrealizedProfitInUsd?: string;
+    unrealizedProfitRatio?: string;
+    totalProfitInUsd?: string;
+    totalProfitRatio?: string;
+    buys?: number | string;
+    sells?: number | string;
+    totalTrades?: number | string;
+    wins?: number | string;
+    losses?: number | string;
+    buyAmount?: string;
+    sellAmount?: string;
+    buyAmountInUsd?: string;
+    sellAmountInUsd?: string;
+    avgBuyPriceInUsd?: string;
+    avgSellPriceInUsd?: string;
+    avgProfitPerTradeInUsd?: string;
+    totalCostInUsd?: string;
+    isClosed?: boolean;
+    firstBuyAt?: number | null;
+    lastSellAt?: number | null;
+}
+interface Phase3PnlDetailsDTO extends CursorPageDTO<Phase3PnlItemDTO> {
+    summary: Phase3PnlSummaryDTO;
+}
+
 declare function toChainDTO(chain: Chain): ChainSymbol;
 declare function toResolutionDTO(resolution: TokenResolution): Resolution;
 declare function toSortDirectionDTO(direction: "asc" | "desc"): string;
@@ -126,18 +288,18 @@ declare const KYBERSWAP_NATIVE_SENTINEL = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeee
 declare function toMintForRoute(dex: "jupiter" | "kyberswap", address: string): string;
 declare function toSwapRouteInput(params: API.SwapParams): SwapRouteInput;
 declare function toSendTxInput(params: API.SendTxParams): SendTxInput;
-declare function fromTokenHolderPage(input: PageResponseTokenHolder): API.CursorList<TokenHolder>;
+declare function fromTokenHolderPage(input: CursorPageDTO<Phase3TokenHolderDTO>): API.CursorList<TokenHolder>;
 declare function fromTokenPage(input: TokenPage): API.SearchTokenCursorList;
 declare function fromSwapRoute(input: SwapRouteResponse): API.SwapRoute;
 declare function fromLatestBlock(input: BlockchainLatestBlock): API.BlockchainLatestBlock;
 declare function fromSendTxResult(input: SendTxResponse): API.SendTxResult;
 declare function fromWalletPortfolios(chain: Chain, input: WalletNetWorthPage): WalletPortfolios;
 declare function fromWalletPnlSummary(chain: Chain, address: string, input: WalletPnlSummary): WalletPnl;
-declare function fromPnlDetailsPage(chain: Chain, address: string, input: PnlDetailsResult): WalletPortfolioPnls;
-declare function fromWalletNetWorthByTokens(chain: Chain, input: NetWorthByTokensResult): Portfolio[];
+declare function fromPnlDetailsPage(chain: Chain, address: string, input: Phase3PnlDetailsDTO): WalletPortfolioPnls;
+declare function fromWalletNetWorthByTokens(chain: Chain, input: Phase3NetWorthByTokensDTO): Portfolio[];
 declare function fromPnlDetailItems(chain: Chain, input: PnlDetailsResult): PortfolioPnl[];
 declare function fromTradePage(input: PageResponseTradeDetail): API.CursorList<Trade>;
-declare function fromActivityPage(input: PageResponseTradeDetail): API.CursorList<Activity>;
+declare function fromActivityPage(input: CursorPageDTO<Phase3ActivityDTO>): API.CursorList<Activity>;
 declare function fromTokenSubscribed(chain: Chain, input: WsNewToken): API.TokenSubscribed;
 declare function fromTokenMetadataSubscribed(chain: Chain, input: WsTokenMetadata): API.TokenSubscribed;
 declare function fromWsCandle(input: WsCandle): TokenCandle;
@@ -154,4 +316,4 @@ declare function fromWsTokenMarketDataFromHolder(input: WsTokenHolder): Partial<
 declare function fromWsTradeActivity(chain: Chain, input: WsTradeActivity): Trade;
 declare function fromWsActivity(chain: Chain, input: WsTradeActivity): Activity;
 
-export { Client, type ClientOptions, type ClientTokenProvider, type ClientTokenProviderFn, KYBERSWAP_NATIVE_SENTINEL, fromActivityPage, fromChainDTO, fromLatestBlock, fromPnlDetailItems, fromPnlDetailsPage, fromSendTxResult, fromSwapRoute, fromTokenCandle, fromTokenCreatorDTO, fromTokenDTO, fromTokenHolderPage, fromTokenLiquidityDTO, fromTokenMarketDataDTO, fromTokenMetadataSubscribed, fromTokenPage, fromTokenSecurity, fromTokenStatsDTO, fromTokenSubscribed, fromTradePage, fromWalletNetWorthByTokens, fromWalletPnlSummary, fromWalletPortfolios, fromWsActivity, fromWsCandle, fromWsTokenBondingCurveToSubscribed, fromWsTokenDataSubscribed, fromWsTokenHolderToSubscribed, fromWsTokenLiquidityToSubscribed, fromWsTokenMarketDataFromHolder, fromWsTokenMarketDataFromStats, fromWsTokenMaxLiquidityToSubscribed, fromWsTokenStats, fromWsTokenSupplyToSubscribed, fromWsTokenTotalLiquidityToSubscribed, fromWsTradeActivity, toChainDTO, toFieldDTO, toMintForRoute, toRangeFiltersDTO, toResolutionDTO, toSearchFieldDTO, toSendTxInput, toSortDirectionDTO, toSwapRouteInput, _default as version };
+export { Client, type ClientOptions, type ClientTokenProvider, type ClientTokenProviderFn, KYBERSWAP_NATIVE_SENTINEL, NotImplementedError, fromActivityPage, fromChainDTO, fromLatestBlock, fromPnlDetailItems, fromPnlDetailsPage, fromSendTxResult, fromSwapRoute, fromTokenCandle, fromTokenCreatorDTO, fromTokenDTO, fromTokenHolderPage, fromTokenLiquidityDTO, fromTokenMarketDataDTO, fromTokenMetadataSubscribed, fromTokenPage, fromTokenSecurity, fromTokenStatsDTO, fromTokenSubscribed, fromTradePage, fromWalletNetWorthByTokens, fromWalletPnlSummary, fromWalletPortfolios, fromWsActivity, fromWsCandle, fromWsTokenBondingCurveToSubscribed, fromWsTokenDataSubscribed, fromWsTokenHolderToSubscribed, fromWsTokenLiquidityToSubscribed, fromWsTokenMarketDataFromHolder, fromWsTokenMarketDataFromStats, fromWsTokenMaxLiquidityToSubscribed, fromWsTokenStats, fromWsTokenSupplyToSubscribed, fromWsTokenTotalLiquidityToSubscribed, fromWsTradeActivity, isNotImplementedError, toChainDTO, toFieldDTO, toMintForRoute, toRangeFiltersDTO, toResolutionDTO, toSearchFieldDTO, toSendTxInput, toSortDirectionDTO, toSwapRouteInput, _default as version };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
+import * as _liberfi_io_types from '@liberfi.io/types';
 import { API, Chain, Token, TokenResolution, TokenCandle, TokenSecurity, TokenStats, TokenHolder, TokenMarketData, WalletPortfolios, WalletPnl, WalletPortfolioPnls, Portfolio, PortfolioPnl, Trade, Activity, TokenCreator as TokenCreator$1, TokenLiquidity } from '@liberfi.io/types';
-import { ChainSymbol, Resolution, RangeFilterCondition, TokenCreator, Token as Token$1, TokenStats as TokenStats$1, DexPool, TokenMarketData as TokenMarketData$1, TokenCandle as TokenCandle$1, SwapRouteInput, SendTxInput, PageResponseTokenHolder, TokenPage, SwapRouteResponse, BlockchainLatestBlock, SendTxResponse, WalletNetWorthPage, WalletPnlSummary, PnlDetailsResult, NetWorthByTokensResult, PageResponseTradeDetail, WsNewToken, WsTokenMetadata, WsCandle, WsTokenStat, WsTokenSupply, WsTokenHolder, WsTokenLiquidity, WsTokenBondingCurve, WsTokenMaxLiquidity, WsTokenTotalLiquidity, WsTradeActivity } from '@chainstream-io/sdk';
+import { ChainSymbol, Resolution, RangeFilterCondition, TokenCreator, Token as Token$1, TokenStats as TokenStats$1, DexPool, TokenMarketData as TokenMarketData$1, TokenCandle as TokenCandle$1, SwapRouteInput, SendTxInput, TokenPage, SwapRouteResponse, BlockchainLatestBlock, SendTxResponse, WalletNetWorthPage, WalletPnlSummary, PnlDetailsResult, PageResponseTradeDetail, WsNewToken, WsTokenMetadata, WsCandle, WsTokenStat, WsTokenSupply, WsTokenHolder, WsTokenLiquidity, WsTokenBondingCurve, WsTokenMaxLiquidity, WsTokenTotalLiquidity, WsTradeActivity } from '@chainstream-io/sdk';
 
 declare global {
     interface Window {
@@ -8,7 +9,7 @@ declare global {
         };
     }
 }
-declare const _default: "0.1.189";
+declare const _default: "0.3.0";
 
 /** Async or sync token provider for authentication. */
 interface ClientTokenProviderFn {
@@ -33,13 +34,14 @@ declare class Client implements API.IClient, API.ISubscribeClient {
     private readonly accessToken;
     private readonly options?;
     private readonly _client;
+    private readonly _phase3;
     constructor(accessToken: ClientTokenProvider, options?: ClientOptions | undefined);
     getToken(chain: Chain, address: string): Promise<Token>;
     getTokens(chain: Chain, addresses: Array<string>): Promise<Array<Token>>;
     getTokenCandles(chain: Chain, address: string, resolution: TokenResolution, options?: API.GetTokenCandlesOptions): Promise<Array<TokenCandle>>;
     getTokenSecurity(chain: Chain, address: string): Promise<TokenSecurity>;
     getTokenStats(chain: Chain, address: string): Promise<TokenStats>;
-    getTokenHolders(chain: Chain, address: string, options?: API.CursorListOptions): Promise<API.CursorList<TokenHolder>>;
+    getTokenHolders(chain: Chain, address: string, options?: API.GetTokenHoldersOptions): Promise<API.CursorList<TokenHolder>>;
     getTokenMarketData(chain: Chain, address: string): Promise<TokenMarketData>;
     getNewTokens(chain: Chain, options?: API.GetTokenListOptions): Promise<Array<Token>>;
     getFinalStretchTokens(chain: Chain, options?: API.GetTokenListOptions): Promise<Array<Token>>;
@@ -56,10 +58,7 @@ declare class Client implements API.IClient, API.ISubscribeClient {
         limit?: number;
     }): Promise<WalletPortfolios>;
     getWalletPnl(chain: Chain, address: string, resolution?: string): Promise<WalletPnl>;
-    getWalletPortfolioPnls(chain: Chain, address: string, options?: {
-        cursor?: string;
-        limit?: number;
-    }): Promise<WalletPortfolioPnls>;
+    getWalletPortfolioPnls(chain: Chain, address: string, options?: API.GetWalletPortfolioPnlsOptions): Promise<WalletPortfolioPnls>;
     getWalletPortfoliosByTokens(chain: Chain, address: string, tokenAddresses: Array<string>): Promise<Array<Portfolio>>;
     getWalletPortfolioPnlsByTokens(chain: Chain, address: string, tokenAddresses: Array<string>): Promise<Array<PortfolioPnl>>;
     getWalletTrades(chain: Chain, address: string, options?: API.GetTradesOptions): Promise<API.CursorList<Trade>>;
@@ -67,6 +66,8 @@ declare class Client implements API.IClient, API.ISubscribeClient {
     getWalletActivities(chain: Chain, address: string, options?: API.GetActivitiesOptions): Promise<API.CursorList<Activity>>;
     getTokenActivities(chain: Chain, address: string, options?: API.GetActivitiesOptions): Promise<API.CursorList<Activity>>;
     getPresignedUploadUrl(): Promise<string>;
+    getWalletLimitOrders(_chain: Chain, _address: string, _options?: API.GetWalletLimitOrdersOptions): Promise<API.CursorList<_liberfi_io_types.LimitOrder>>;
+    getTokensByCreator(_chain: Chain, _creator: string, _options?: API.GetTokensByCreatorOptions): Promise<API.CursorList<Token>>;
     subscribeToken(chain: Chain, address: string, callback: (data: Array<API.TokenSubscribed>) => void): API.ISubscription;
     subscribeTokenCandles(chain: Chain, address: string, resolution: TokenResolution, callback: (candles: Array<TokenCandle>) => void): API.ISubscription;
     subscribeWalletPnl(chain: Chain, address: string, callback: (pnls: Array<API.WalletPnlSubscribed>) => void): API.ISubscription;
@@ -98,6 +99,167 @@ declare class Client implements API.IClient, API.ISubscribeClient {
     private _subscribeRankingTokens;
 }
 
+/**
+ * Error thrown when a Client method is called against a server endpoint
+ * that has not yet shipped. This is distinct from a network / auth error:
+ * the SDK is structurally ready to call the endpoint but the backend
+ * side is not.
+ *
+ * Widgets can use `instanceof NotImplementedError` (or check `code`) to
+ * render a "coming soon" empty state instead of a generic error surface.
+ */
+declare class NotImplementedError extends Error {
+    /** Stable discriminant, useful across package boundaries where `instanceof` may be brittle. */
+    readonly code: "NotImplemented";
+    constructor(method: string, detail?: string);
+}
+/** Type guard using the stable code so it survives bundling across realms. */
+declare function isNotImplementedError(error: unknown): error is NotImplementedError;
+
+/**
+ * Phase 3 HTTP helpers.
+ *
+ * The bundled `@chainstream-io/sdk` version pins an older schema that does not
+ * recognize the Phase 3 parameters (`sortBy`, `positionState`, `resolution`) or
+ * response fields (`gasFee`, `traderTags`, `tags`, `lastActiveAt`, `avgCostUsd`,
+ * `isActive`, `walletTokenTags`, `isClosed`, `firstBuyAt`, `lastSellAt`).
+ *
+ * Rather than wait for the SDK to be regenerated, this module issues direct
+ * `fetch` calls against the same REST endpoints the SDK would have hit, and
+ * types the raw DTOs as described in the 2026-05-01 Phase 3 spec. Mapping from
+ * DTO → domain type stays in `utils.ts`.
+ *
+ * Once the SDK adopts Phase 3, this module can be deleted and Client can call
+ * the SDK methods again without touching any consumer code.
+ */
+
+interface CursorPageDTO<T> {
+    data: Array<T>;
+    hasNext: boolean;
+    hasPrev: boolean;
+    startCursor?: string | null;
+    endCursor?: string | null;
+}
+interface Phase3TokenHolderDTO {
+    walletAddress: string;
+    amount: string;
+    amountInUsd: string;
+    percentage: string;
+    tags?: Array<string>;
+    lastActiveAt?: number | null;
+    startHoldingAt?: number | null;
+}
+interface Phase3ActivityDTO {
+    transactionSignature: string;
+    chain: string;
+    blockHeight?: number;
+    blockTimestamp: number;
+    type: string;
+    tokenAddress: string;
+    tokenName?: string;
+    tokenSymbol: string;
+    tokenImageUrl?: string | null;
+    tokenAmount: string;
+    tokenAmountInUsd: string;
+    tokenPriceInUsd?: string;
+    tokenAmountInNative?: string;
+    tokenPriceInNative?: string;
+    sideTokenAddress: string;
+    sideTokenName?: string;
+    sideTokenSymbol: string;
+    sideTokenImageUrl?: string | null;
+    sideTokenAmount: string;
+    sideTokenAmountInUsd: string;
+    sideTokenPriceInUsd?: string;
+    accountOwnerAddress: string;
+    gasFee?: number | null;
+    traderTags?: Array<string>;
+    poolAddress?: string | null;
+    dexProgramAddress?: string | null;
+    dexProtocolFamily?: string | null;
+    dexImage?: string | null;
+    status?: string;
+}
+interface Phase3NetWorthTokenDTO {
+    chain: string;
+    tokenAddress: string;
+    name: string;
+    symbol: string;
+    decimals: number;
+    logoUri?: string | null;
+    amount: string;
+    priceInUsd: string;
+    priceInNative: string;
+    valueInUsd: string;
+    valueInNative: string;
+    isActive?: boolean;
+    avgCostUsd?: string | null;
+    lastActiveAt?: number | null;
+    walletTokenTags?: Array<string>;
+}
+interface Phase3NetWorthByTokensDTO {
+    walletAddress: string;
+    totalValueInUsd: string;
+    totalValueInNative: string;
+    currentTimestamp?: number;
+    data: Array<Phase3NetWorthTokenDTO>;
+}
+interface Phase3PnlSummaryDTO {
+    tokens?: number | string;
+    totalTrades?: number | string;
+    buys?: number | string;
+    sells?: number | string;
+    wins?: number | string;
+    losses?: number | string;
+    winRate?: string | null;
+    realizedProfitInUsd?: string | null;
+    unrealizedProfitInUsd?: string | null;
+    totalProfitInUsd?: string | null;
+    totalProfitRatio?: string | null;
+    currentValue?: string | null;
+    buyAmountInUsd?: string | null;
+    sellAmountInUsd?: string | null;
+    totalCostInUsd?: string;
+    avgProfitPerTradeInUsd?: string | null;
+}
+interface Phase3PnlItemDTO {
+    tokenAddress: string;
+    symbol?: string;
+    name?: string;
+    decimals?: number;
+    logoUri?: string | null;
+    walletAddress?: string;
+    chain?: string;
+    balance: string;
+    priceInUsd: string;
+    currentValue: string;
+    realizedProfitInUsd?: string;
+    realizedProfitRatio?: string;
+    unrealizedProfitInUsd?: string;
+    unrealizedProfitRatio?: string;
+    totalProfitInUsd?: string;
+    totalProfitRatio?: string;
+    buys?: number | string;
+    sells?: number | string;
+    totalTrades?: number | string;
+    wins?: number | string;
+    losses?: number | string;
+    buyAmount?: string;
+    sellAmount?: string;
+    buyAmountInUsd?: string;
+    sellAmountInUsd?: string;
+    avgBuyPriceInUsd?: string;
+    avgSellPriceInUsd?: string;
+    avgProfitPerTradeInUsd?: string;
+    totalCostInUsd?: string;
+    isClosed?: boolean;
+    firstBuyAt?: number | null;
+    lastSellAt?: number | null;
+}
+interface Phase3PnlDetailsDTO extends CursorPageDTO<Phase3PnlItemDTO> {
+    summary: Phase3PnlSummaryDTO;
+}
+
 declare function toChainDTO(chain: Chain): ChainSymbol;
 declare function toResolutionDTO(resolution: TokenResolution): Resolution;
 declare function toSortDirectionDTO(direction: "asc" | "desc"): string;
@@ -126,18 +288,18 @@ declare const KYBERSWAP_NATIVE_SENTINEL = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeee
 declare function toMintForRoute(dex: "jupiter" | "kyberswap", address: string): string;
 declare function toSwapRouteInput(params: API.SwapParams): SwapRouteInput;
 declare function toSendTxInput(params: API.SendTxParams): SendTxInput;
-declare function fromTokenHolderPage(input: PageResponseTokenHolder): API.CursorList<TokenHolder>;
+declare function fromTokenHolderPage(input: CursorPageDTO<Phase3TokenHolderDTO>): API.CursorList<TokenHolder>;
 declare function fromTokenPage(input: TokenPage): API.SearchTokenCursorList;
 declare function fromSwapRoute(input: SwapRouteResponse): API.SwapRoute;
 declare function fromLatestBlock(input: BlockchainLatestBlock): API.BlockchainLatestBlock;
 declare function fromSendTxResult(input: SendTxResponse): API.SendTxResult;
 declare function fromWalletPortfolios(chain: Chain, input: WalletNetWorthPage): WalletPortfolios;
 declare function fromWalletPnlSummary(chain: Chain, address: string, input: WalletPnlSummary): WalletPnl;
-declare function fromPnlDetailsPage(chain: Chain, address: string, input: PnlDetailsResult): WalletPortfolioPnls;
-declare function fromWalletNetWorthByTokens(chain: Chain, input: NetWorthByTokensResult): Portfolio[];
+declare function fromPnlDetailsPage(chain: Chain, address: string, input: Phase3PnlDetailsDTO): WalletPortfolioPnls;
+declare function fromWalletNetWorthByTokens(chain: Chain, input: Phase3NetWorthByTokensDTO): Portfolio[];
 declare function fromPnlDetailItems(chain: Chain, input: PnlDetailsResult): PortfolioPnl[];
 declare function fromTradePage(input: PageResponseTradeDetail): API.CursorList<Trade>;
-declare function fromActivityPage(input: PageResponseTradeDetail): API.CursorList<Activity>;
+declare function fromActivityPage(input: CursorPageDTO<Phase3ActivityDTO>): API.CursorList<Activity>;
 declare function fromTokenSubscribed(chain: Chain, input: WsNewToken): API.TokenSubscribed;
 declare function fromTokenMetadataSubscribed(chain: Chain, input: WsTokenMetadata): API.TokenSubscribed;
 declare function fromWsCandle(input: WsCandle): TokenCandle;
@@ -154,4 +316,4 @@ declare function fromWsTokenMarketDataFromHolder(input: WsTokenHolder): Partial<
 declare function fromWsTradeActivity(chain: Chain, input: WsTradeActivity): Trade;
 declare function fromWsActivity(chain: Chain, input: WsTradeActivity): Activity;
 
-export { Client, type ClientOptions, type ClientTokenProvider, type ClientTokenProviderFn, KYBERSWAP_NATIVE_SENTINEL, fromActivityPage, fromChainDTO, fromLatestBlock, fromPnlDetailItems, fromPnlDetailsPage, fromSendTxResult, fromSwapRoute, fromTokenCandle, fromTokenCreatorDTO, fromTokenDTO, fromTokenHolderPage, fromTokenLiquidityDTO, fromTokenMarketDataDTO, fromTokenMetadataSubscribed, fromTokenPage, fromTokenSecurity, fromTokenStatsDTO, fromTokenSubscribed, fromTradePage, fromWalletNetWorthByTokens, fromWalletPnlSummary, fromWalletPortfolios, fromWsActivity, fromWsCandle, fromWsTokenBondingCurveToSubscribed, fromWsTokenDataSubscribed, fromWsTokenHolderToSubscribed, fromWsTokenLiquidityToSubscribed, fromWsTokenMarketDataFromHolder, fromWsTokenMarketDataFromStats, fromWsTokenMaxLiquidityToSubscribed, fromWsTokenStats, fromWsTokenSupplyToSubscribed, fromWsTokenTotalLiquidityToSubscribed, fromWsTradeActivity, toChainDTO, toFieldDTO, toMintForRoute, toRangeFiltersDTO, toResolutionDTO, toSearchFieldDTO, toSendTxInput, toSortDirectionDTO, toSwapRouteInput, _default as version };
+export { Client, type ClientOptions, type ClientTokenProvider, type ClientTokenProviderFn, KYBERSWAP_NATIVE_SENTINEL, NotImplementedError, fromActivityPage, fromChainDTO, fromLatestBlock, fromPnlDetailItems, fromPnlDetailsPage, fromSendTxResult, fromSwapRoute, fromTokenCandle, fromTokenCreatorDTO, fromTokenDTO, fromTokenHolderPage, fromTokenLiquidityDTO, fromTokenMarketDataDTO, fromTokenMetadataSubscribed, fromTokenPage, fromTokenSecurity, fromTokenStatsDTO, fromTokenSubscribed, fromTradePage, fromWalletNetWorthByTokens, fromWalletPnlSummary, fromWalletPortfolios, fromWsActivity, fromWsCandle, fromWsTokenBondingCurveToSubscribed, fromWsTokenDataSubscribed, fromWsTokenHolderToSubscribed, fromWsTokenLiquidityToSubscribed, fromWsTokenMarketDataFromHolder, fromWsTokenMarketDataFromStats, fromWsTokenMaxLiquidityToSubscribed, fromWsTokenStats, fromWsTokenSupplyToSubscribed, fromWsTokenTotalLiquidityToSubscribed, fromWsTradeActivity, isNotImplementedError, toChainDTO, toFieldDTO, toMintForRoute, toRangeFiltersDTO, toResolutionDTO, toSearchFieldDTO, toSendTxInput, toSortDirectionDTO, toSwapRouteInput, _default as version };