@liberfi.io/types 0.3.13 → 0.4.1

package/dist/api/index.d.ts

@@ -0,0 +1,1829 @@
+declare enum Chain {
+    ETHEREUM = "1",
+    UBIQ = "8",
+    OPTIMISM = "10",
+    FLARE = "14",
+    SONGBIRD = "19",
+    ELASTOS = "20",
+    KARDIA = "24",
+    CRONOS = "25",
+    RSK = "30",
+    TELOS = "40",
+    LUKSO = "42",
+    CRAB = "44",
+    DARWINIA = "46",
+    XDC = "50",
+    CSC = "52",
+    ZYX = "55",
+    BINANCE = "56",
+    BINANCE_TESTNET = "97",
+    SYSCOIN = "57",
+    GOCHAIN = "60",
+    ETHEREUMCLASSIC = "61",
+    OKEXCHAIN = "66",
+    HOO = "70",
+    METER = "82",
+    NOVA_NETWORK = "87",
+    TOMOCHAIN = "88",
+    BITKUB = "96",
+    XDAI = "100",
+    VELAS = "106",
+    THUNDERCORE = "108",
+    ENULS = "119",
+    FUSE = "122",
+    HECO = "128",
+    UNICHAIN = "130",
+    POLYGON = "137",
+    SONIC = "146",
+    SHIMMER_EVM = "148",
+    RBN = "151",
+    OMNI = "166",
+    MANTA = "169",
+    HSK = "177",
+    WATER = "181",
+    XLAYER = "196",
+    XDAIARB = "200",
+    OP_BNB = "204",
+    VINUCHAIN = "207",
+    ENERGYWEB = "246",
+    OASYS = "248",
+    FANTOM = "250",
+    FRAXTAL = "252",
+    HPB = "269",
+    BOBA = "288",
+    OMAX = "311",
+    FILECOIN = "314",
+    KUCOIN = "321",
+    ZKSYNC_ERA = "324",
+    SHIDEN = "336",
+    THETA = "361",
+    PULSE = "369",
+    CRONOS_ZKEVM = "388",
+    SX = "416",
+    AREON = "463",
+    WC = "480",
+    CANDLE = "534",
+    ROLLUX = "570",
+    ASTAR = "592",
+    REDSTONE = "690",
+    MATCHAIN = "698",
+    CALLISTO = "820",
+    TARA = "841",
+    WANCHAIN = "888",
+    LYRA_CHAIN = "957",
+    BIFROST = "996",
+    CONFLUX = "1030",
+    METIS = "1088",
+    DYMENSION = "1100",
+    POLYGON_ZKEVM = "1101",
+    CORE = "1116",
+    LISK = "1135",
+    ULTRON = "1231",
+    STEP = "1234",
+    MOONBEAM = "1284",
+    MOONRIVER = "1285",
+    SEI = "1329",
+    LIVING_ASSETS_MAINNET = "1440",
+    STY = "1514",
+    TENET = "1559",
+    GRAVITY = "1625",
+    REYA_NETWORK = "1729",
+    SONEIUM = "1868",
+    SWELLCHAIN = "1923",
+    ONUS = "1975",
+    HUBBLENET = "1992",
+    SANKO = "1996",
+    DOGECHAIN = "2000",
+    MILKOMEDA = "2001",
+    MILKOMEDA_A1 = "2002",
+    KAVA = "2222",
+    SOMA = "2332",
+    KARAK = "2410",
+    ABSTRACT = "2741",
+    ABSTRACT_TESTNET = "11124",
+    MORPH = "2818",
+    CROSSFI = "4158",
+    BEAM = "4337",
+    IOTEX = "4689",
+    MANTLE = "5000",
+    XLC = "5050",
+    NAHMII = "5551",
+    BOUNCEBIT = "6001",
+    TOMBCHAIN = "6969",
+    ZETACHAIN = "7000",
+    PLANQ = "7070",
+    BITROCK = "7171",
+    XSAT = "7200",
+    CYETH = "7560",
+    CANTO = "7700",
+    KLAYTN = "8217",
+    THAT = "8428",
+    BASE = "8453",
+    HELA = "8668",
+    IOTAEVM = "8822",
+    JBC = "8899",
+    EVMOS = "9001",
+    CARBON = "9790",
+    SMARTBCH = "10000",
+    ARTELA = "11820",
+    IMMUTABLE_ZKEVM = "13371",
+    LOOP = "15551",
+    GENESYS = "16507",
+    EOS_EVM = "17777",
+    MAP_PROTOCOL = "22776",
+    SAPPHIRE = "23294",
+    BITGERT = "32520",
+    FUSION = "32659",
+    ZILLIQA = "32769",
+    APECHAIN = "33139",
+    EDU_CHAIN = "41923",
+    ARBITRUM = "42161",
+    ARBITRUM_TESTNET_GOERLI = "421613",
+    ARBITRUM_TESTNET_SEPOLIA = "421614",
+    ARBITRUM_NOVA = "42170",
+    CELO = "42220",
+    OASIS = "42262",
+    ASSETCHAIN = "42420",
+    ETHERLINK = "42793",
+    AVALANCHE = "43114",
+    REI = "47805",
+    ZIRCUIT = "48900",
+    SOPHON = "50104",
+    ETN = "52014",
+    SUPERPOSITION = "55244",
+    REICHAIN = "55555",
+    BOBA_BNB = "56288",
+    INK = "57073",
+    LINEA = "59144",
+    BOB = "60808",
+    GODWOKEN = "71402",
+    BERACHAIN = "80094",
+    BLAST = "81457",
+    CHILIZ = "88888",
+    STRATIS = "105105",
+    REAL = "111188",
+    ODYSSEY = "153153",
+    TAIKO = "167000",
+    BITLAYER = "200901",
+    HYDRATION = "222222",
+    PAREX = "322202",
+    POLIS = "333999",
+    KEKCHAIN = "420420",
+    SCROLL = "534352",
+    ZERO_NETWORK = "543210",
+    ZKLINK_NOVA = "810180",
+    VISION = "888888",
+    SAAKURU = "7225878",
+    ZORA = "7777777",
+    CORN = "21000000",
+    NEON = "245022934",
+    LUMIA = "994873017",
+    AURORA = "1313161554",
+    HARMONY = "1666600000",
+    PALM = "11297108109",
+    ZENIQ = "383414847825",
+    CURIO = "836542336838601",
+    MODE = "34443",
+    SOLANA = "900900900",
+    SOLANA_TESTNET = "901901901",
+    SOLANA_DEVNET = "902902902"
+}
+declare enum ChainNamespace {
+    EVM = "EVM",
+    SOLANA = "SOL"
+}
+
+/**
+ * Classification tag applied to a wallet across token-holding, activity, and
+ * portfolio contexts. Sparse — only a small percentage of wallets match one
+ * of the known patterns. The `(string & {})` escape hatch allows new server-
+ * defined tags to flow through without a library update.
+ */
+type WalletTag = "kol" | "smart" | "sniper" | "dev" | "bundle" | "bluechip" | (string & {});
+
+interface ActivityToken {
+    /** token address */
+    address: string;
+    /** token symbol */
+    symbol: string;
+    /** token name */
+    name?: string;
+    /** token avatar image url */
+    image?: string;
+    /** token amount */
+    amount: string;
+    /** token amount in USD */
+    amountInUsd?: string;
+    /** token price in USD at the time of the trade */
+    priceInUsd?: string;
+}
+interface ActivityDex {
+    /** dex name */
+    name?: string;
+    /** dex avatar image url */
+    image?: string;
+    /** dex protocol family */
+    protocolFamily?: string;
+    /** dex program address */
+    programAddress?: string;
+}
+type ActivityType = "buy" | "sell" | "liquidity_initialize" | "liquidity_add" | "liquidity_remove" | "red_packet_create" | "red_packet_claim" | "red_packet_complete" | "red_packet_refund";
+/**
+ * An on-chain activity record (trade, liquidity, red packet, etc.).
+ */
+interface Activity {
+    /** chain id */
+    chain: Chain;
+    /** wallet address */
+    walletAddress: string;
+    /** transaction hash */
+    txHash: string;
+    /** activity type */
+    type: ActivityType;
+    /** source token */
+    from: ActivityToken;
+    /** destination token */
+    to: ActivityToken;
+    /** dex where the activity happened */
+    dex?: ActivityDex;
+    /** pool address */
+    poolAddress?: string;
+    /** activity status */
+    status: "pending" | "success" | "failed";
+    /** activity time */
+    time: Date;
+    /**
+     * Transaction gas fee as a decimal string in the native token's smallest unit
+     * (e.g. lamports on Solana, wei on EVM chains). Phase 3; ~100% fill rate on SOL.
+     */
+    gasFee?: string;
+    /**
+     * Classification tags applied to the trader for this activity (Phase 3).
+     * Sparse — only present when the trader matches one of the known patterns.
+     */
+    traderTags?: Array<WalletTag>;
+}
+/**
+ * A buy/sell trade record. Narrowed subset of {@link Activity}.
+ */
+interface Trade extends Activity {
+    type: "buy" | "sell";
+}
+
+/**
+ * Shared cursor-based pagination fields.
+ */
+interface CursorPagination {
+    /** pagination start cursor */
+    startCursor?: string;
+    /** pagination end cursor */
+    endCursor?: string;
+    /** whether there is a previous page */
+    hasPrev?: boolean;
+    /** whether there is a next page */
+    hasNext?: boolean;
+}
+
+/**
+ * Cursor list result data.
+ */
+interface CursorList<T> extends CursorPagination {
+    data: Array<T>;
+}
+/**
+ * Cursor list query options.
+ */
+interface CursorListOptions {
+    /** query cursor */
+    cursor?: string;
+    /** return limit */
+    limit?: number;
+    /** query direction */
+    direction?: "next" | "prev";
+}
+
+/**
+ * Options for getting trades.
+ */
+interface GetTradesOptions extends CursorListOptions {
+    /** filter trades before this timestamp */
+    before?: Date;
+    /** filter trades after this timestamp */
+    after?: Date;
+    /** filter trades before this block height */
+    beforeBlockHeight?: number;
+    /** filter trades after this block height */
+    afterBlockHeight?: number;
+    /** filter trades by type */
+    type?: "buy" | "sell";
+    /** filter trades by pool address */
+    poolAddress?: string;
+}
+/**
+ * Sort field for activity list (Phase 3).
+ * - `timestamp` — order by activity time (default, descending)
+ * - `totalUsd` — order by USD amount (useful for finding whale trades)
+ */
+type ActivitiesSortBy = "timestamp" | "totalUsd";
+/**
+ * Options for getting activities.
+ */
+interface GetActivitiesOptions extends CursorListOptions {
+    /** filter activities before this timestamp */
+    before?: Date;
+    /** filter activities after this timestamp */
+    after?: Date;
+    /** filter activities before this block height */
+    beforeBlockHeight?: number;
+    /** filter activities after this block height */
+    afterBlockHeight?: number;
+    /** filter activities by type */
+    type?: ActivityType;
+    /** filter activities by pool address */
+    poolAddress?: string;
+    /**
+     * Sort field (Phase 3). Defaults to `timestamp` on the server. When changing
+     * `sortBy`, the caller must discard the previous cursor and restart from page 1.
+     */
+    sortBy?: ActivitiesSortBy;
+}
+
+/**
+ * Side of a limit order.
+ */
+type LimitOrderSide = "buy" | "sell";
+/**
+ * Lifecycle state of a limit order (Phase 3 extension).
+ * - `active`    — order is open, still watching the target price
+ * - `filled`    — order was executed
+ * - `cancelled` — order was cancelled by the user
+ * - `expired`   — order reached its deadline without filling
+ */
+type LimitOrderState = "active" | "filled" | "cancelled" | "expired";
+/**
+ * A wallet-scoped limit order (not yet backed by a server endpoint;
+ * shape captures the Axiom-style `Orders` tab columns so the widget
+ * layer can be built against stable types even while the backend is
+ * still being designed).
+ */
+interface LimitOrder {
+    /** stable order id */
+    id: string;
+    /** chain id */
+    chain: Chain;
+    /** owner wallet address */
+    wallet: string;
+    /** target token address */
+    tokenAddress: string;
+    /** target token name (mirrored for convenience) */
+    tokenName?: string;
+    /** target token symbol */
+    tokenSymbol?: string;
+    /** target token image url */
+    tokenImage?: string;
+    /** buy or sell */
+    side: LimitOrderSide;
+    /** order amount in token base units (string to avoid precision loss) */
+    amount: string;
+    /** optional USD amount at order creation time */
+    amountInUsd?: string;
+    /** current market cap in USD at query time (display-only) */
+    currentMarketCapInUsd?: string;
+    /** target market cap in USD at which the order triggers */
+    targetMarketCapInUsd?: string;
+    /** optional trigger price in USD (alternative to target market cap) */
+    targetPriceInUsd?: string;
+    /** optional slippage tolerance, range 0-100 */
+    slippage?: number;
+    /** order state */
+    state: LimitOrderState;
+    /** order creation time */
+    createdAt?: Date;
+    /** order expiry time (if any) */
+    expiresAt?: Date;
+    /** execution time when state is `filled` */
+    filledAt?: Date;
+}
+
+declare enum SolanaTokenProtocol {
+    BAGS = "bags",
+    BELIEVE = "believe",
+    BONK = "bonk",
+    BOOP = "boop",
+    HEAVEN = "heaven",
+    JUPSTUDIO = "jupstudio",
+    LAUNCHLAB = "launchlab",
+    METEORA = "meteora",
+    MOONIT = "moonit",
+    MOONSHOT = "moonshot",
+    ORCA = "orca",
+    PUMP = "pump",
+    RAYDIUM = "raydium",
+    SUGAR = "sugar",
+    VIRTUAL_CURVE = "virtual-curve",
+    PUMP_AMM = "pump-amm"
+}
+type TokenProtocol = SolanaTokenProtocol | (string & {});
+declare const SOLANA_TOKEN_PROTOCOLS: SolanaTokenProtocol[];
+interface Token {
+    /**
+     * chain id.
+     */
+    chain: Chain;
+    /**
+     * token name, e.g. "Ethereum", "Solana", etc.
+     */
+    name: string;
+    /**
+     * token symbol, e.g. "ETH", "SOL", etc.
+     */
+    symbol: string;
+    /**
+     * token address.
+     */
+    address: string;
+    /**
+     * token decimals.
+     */
+    decimals: number;
+    /**
+     * token avatar image url.
+     */
+    image?: string;
+    /**
+     * token description.
+     */
+    description?: string;
+    /**
+     * token creators.
+     */
+    creators?: Array<TokenCreator>;
+    /**
+     * token launch info.
+     */
+    launchedFrom?: TokenLaunchedFrom;
+    /**
+     * token migrate progress, range is 0-100.
+     */
+    migrateProgress?: string;
+    /**
+     * token migrate info.
+     */
+    migratedTo?: TokenMigratedTo;
+    /**
+     * token social medias.
+     */
+    socialMedias?: TokenSocialMedias;
+    /**
+     * token stats.
+     */
+    stats?: TokenStats;
+    /**
+     * token market data.
+     */
+    marketData?: TokenMarketData;
+    /**
+     * token liquidity pools
+     */
+    liquidities?: Array<TokenLiquidity>;
+    /**
+     * token security.
+     */
+    security?: TokenSecurity;
+    /**
+     * token tags.
+     */
+    tags?: Array<string>;
+    /**
+     * token create time.
+     */
+    createdAt?: Date;
+}
+interface TokenCreator {
+    /**
+     * token creator's wallet address.
+     */
+    address?: string;
+    /**
+     * token creator's share percentage, range is 0-100.
+     */
+    share?: number;
+    /**
+     * whether the token creator is verified.
+     */
+    isVerified?: boolean;
+}
+interface TokenLaunchedFrom {
+    /**
+     * token launch program address.
+     */
+    programAddress?: string;
+    /**
+     * token launch protocol family.
+     */
+    protocolFamily?: string;
+}
+interface TokenMigratedTo {
+    /**
+     * token migrate program address.
+     */
+    programAddress?: string;
+    /**
+     * token migrate protocol family.
+     */
+    protocolFamily?: string;
+    /**
+     * token migrate pool address.
+     */
+    poolAddress?: string;
+    /**
+     * token migrate time.
+     */
+    migratedAt?: Date;
+}
+interface TokenSocialMedias {
+    /**
+     * token twitter url.
+     */
+    twitter?: string;
+    /**
+     * token telegram url.
+     */
+    telegram?: string;
+    /**
+     * token website url.
+     */
+    website?: string;
+    /**
+     * token tiktok url.
+     */
+    tiktok?: string;
+    /**
+     * token discord url.
+     */
+    discord?: string;
+    /**
+     * token facebook url.
+     */
+    facebook?: string;
+    /**
+     * token github url.
+     */
+    github?: string;
+    /**
+     * token instagram url.
+     */
+    instagram?: string;
+    /**
+     * token linkedin url.
+     */
+    linkedin?: string;
+    /**
+     * token medium url.
+     */
+    medium?: string;
+    /**
+     * token reddit url.
+     */
+    reddit?: string;
+    /**
+     * token youtube url.
+     */
+    youtube?: string;
+    /**
+     * token bitbucket url.
+     */
+    bitbucket?: string;
+}
+interface TokenStats {
+    /**
+     * token stats by 1m timeframe.
+     */
+    "1m"?: TokenStatsByResolution;
+    /**
+     * token stats by 5m timeframe.
+     */
+    "5m"?: TokenStatsByResolution;
+    /**
+     * token stats by 15m timeframe.
+     */
+    "15m"?: TokenStatsByResolution;
+    /**
+     * token stats by 30m timeframe.
+     */
+    "30m"?: TokenStatsByResolution;
+    /**
+     * token stats by 1h timeframe.
+     */
+    "1h"?: TokenStatsByResolution;
+    /**
+     * token stats by 4h timeframe.
+     */
+    "4h"?: TokenStatsByResolution;
+    /**
+     * token stats by 24h timeframe.
+     */
+    "24h"?: TokenStatsByResolution;
+}
+interface TokenStatsByResolution {
+    /**
+     * buy txs count
+     */
+    buys?: number;
+    /**
+     * sell txs count
+     */
+    sells?: number;
+    /**
+     * txs count
+     */
+    trades?: number;
+    /**
+     * buy addresses count
+     */
+    buyers?: number;
+    /**
+     * sell addresses count
+     */
+    sellers?: number;
+    /**
+     * trade addresses count
+     */
+    traders?: number;
+    /**
+     * buy volumes in quote token
+     */
+    buyVolumes?: string;
+    /**
+     * sell volumes in quote token
+     */
+    sellVolumes?: string;
+    /**
+     * total volumes in quote token
+     */
+    volumes?: string;
+    /**
+     * buy volumes in usd
+     */
+    buyVolumesInUsd?: string;
+    /**
+     * sell volumes in usd
+     */
+    sellVolumesInUsd?: string;
+    /**
+     * total volumes in usd
+     */
+    volumesInUsd?: string;
+    /**
+     * open price in usd
+     */
+    openPriceInUsd?: string;
+    /**
+     * close price in usd
+     */
+    closePriceInUsd?: string;
+    /**
+     * high price in usd
+     */
+    highPriceInUsd?: string;
+    /**
+     * low price in usd
+     */
+    lowPriceInUsd?: string;
+    /**
+     * price in usd
+     */
+    priceInUsd?: string;
+    /**
+     * price change %
+     */
+    priceChange?: string;
+}
+interface TokenMarketData {
+    /**
+     * total supply
+     */
+    totalSupply?: string;
+    /**
+     * market cap in quote token
+     */
+    marketCap?: string;
+    /**
+     * market cap in usd
+     */
+    marketCapInUsd?: string;
+    /**
+     * price in quote token
+     */
+    price?: string;
+    /**
+     * price in usd
+     */
+    priceInUsd?: string;
+    /**
+     * tvl in quote token
+     */
+    tvl?: string;
+    /**
+     * tvl in usd
+     */
+    tvlInUsd?: string;
+    /**
+     * holders count
+     */
+    holders?: number;
+    /**
+     * top 10 total holdings
+     */
+    top10Holdings?: string;
+    /**
+     * top 10 holdings ratio
+     */
+    top10HoldingsRatio?: string;
+    /**
+     * top 50 total holdings
+     */
+    top50Holdings?: string;
+    /**
+     * top 50 holdings ratio
+     */
+    top50HoldingsRatio?: string;
+    /**
+     * top 100 total holdings
+     */
+    top100Holdings?: string;
+    /**
+     * top 100 holdings ratio
+     */
+    top100HoldingsRatio?: string;
+    /**
+     * Bluechip holders count
+     */
+    bluechipHolders?: number;
+    /**
+     * Bluechip total holdings
+     */
+    bluechipHoldings?: string;
+    /**
+     * Bluechip holdings ratio
+     */
+    bluechipHoldingsRatio?: string;
+    /**
+     * KOL holders count
+     */
+    kolHolders?: number;
+    /**
+     * KOL total holdings
+     */
+    kolHoldings?: string;
+    /**
+     * KOL holdings ratio
+     */
+    kolHoldingsRatio?: string;
+    /**
+     * Sniper holders count
+     */
+    sniperHolders?: number;
+    /**
+     * Sniper total holdings
+     */
+    sniperHoldings?: string;
+    /**
+     * Sniper holdings ratio
+     */
+    sniperHoldingsRatio?: string;
+    /**
+     * Pro holders count
+     */
+    proHolders?: number;
+    /**
+     * Pro total holdings
+     */
+    proHoldings?: string;
+    /**
+     * Pro holdings ratio
+     */
+    proHoldingsRatio?: string;
+    /**
+     * Insider holders count
+     */
+    insiderHolders?: number;
+    /**
+     * Insider total holdings
+     */
+    insiderHoldings?: string;
+    /**
+     * Insider holdings ratio
+     */
+    insiderHoldingsRatio?: string;
+    /**
+     * Sandwich holders count
+     */
+    sandwichHolders?: number;
+    /**
+     * Sandwich total holdings
+     */
+    sandwichHoldings?: string;
+    /**
+     * Sandwich holdings ratio
+     */
+    sandwichHoldingsRatio?: string;
+    /**
+     * Fresh holders count
+     */
+    freshHolders?: number;
+    /**
+     * Fresh total holdings
+     */
+    freshHoldings?: string;
+    /**
+     * Fresh holdings ratio
+     */
+    freshHoldingsRatio?: string;
+    /**
+     * Bundle holders count
+     */
+    bundleHolders?: number;
+    /**
+     * Bundle total holdings
+     */
+    bundleHoldings?: string;
+    /**
+     * Bundle holdings ratio
+     */
+    bundleHoldingsRatio?: string;
+    /**
+     * Dev holders count
+     */
+    devHolders?: number;
+    /**
+     * Dev total holdings
+     */
+    devHoldings?: string;
+    /**
+     * Dev holdings ratio
+     */
+    devHoldingsRatio?: string;
+}
+interface TokenLiquidity {
+    /**
+     * pool avatar image
+     */
+    image?: string;
+    /**
+     * pair token address.
+     */
+    pairAddress?: string;
+    /**
+     * pool address.
+     */
+    poolAddress?: string;
+    /**
+     * program address.
+     */
+    programAddress?: string;
+    /**
+     * protocol name.
+     */
+    protocolName?: string;
+    /**
+     * protocol family.
+     */
+    protocolFamily?: string;
+    /**
+     * tvl in quote token.
+     */
+    tvl?: string;
+    /**
+     * tvl in usd.
+     */
+    tvlInUsd?: string;
+}
+/**
+ * Token security flags. Backend currently exposes the five Solana SPL flags
+ * below; additional checks may be added in the future as the security service
+ * gains coverage of more chains and risk vectors.
+ */
+interface TokenSecurity {
+    /**
+     * whether the token has transfer fee.
+     */
+    hasTransferFee?: boolean;
+    /**
+     * whether the token transfer fee is upgradable.
+     */
+    isTransferFeeUpgradable?: boolean;
+    /**
+     * whether the token is transferable.
+     */
+    isTransferable?: boolean;
+    /**
+     * whether the token is freezable.
+     */
+    isFreezable?: boolean;
+    /**
+     * whether the token is closable.
+     */
+    isClosable?: boolean;
+}
+type TokenResolution = "1s" | "15s" | "30s" | "1m" | "5m" | "15m" | "30m" | "1h" | "4h" | "12h" | "24h";
+interface TokenCandle {
+    /**
+     * open price in usd
+     */
+    open: string;
+    /**
+     * close price in usd
+     */
+    close: string;
+    /**
+     * high price in usd
+     */
+    high: string;
+    /**
+     * low price in usd
+     */
+    low: string;
+    /**
+     * volume in usd
+     */
+    volume: string;
+    /**
+     * resolution
+     */
+    resolution: TokenResolution;
+    /**
+     * timestamp
+     */
+    timestamp: Date;
+}
+interface TokenHolder {
+    /**
+     * holder wallet address
+     */
+    address: string;
+    /**
+     * holdings amount in token
+     */
+    amount: string;
+    /**
+     * holdings amount in usd
+     */
+    amountInUsd: string;
+    /**
+     * holdings ratio, range is 0-100
+     */
+    ratio: string;
+    /**
+     * Holder classification tags (Phase 3). Sparse — only present when the
+     * wallet matches one of the known patterns (kol/smart/sniper/dev/...).
+     */
+    tags?: Array<WalletTag>;
+    /**
+     * The last time this wallet was active on-chain (Phase 3).
+     * Sparse (~80% fill rate).
+     */
+    lastActiveAt?: Date;
+    /**
+     * The first time this wallet started holding this token (Phase 3).
+     * Sparse (~60% fill rate).
+     */
+    startHoldingAt?: Date;
+}
+
+/**
+ * Portfolio PNL
+ */
+interface PortfolioPnl {
+    /** chain id */
+    chain: Chain;
+    /** token address */
+    address: string;
+    /** token name */
+    name: string;
+    /** token symbol */
+    symbol: string;
+    /** token image url */
+    image?: string;
+    /** holding token amount */
+    amount: string;
+    /** holding token amount in usd */
+    amountInUsd: string;
+    /** token current price in usd */
+    priceInUsd: string;
+    /** token decimals */
+    decimals: number;
+    /** open position time */
+    openTime?: Date;
+    /** close position time */
+    closeTime?: Date;
+    /** total trades count */
+    totalTrades?: number;
+    /** total buy txs count */
+    buys?: number;
+    /** total buy volumes */
+    buyVolumes?: string;
+    /** total buy volumes in usd */
+    buyVolumesInUsd?: string;
+    /** average buy price in usd */
+    buyAvgPriceInUsd?: string;
+    /** total sell txs count */
+    sells?: number;
+    /** total sell volumes */
+    sellVolumes?: string;
+    /** total sell volumes in usd */
+    sellVolumesInUsd?: string;
+    /** average sell price in usd */
+    sellAvgPriceInUsd?: string;
+    /** realized profit in usd */
+    realizedProfitInUsd?: string;
+    /** realized profit ratio */
+    realizedProfitRatio?: string;
+    /** unrealized profit in usd */
+    unrealizedProfitInUsd?: string;
+    /** unrealized profit ratio */
+    unrealizedProfitRatio?: string;
+    /** total profit in usd (including both realized and unrealized profit) */
+    totalProfitInUsd?: string;
+    /** total profit ratio (including both realized and unrealized profit) */
+    totalProfitRatio?: string;
+    /** average profit per trade in usd */
+    avgProfitPerTradeInUsd?: string;
+    /**
+     * Whether the position is closed (balance == 0). Phase 3; 100% fill rate.
+     * Corresponds to `positionState=closed` filter on the pnl-details endpoint.
+     */
+    isClosed?: boolean;
+    /** First buy time (Phase 3). Sparse (~60% fill rate). */
+    firstBuyAt?: Date;
+    /** Last sell time (Phase 3). Sparse (~30% fill rate). */
+    lastSellAt?: Date;
+}
+interface Portfolio {
+    /** chain id */
+    chain: Chain;
+    /** token address */
+    address: string;
+    /** token name */
+    name: string;
+    /** token symbol */
+    symbol: string;
+    /** token image url */
+    image?: string;
+    /** token current price in usd */
+    priceInUsd: string;
+    /** token current price in native token */
+    priceInNative: string;
+    /** holding token amount */
+    amount: string;
+    /** holding token amount in usd */
+    amountInUsd: string;
+    /** holding token amount in native token */
+    amountInNative: string;
+    /** token decimals */
+    decimals: number;
+    /**
+     * Whether the wallet currently holds a positive balance of this token (Phase 3).
+     * Always `true` in `net-worth/tokens` responses (the endpoint filters closed positions out).
+     */
+    isActive?: boolean;
+    /**
+     * Average cost basis in USD (Phase 3). Extremely sparse (~0.2% fill rate) —
+     * backed by historical buy prices and often unavailable.
+     */
+    avgCostUsd?: string;
+    /**
+     * Last time this wallet operated on this token (Phase 3). Sparse.
+     */
+    lastActiveAt?: Date;
+    /**
+     * Tags applied to the wallet for this specific token position (Phase 3). Sparse.
+     */
+    walletTokenTags?: Array<WalletTag>;
+}
+/**
+ * Wallet PnL summary
+ */
+interface WalletPnl {
+    /** chain id */
+    chain: Chain;
+    /** wallet address */
+    address: string;
+    /** total tokens traded */
+    tokens?: number;
+    /** total buy txs count */
+    buys?: number;
+    /** total sell txs count */
+    sells?: number;
+    /** total trades count */
+    totalTrades?: number;
+    /** total winning trades */
+    wins?: number;
+    /** total losing trades */
+    losses?: number;
+    /** win rate, range is 0-1 */
+    winRate?: string;
+    /** total buy amount in usd */
+    buyAmountInUsd?: string;
+    /** total sell amount in usd */
+    sellAmountInUsd?: string;
+    /** total cost in usd */
+    totalCostInUsd?: string;
+    /** realized profit in usd */
+    realizedProfitInUsd?: string;
+    /** realized profit ratio */
+    realizedProfitRatio?: string;
+    /** unrealized profit in usd */
+    unrealizedProfitInUsd?: string;
+    /** unrealized profit ratio */
+    unrealizedProfitRatio?: string;
+    /** total profit in usd (including both realized and unrealized profit) */
+    totalProfitInUsd?: string;
+    /** total profit ratio */
+    totalProfitRatio?: string;
+    /** average profit per trade in usd */
+    avgProfitPerTradeInUsd?: string;
+}
+/**
+ * Wallet portfolio PnL details (paged, with summary)
+ */
+interface WalletPortfolioPnls extends WalletPnl, CursorPagination {
+    /** per-token portfolio + pnl details */
+    portfolios: Array<PortfolioPnl>;
+}
+/**
+ * Wallet portfolios
+ */
+interface WalletPortfolios extends CursorPagination {
+    /** chain id */
+    chain: Chain;
+    /** wallet address */
+    address: string;
+    /** wallet total balance in usd */
+    balanceInUsd: string;
+    /** wallet total balance in native token */
+    balanceInNative: string;
+    /** wallet portfolios */
+    portfolios: Array<Portfolio>;
+}
+
+/**
+ * Resolution window for wallet PnL queries (Phase 3).
+ *
+ * Two related endpoints surface this concept:
+ * - `getWalletPortfolioPnls` (per-token, Phase 3) requires this exact set on
+ *   the server; other values yield HTTP 400.
+ * - `getWalletPnl` (summary) and `subscribeWalletPnl` are typed against the
+ *   same union for callers' ergonomics. The implementation maps to whatever
+ *   the upstream SDK accepts; values outside the upstream's set may fall
+ *   through to a server-side default.
+ */
+type WalletPnlResolution = "7d" | "30d" | "90d";
+/**
+ * Position state filter for wallet PnL details (Phase 3).
+ * - `open`   — only tokens with current balance > 0 (default)
+ * - `closed` — only tokens with balance == 0 (historical realized PnL)
+ * - `all`    — both open and closed positions
+ */
+type PositionState = "open" | "closed" | "all";
+/**
+ * Sort field for wallet PnL details (Phase 3).
+ */
+type WalletPnlSortBy = "totalPnl" | "realizedPnl" | "unrealizedPnl";
+/**
+ * Options for getting wallet portfolio PnL details (Phase 3).
+ */
+interface GetWalletPortfolioPnlsOptions extends CursorListOptions {
+    /**
+     * Statistics time window. Defaults to `30d` in the Client implementation
+     * for backward compatibility; the server requires this parameter and will
+     * return 400 if it is missing.
+     */
+    resolution?: WalletPnlResolution;
+    /** Position state filter. Defaults to `open` on the server. */
+    positionState?: PositionState;
+    /**
+     * Sort field. Defaults to `totalPnl` on the server.
+     * Switching `sortBy` requires discarding the old cursor.
+     */
+    sortBy?: WalletPnlSortBy;
+}
+/**
+ * Options for listing a wallet's limit orders.
+ *
+ * NOTE: The server does not yet implement a limit-orders endpoint. The
+ * `Client.getWalletLimitOrders` method throws a `NotImplementedError` and
+ * the React hook surfaces an empty result so the widget layer can be built
+ * ahead of backend availability.
+ */
+interface GetWalletLimitOrdersOptions extends CursorListOptions {
+    /** filter by order state; defaults to `active`. */
+    state?: LimitOrderState;
+    /** restrict to a single token when provided. */
+    tokenAddress?: string;
+}
+
+/**
+ * Subscription handle returned by `ISubscribeClient.*` methods. Call
+ * {@link ISubscription.unsubscribe} to detach the listener and release server
+ * resources.
+ */
+interface ISubscription {
+    unsubscribe(): void;
+}
+/**
+ * Incremental token update from subscriptions.
+ * `chain` + `address` identify the token; all other fields are optional —
+ * `undefined` means this push did not carry that field.
+ */
+type TokenSubscribed = Partial<Omit<Token, "chain" | "address">> & Pick<Token, "chain" | "address">;
+interface WalletPnlSubscribed extends WalletPnl {
+    /** pnl resolution window matching the originating subscription */
+    resolution?: WalletPnlResolution;
+}
+interface PortfolioSubscribed {
+    /** chain id */
+    chain: Chain;
+    /** wallet address */
+    walletAddress: string;
+    /** token address */
+    tokenAddress: string;
+    /** token current price in usd */
+    priceInUsd?: string;
+    /** holding token amount */
+    amount?: string;
+}
+type PortfolioPnlSubscribed = Partial<Omit<PortfolioPnl, "address" | "name" | "symbol" | "image">> & {
+    /** wallet address */
+    walletAddress: string;
+    /** token address */
+    tokenAddress: string;
+};
+
+declare enum SwapMode {
+    EXACT_IN = "exact_in",
+    EXACT_OUT = "exact_out"
+}
+/**
+ * DEX identifier used for route / mint address conversion. Open union — the
+ * known values cover today's DEXes; new aggregators can be plugged in without
+ * a library update.
+ */
+type SwapDex = "jupiter" | "kyberswap" | (string & {});
+interface SwapParams {
+    /** chain id */
+    chain: Chain;
+    /** DEX to use; if omitted, inferred from chain (Solana → jupiter, EVM → kyberswap). Mint conversion uses this. */
+    dex?: SwapDex;
+    /** user wallet address */
+    userAddress: string;
+    /** input token address */
+    input: string;
+    /** output token address */
+    output: string;
+    /** swap mode, e.g. ExactIn, ExactOut */
+    mode: SwapMode;
+    /** input token amount when mode is ExactIn, output token amount when mode is ExactOut */
+    amount: string;
+    /** slippage, range is 0-100 */
+    slippage?: number;
+    /** priority fee */
+    priorityFee?: string;
+    /** tip fee */
+    tipFee?: string;
+    /** whether to use anti-MEV */
+    isAntiMev?: boolean;
+    /** EIP-2612 permit data (EVM only, alternative to on-chain approve) */
+    permit?: string;
+    /** deadline timestamp in ms (EVM only) */
+    deadline?: number;
+}
+interface SwapRoutePlan {
+    /** protocol name / dex name etc. */
+    name: string;
+    /** input token address */
+    input: string;
+    /** input token amount */
+    inputAmount: string;
+    /** output token address */
+    output: string;
+    /** output token amount */
+    outputAmount: string;
+    /** fee quote token address */
+    feeQuote?: string;
+    /** fee amount */
+    feeAmount?: string;
+    /** extra infos by api provider */
+    extra?: Record<string, unknown>;
+}
+interface SwapRoute {
+    /** unsigned tx in base64 format */
+    serializedTx: string;
+    /** recent blockhash embedded in the unsigned Solana transaction */
+    recentBlockhash?: string;
+    /** last block height at which the embedded Solana blockhash remains valid */
+    lastValidBlockHeight?: number;
+    /** swap plans */
+    plans: Array<SwapRoutePlan>;
+    /** extra infos by api provider */
+    extra?: Record<string, unknown>;
+}
+
+/**
+ * Time window prefix used by per-resolution token metric fields.
+ */
+type Timeframe = "1m" | "5m" | "15m" | "30m" | "1h" | "4h" | "24h";
+/**
+ * Metric base name that is repeated across timeframes.
+ */
+type TimeBasedMetric = "buys" | "sells" | "trades" | "traders" | "volumes" | "priceChange";
+/**
+ * Cross-product of metric × timeframe (e.g. `buys1m`, `priceChange24h`).
+ * Generated from {@link TimeBasedMetric} and {@link Timeframe} so adding a new
+ * timeframe / metric is a one-line change.
+ */
+type TimeBasedField = `${TimeBasedMetric}${Capitalize<Timeframe>}`;
+/**
+ * Token field names that do not have a per-resolution variant.
+ */
+type StandaloneField = "price" | "marketCap" | "tvl" | "holders" | "top10Holdings" | "top10Ratio" | "top100Holdings" | "top100Ratio" | "creatorsHoldings" | "creatorsRatio" | "launchedFromProtocolFamily" | "migratedToProtocolFamily" | "tag" | "createdAt";
+/**
+ * Token field for filtering / sorting. Open union: server-defined fields not
+ * known to the SDK are still acceptable via the `(string & {})` escape hatch.
+ */
+type TokenFieldOption = TimeBasedField | StandaloneField | (string & {});
+/**
+ * Token filter option.
+ */
+interface TokenFilterOption {
+    field: TokenFieldOption;
+    operator: "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "between" | "in" | "nin" | "contains" | "notContains" | "startsWith" | "endsWith" | "isNotNull" | "isNull";
+    value?: string | number | boolean | Array<string | number | boolean>;
+}
+/**
+ * Options for getting token candles.
+ */
+interface GetTokenCandlesOptions {
+    /** query candles after this timestamp */
+    after?: Date;
+    /** query candles before this timestamp */
+    before?: Date;
+    /** return limit */
+    limit?: number;
+}
+/**
+ * Options for getting token list.
+ */
+interface GetTokenListOptions {
+    /** sort field */
+    sortBy?: TokenFieldOption;
+    /** sort direction */
+    sortDirection?: "asc" | "desc";
+    /** filters */
+    filters?: Array<TokenFilterOption>;
+    /** search keywords */
+    keywords?: Array<string>;
+    /** exclude keywords */
+    excludeKeywords?: Array<string>;
+}
+/**
+ * Options for searching tokens.
+ */
+interface SearchTokensOptions extends CursorListOptions {
+    /** chains */
+    chains?: Array<Chain>;
+    /** search keyword */
+    keyword?: string;
+    /** filters */
+    filters?: Array<TokenFilterOption>;
+    /** sort field */
+    sortBy?: TokenFieldOption;
+    /** sort direction */
+    sortDirection?: "asc" | "desc";
+}
+/**
+ * Search token cursor list.
+ */
+interface SearchTokenCursorList extends CursorList<Token> {
+    /** total count */
+    total?: number;
+    /** extra infos by api provider */
+    extra?: Record<string, unknown>;
+}
+/**
+ * Sort field for token holder list (Phase 3).
+ * - `holdingUsd`     — order by holding value in USD (default, descending)
+ * - `lastActiveAt`   — order by wallet's last activity time
+ * - `realizedPnl`    — order by realized PnL on this token; used by the
+ *                     Top Traders view, which shares the same endpoint but
+ *                     surfaces traders ranked by profit. Server support for
+ *                     this sort key is required by `getTopTokenTraders`.
+ */
+type TokenHoldersSortBy = "holdingUsd" | "lastActiveAt" | "realizedPnl";
+/**
+ * Options for getting token holders (Phase 3).
+ */
+interface GetTokenHoldersOptions extends CursorListOptions {
+    /**
+     * Sort field. Defaults to `holdingUsd` on the server.
+     * Switching `sortBy` requires discarding the old cursor and restarting from page 1.
+     */
+    sortBy?: TokenHoldersSortBy;
+}
+/**
+ * Resolution subset supported by the trending token list.
+ */
+type TrendingResolution = Extract<TokenResolution, "1m" | "5m" | "1h" | "4h" | "24h">;
+/**
+ * Options for listing tokens created by a given wallet (the "Dev Tokens" tab).
+ *
+ * NOTE: The server does not yet implement a creator-index endpoint. The
+ * `Client.getTokensByCreator` method throws a `NotImplementedError` and the
+ * React hook surfaces an empty result for now.
+ */
+interface GetTokensByCreatorOptions extends CursorListOptions {
+    /** optional sort field; server behaviour will be defined when endpoint ships. */
+    sortBy?: TokenFieldOption;
+    /** sort direction. */
+    sortDirection?: "asc" | "desc";
+}
+
+interface LatestBlockParams {
+    /** chain id */
+    chain: Chain;
+}
+interface BlockchainLatestBlock {
+    /** latest block hash */
+    blockhash: string;
+    /** last valid block height for transactions built with the latest blockhash */
+    lastValidBlockHeight: number;
+}
+interface SendTxParams {
+    /** chain id */
+    chain: Chain;
+    /** signed tx in base64 format */
+    serializedTx: string;
+    /** extra infos needed by api provider */
+    extra?: Record<string, unknown>;
+}
+interface SendTxResult {
+    /** tx hash */
+    txHash: string;
+    /** extra infos by api provider */
+    extra?: Record<string, unknown>;
+}
+
+/**
+ * API client interface — read-side data + transaction broadcast.
+ */
+interface IClient {
+    /**
+     * fetch token info
+     * @param chain chain id
+     * @param address token address
+     * @returns token info
+     */
+    getToken(chain: Chain, address: string): Promise<Token>;
+    /**
+     * fetch token infos in batch
+     * @param chain chain id
+     * @param addresses token addresses
+     * @returns token infos
+     */
+    getTokens(chain: Chain, addresses: Array<string>): Promise<Array<Token>>;
+    /**
+     * fetch token candles
+     * @param chain chain id
+     * @param address token address
+     * @param resolution token resolution
+     * @param options optional query options
+     * @returns token candles
+     */
+    getTokenCandles(chain: Chain, address: string, resolution: TokenResolution, options?: GetTokenCandlesOptions): Promise<Array<TokenCandle>>;
+    /**
+     * fetch token security
+     * @param chain chain id
+     * @param address token address
+     * @returns token security
+     */
+    getTokenSecurity(chain: Chain, address: string): Promise<TokenSecurity>;
+    /**
+     * fetch token stats
+     * @param chain chain id
+     * @param address token address
+     * @returns token stats
+     */
+    getTokenStats(chain: Chain, address: string): Promise<TokenStats>;
+    /**
+     * fetch token holders
+     * @param chain chain id
+     * @param address token address
+     * @param options optional query options (Phase 3: sortBy)
+     * @returns token holders
+     */
+    getTokenHolders(chain: Chain, address: string, options?: GetTokenHoldersOptions): Promise<CursorList<TokenHolder>>;
+    /**
+     * fetch token market data
+     * @param chain chain id
+     * @param address token address
+     * @returns token market data
+     */
+    getTokenMarketData(chain: Chain, address: string): Promise<TokenMarketData>;
+    /**
+     * fetch `New` token list
+     * @param chain chain id
+     * @param options optional query options
+     * @returns `New` token list
+     */
+    getNewTokens(chain: Chain, options?: GetTokenListOptions): Promise<Array<Token>>;
+    /**
+     * fetch `Final Stretch` token list
+     * @param chain chain id
+     * @param options optional query options
+     * @returns `Final Stretch` token list
+     */
+    getFinalStretchTokens(chain: Chain, options?: GetTokenListOptions): Promise<Array<Token>>;
+    /**
+     * fetch `Migrated` token list
+     * @param chain chain id
+     * @param options optional query options
+     * @returns `Migrated` token list
+     */
+    getMigratedTokens(chain: Chain, options?: GetTokenListOptions): Promise<Array<Token>>;
+    /**
+     * fetch `Trending` token list
+     * @param chain chain id
+     * @param resolution query resolution, e.g. "1m", "5m", "1h", "4h", "24h"
+     * @param options optional query options
+     * @returns `Trending` token list
+     */
+    getTrendingTokens(chain: Chain, resolution: TrendingResolution, options?: GetTokenListOptions): Promise<Array<Token>>;
+    /**
+     * fetch `Stock` token list
+     * @param chain chain id
+     * @param options optional query options
+     * @returns `Stock` token list
+     */
+    getStockTokens(chain: Chain, options?: GetTokenListOptions): Promise<Array<Token>>;
+    /**
+     * search tokens
+     * @param options optional query options
+     * @returns search token cursor list
+     */
+    searchTokens(options?: SearchTokensOptions): Promise<SearchTokenCursorList>;
+    /**
+     * fetch swap route plans
+     * @param params swap params
+     * @returns swap route plans
+     */
+    swapRoute(params: SwapParams): Promise<SwapRoute>;
+    /**
+     * fetch latest block metadata
+     * @param params latest block params
+     * @returns latest block metadata
+     */
+    getLatestBlock(params: LatestBlockParams): Promise<BlockchainLatestBlock>;
+    /**
+     * send tx
+     * @param params send tx params
+     * @returns send tx result
+     */
+    sendTx(params: SendTxParams): Promise<SendTxResult>;
+    /**
+     * check if tx is successful
+     * @param chain chain id
+     * @param txHash tx hash
+     * @param timeout timeout in milliseconds
+     * @returns true if tx is successful, false otherwise
+     */
+    checkTxSuccess(chain: Chain, txHash: string, timeout?: number): Promise<boolean>;
+    /**
+     * fetch wallet portfolios
+     * @param chain chain id
+     * @param address wallet address
+     * @param options optional pagination options
+     * @returns wallet portfolios
+     */
+    getWalletPortfolios(chain: Chain, address: string, options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<WalletPortfolios>;
+    /**
+     * fetch wallet PnL summary
+     * @param chain chain id
+     * @param address wallet address
+     * @param resolution pnl resolution window (e.g. `"7d"`, `"30d"`, `"90d"`)
+     * @returns wallet pnl summary
+     */
+    getWalletPnl(chain: Chain, address: string, resolution?: WalletPnlResolution): Promise<WalletPnl>;
+    /**
+     * fetch wallet portfolio PnL details (per-token)
+     * @param chain chain id
+     * @param address wallet address
+     * @param options optional query options (Phase 3: resolution, positionState, sortBy)
+     * @returns portfolio pnl list with summary
+     */
+    getWalletPortfolioPnls(chain: Chain, address: string, options?: GetWalletPortfolioPnlsOptions): Promise<WalletPortfolioPnls>;
+    /**
+     * fetch wallet portfolios for specific tokens
+     * @param chain chain id
+     * @param address wallet address
+     * @param tokenAddresses token addresses to query
+     * @returns portfolio list for the specified tokens
+     */
+    getWalletPortfoliosByTokens(chain: Chain, address: string, tokenAddresses: Array<string>): Promise<Array<Portfolio>>;
+    /**
+     * fetch wallet portfolio PnL for specific tokens
+     * @param chain chain id
+     * @param address wallet address
+     * @param tokenAddresses token addresses to query
+     * @returns portfolio pnl list for the specified tokens
+     */
+    getWalletPortfolioPnlsByTokens(chain: Chain, address: string, tokenAddresses: Array<string>): Promise<Array<PortfolioPnl>>;
+    /**
+     * fetch wallet's trade activities
+     * @param chain chain id
+     * @param address wallet address
+     * @param options optional query options
+     * @returns wallet's trade activities
+     */
+    getWalletTrades(chain: Chain, address: string, options?: GetTradesOptions): Promise<CursorList<Trade>>;
+    /**
+     * fetch token's trade activities
+     * @param chain chain id
+     * @param address token address
+     * @param options optional query options
+     * @returns token's trade activities
+     */
+    getTokenTrades(chain: Chain, address: string, options?: GetTradesOptions): Promise<CursorList<Trade>>;
+    /**
+     * fetch wallet's activities (trades, liquidity, red packets, etc.)
+     * @param chain chain id
+     * @param address wallet address
+     * @param options optional query options
+     * @returns wallet's activities
+     */
+    getWalletActivities(chain: Chain, address: string, options?: GetActivitiesOptions): Promise<CursorList<Activity>>;
+    /**
+     * fetch token's activities (trades, liquidity, red packets, etc.)
+     * @param chain chain id
+     * @param address token address
+     * @param options optional query options
+     * @returns token's activities
+     */
+    getTokenActivities(chain: Chain, address: string, options?: GetActivitiesOptions): Promise<CursorList<Activity>>;
+    /**
+     * get presigned upload url
+     * @returns presigned upload url
+     */
+    getPresignedUploadUrl(): Promise<string>;
+    /**
+     * fetch a wallet's limit orders.
+     *
+     * Currently unsupported by the backend; implementations throw
+     * `NotImplementedError` to make the gap explicit while the widget-layer
+     * clone of Axiom's Orders tab is being developed.
+     * @param chain chain id
+     * @param address wallet address
+     * @param options optional query options
+     */
+    getWalletLimitOrders(chain: Chain, address: string, options?: GetWalletLimitOrdersOptions): Promise<CursorList<LimitOrder>>;
+    /**
+     * fetch tokens created by a wallet ("Dev Tokens").
+     *
+     * Currently unsupported by the backend; implementations throw
+     * `NotImplementedError`.
+     * @param chain chain id
+     * @param creator creator wallet address
+     * @param options optional query options
+     */
+    getTokensByCreator(chain: Chain, creator: string, options?: GetTokensByCreatorOptions): Promise<CursorList<Token>>;
+}
+/**
+ * Subscribe client interface — push-side real-time data.
+ */
+interface ISubscribeClient {
+    /**
+     * Subscribe to a token's real-time data updates (stats, market data,
+     * holders, liquidity, etc.). The client internally manages multiple
+     * backend channels and delivers incremental updates via `callback`.
+     * @param chain chain id
+     * @param address token address
+     * @param callback receives incremental token updates
+     * @returns subscription
+     */
+    subscribeToken(chain: Chain, address: string, callback: (data: Array<TokenSubscribed>) => void): ISubscription;
+    /**
+     * Subscribe token new candles
+     * @param chain chain id
+     * @param address token address
+     * @param resolution token resolution
+     * @param callback callback function
+     * @returns subscription
+     */
+    subscribeTokenCandles(chain: Chain, address: string, resolution: TokenResolution, callback: (candles: Array<TokenCandle>) => void): ISubscription;
+    /**
+     * Subscribe wallet's pnl changes
+     * @param chain chain id
+     * @param address wallet address
+     * @param callback callback function
+     * @returns subscription
+     */
+    subscribeWalletPnl(chain: Chain, address: string, callback: (pnls: Array<WalletPnlSubscribed>) => void): ISubscription;
+    /**
+     * Subscribe wallet's portfolio changes
+     * @param chain chain id
+     * @param address wallet address
+     * @param callback callback function
+     * @returns subscription
+     */
+    subscribeWalletPortfolios(chain: Chain, address: string, callback: (portfolios: Array<PortfolioSubscribed>) => void): ISubscription;
+    /**
+     * Subscribe wallet's portfolio pnl changes
+     * @param chain chain id
+     * @param address wallet address
+     * @param callback callback function
+     * @returns subscription
+     */
+    subscribeWalletPortfolioPnls(chain: Chain, address: string, callback: (portfolioPnls: Array<PortfolioPnlSubscribed>) => void): ISubscription;
+    /**
+     * Subscribe wallet's new trade activities
+     * @param chain chain id
+     * @param address wallet address
+     * @param callback callback function
+     * @returns subscription
+     */
+    subscribeWalletTrades(chain: Chain, address: string, callback: (trades: Array<Trade>) => void): ISubscription;
+    /**
+     * Subscribe token's new trade activities
+     * @param chain chain id
+     * @param address token address
+     * @param callback callback function
+     * @returns subscription
+     */
+    subscribeTokenTrades(chain: Chain, address: string, callback: (trades: Array<Trade>) => void): ISubscription;
+    /**
+     * Subscribe wallet's new activities (trades, liquidity, etc.)
+     * @param chain chain id
+     * @param address wallet address
+     * @param callback callback function
+     * @returns subscription
+     */
+    subscribeWalletActivities(chain: Chain, address: string, callback: (activities: Array<Activity>) => void): ISubscription;
+    /**
+     * Subscribe token's new activities (trades, liquidity, etc.)
+     * @param chain chain id
+     * @param address token address
+     * @param callback callback function
+     * @returns subscription
+     */
+    subscribeTokenActivities(chain: Chain, address: string, callback: (activities: Array<Activity>) => void): ISubscription;
+    /**
+     * Subscribe to `New` token list real-time updates. The client internally
+     * manages multiple backend channels (new token events, metadata, stats,
+     * holders, supply, liquidity, bonding curve) and delivers incremental
+     * updates via `callback`.
+     * @param chain chain id
+     * @param callback receives incremental token updates
+     * @returns subscription
+     */
+    subscribeNewTokens(chain: Chain, callback: (data: Array<TokenSubscribed>) => void): ISubscription;
+    /**
+     * Subscribe to `Trending` token list real-time updates. The client
+     * internally manages multiple backend channels (stats, holders, supply,
+     * liquidity) and delivers incremental updates via `callback`.
+     * @param chain chain id
+     * @param callback receives incremental token updates
+     * @returns subscription
+     */
+    subscribeTrendingTokens(chain: Chain, callback: (data: Array<TokenSubscribed>) => void): ISubscription;
+    /**
+     * Subscribe to `Migrated` token list real-time updates. The client
+     * internally manages multiple backend channels (stats, holders, supply,
+     * liquidity) and delivers incremental updates via `callback`.
+     * @param chain chain id
+     * @param callback receives incremental token updates
+     * @returns subscription
+     */
+    subscribeMigratedTokens(chain: Chain, callback: (data: Array<TokenSubscribed>) => void): ISubscription;
+    /**
+     * Subscribe to `FinalStretch` token list real-time updates. The client
+     * internally manages multiple backend channels (stats, holders, supply,
+     * liquidity, bonding curve) and delivers incremental updates via `callback`.
+     * @param chain chain id
+     * @param callback receives incremental token updates
+     * @returns subscription
+     */
+    subscribeFinalStretchTokens(chain: Chain, callback: (data: Array<TokenSubscribed>) => void): ISubscription;
+    /**
+     * Subscribe to `Stock` token list real-time updates. The client internally
+     * manages multiple backend channels (stats, holders, supply, liquidity)
+     * and delivers incremental updates via `callback`.
+     * @param chain chain id
+     * @param callback receives incremental token updates
+     * @returns subscription
+     */
+    subscribeStockTokens(chain: Chain, callback: (data: Array<TokenSubscribed>) => void): ISubscription;
+}
+
+export { type ActivityToken as A, type ActivitiesSortBy, type BlockchainLatestBlock, Chain as C, type CursorList, type CursorListOptions, type CursorPagination, type GetActivitiesOptions, type GetTokenCandlesOptions, type GetTokenHoldersOptions, type GetTokenListOptions, type GetTokensByCreatorOptions, type GetTradesOptions, type GetWalletLimitOrdersOptions, type GetWalletPortfolioPnlsOptions, type IClient, type ISubscribeClient, type ISubscription, type LimitOrderSide as L, type LatestBlockParams, type PortfolioPnl as P, type PortfolioPnlSubscribed, type PortfolioSubscribed, type PositionState, SolanaTokenProtocol as S, type SearchTokenCursorList, type SearchTokensOptions, type SendTxParams, type SendTxResult, type SwapDex, SwapMode, type SwapParams, type SwapRoute, type SwapRoutePlan, type Trade as T, type TokenFieldOption, type TokenFilterOption, type TokenHoldersSortBy, type TokenSubscribed, type TrendingResolution, type WalletTag as W, type WalletPnlResolution, type WalletPnlSortBy, type WalletPnlSubscribed, type ActivityDex as a, type ActivityType as b, type Activity as c, ChainNamespace as d, type LimitOrderState as e, type LimitOrder as f, type TokenProtocol as g, SOLANA_TOKEN_PROTOCOLS as h, type Token as i, type TokenCreator as j, type TokenLaunchedFrom as k, type TokenMigratedTo as l, type TokenSocialMedias as m, type TokenStats as n, type TokenStatsByResolution as o, type TokenMarketData as p, type TokenLiquidity as q, type TokenSecurity as r, type TokenResolution as s, type TokenCandle as t, type TokenHolder as u, type Portfolio as v, type WalletPnl as w, type WalletPortfolioPnls as x, type WalletPortfolios as y };