UNPKG

@solana-tracker/data-api

Version:

Official Solana Tracker Data API client for accessing Solana Data

1,979 lines (1,977 loc) 112 kB
import { EventEmitter } from 'events'; interface TokenInfo { name: string; symbol: string; mint: string; uri?: string; decimals: number; description?: string; image?: string; hasFileMetaData?: boolean; strictSocials?: { twitter?: string; telegram?: string; discord?: string; website?: string; }; showName?: boolean; twitter?: string; telegram?: string; website?: string; discord?: string; createdOn?: string; creation?: { creator: string; created_tx: string; created_time: number; }; [key: string]: any; } interface TokenSecurity { freezeAuthority: string | null; mintAuthority: string | null; } interface TokenPoolTxns { buys: number; sells: number; total: number; volume: number; volume24h: number; } interface TokenValuePair { quote: number; usd: number; } interface LaunchpadLiquidity$1 { amount: number; usd: number; } interface Launchpad$1 { name: string; url: string; logo: string; baseLiquidity: LaunchpadLiquidity$1; quoteLiquidity: LaunchpadLiquidity$1; } interface MeteoraCurveLiquidity$1 { base?: number; quote?: number; usd: number; } interface MeteoraCurve$1 { baseLiquidity: MeteoraCurveLiquidity$1; quoteLiquidity: MeteoraCurveLiquidity$1; fee: number; name?: string; url?: string; logo?: string; } interface RiskWallet { address: string; balance: number; percentage: number; } interface RiskCategory { count: number; totalBalance: number; totalPercentage: number; wallets: RiskWallet[]; } interface BundlerWallet { wallet: string; initialBalance: number; initialPercentage: number; balance: number; percentage: number; bundleTime: number; } interface BundlersCategory { count: number; totalBalance: number; totalPercentage: number; totalInitialBalance: number; totalInitialPercentage: number; wallets: BundlerWallet[]; } interface BundlersResponse { total: number; balance: number; percentage: number; initialBalance: number; initialPercentage: number; wallets: BundlerWallet[]; } interface MultiTokensResponse { tokens: { [tokenAddress: string]: TokenDetailResponse; }; } interface PoolInfo { poolId: string; liquidity: TokenValuePair; price: TokenValuePair; tokenSupply: number; lpBurn: number; tokenAddress: string; marketCap: TokenValuePair; market: string; quoteToken: string; decimals: number; security: TokenSecurity; lastUpdated: number; deployer?: string; txns?: TokenPoolTxns; curvePercentage?: number; curve?: string; createdAt?: number; bundleId?: string; launchpad?: Launchpad$1; meteoraCurve?: MeteoraCurve$1; raydium?: { baseLiquidity: number; quoteLiquidity: number; }; heaven?: { baseLiquidity: number; quoteLiquidity: number; is_migrated: boolean; migrationTime?: number; }; pumpfun?: { tokenProgram?: string; isMayhemMode?: boolean; }; 'pumpfun-amm'?: { tokenProgram?: string; isMayhemMode?: boolean; }; /** Pool creation data - only present on new/graduated pool messages */ creation?: { creator: string; created_tx: string; created_time: number; }; } interface PriceChangeData { priceChangePercentage: number; } interface TokenEvents { "1m"?: PriceChangeData; "5m"?: PriceChangeData; "15m"?: PriceChangeData; "30m"?: PriceChangeData; "1h"?: PriceChangeData; "2h"?: PriceChangeData; "3h"?: PriceChangeData; "4h"?: PriceChangeData; "5h"?: PriceChangeData; "6h"?: PriceChangeData; "12h"?: PriceChangeData; "24h"?: PriceChangeData; } interface DevHolding { percentage: number; amount: number; } interface RiskFees { jito?: number; network?: number; bloom?: number; maestro?: number; soltradingbot?: number; bullx?: number; photon?: number; trojan?: number; padre?: number; nextblock?: number; totalTrading?: number; totalTips?: number; total?: number; [key: string]: number | undefined; } interface TokenRisk { snipers: RiskCategory; insiders: RiskCategory; bundlers: BundlersCategory; top10: number; dev: DevHolding; fees?: RiskFees; rugged: boolean; risks: TokenRiskFactor[]; score: number; jupiterVerified?: boolean; } interface TokenRiskFactor { name: string; description: string; value?: string | number; level: "warning" | "danger"; score: number; } interface TokenDetailResponse { token: TokenInfo; pools: PoolInfo[]; events: TokenEvents; risk: TokenRisk; buys: number; sells: number; txns: number; holders?: number; } interface Holder { wallet: string; amount: number; value: TokenValuePair; percentage: number; } interface TopHolder$1 { address: string; amount: number; percentage: number; value: TokenValuePair; } /** * Flat per-token PnL returned in `/tokens/:tokenAddress/holders?enrich=walletPnl`. * * Distinct from the nested `PnlV2Position` shape: holder enrichment uses flat * field names (`buys`/`sells`, `totalBought`/`totalSold`, `avgBuy`/`avgSell`) * for backwards compatibility. */ interface EnrichedTokenPnl { realized: number | null; unrealized: number | null; total: number | null; invested: number | null; proceeds: number | null; buys: number; sells: number; totalTrades: number; roi: number | null; /** Current token balance (native units). */ balance: number | null; /** Cost basis of remaining held tokens (USD). */ costBasis: number | null; /** Current USD value of held tokens. */ value: number | null; /** Current token price (USD). */ price: number | null; /** Total tokens purchased (native units). */ totalBought: number | null; /** Total tokens sold (native units). */ totalSold: number | null; /** Average buy size (USD). */ avgBuy: number | null; /** Average sell size (USD). */ avgSell: number | null; /** Average cost per token (USD). */ avgCost?: number | null; /** Unix ms. */ firstBuy: number | null; /** Unix ms. */ lastBuy: number | null; /** Unix ms. */ firstSell: number | null; /** Unix ms. */ lastSell: number | null; /** Unix ms. */ firstTrade: number | null; /** Unix ms. */ lastTrade: number | null; /** Hold duration in seconds. */ holdTimeSecs: number | null; } interface TokenHoldersResponse { total: number; enrich?: string[]; accounts: (Holder & { pnl?: { wallet?: PnlV2WalletLifetimePnl; token?: EnrichedTokenPnl; }; identity?: PnlV2Identity | null; })[]; } interface AthPrice { highest_price: number; highest_market_cap: number; timestamp: number; pool_id: string; } interface DeployerToken { name: string; symbol: string; mint: string; image?: string; decimals: number; hasSocials: boolean; poolAddress?: string; liquidityUsd: number; marketCapUsd: number; priceUsd: number; lpBurn: number; market: string; freezeAuthority: string | null; mintAuthority: string | null; createdAt: number; lastUpdated: number; buys: number; sells: number; totalTransactions: number; } interface DeployerTokensResponse<T = DeployerToken> { total: number; tokens: T[]; } /** * Parameters for the deployer endpoint (/deployer/:wallet) */ interface DeployerParams { /** Page number (default: 1) */ page?: number; /** Number of items per page (default: 250, max: 500, max: 100 when format=full) */ limit?: number; /** Filter by market(s) - single value or array (e.g., 'raydium' or ['raydium', 'orca', 'pumpfun']) */ market?: string | string[]; /** Filter by launchpad(s) - single value or array (e.g., 'pumpfun' or ['pumpfun', 'boop']) */ launchpad?: string | string[]; /** Return full token objects (same shape as /tokens/:token). Max limit is capped at 100. */ format?: 'full'; } interface SearchParams { query?: string; symbol?: string; page?: number; limit?: number; cursor?: string; sortBy?: string; sortOrder?: string; showAllPools?: boolean; showPriceChanges?: boolean; minCreatedAt?: number; maxCreatedAt?: number; minLiquidity?: number; maxLiquidity?: number; minMarketCap?: number; maxMarketCap?: number; minVolume?: number; maxVolume?: number; volumeTimeframe?: string; minVolume_5m?: number; maxVolume_5m?: number; minVolume_15m?: number; maxVolume_15m?: number; minVolume_30m?: number; maxVolume_30m?: number; minVolume_1h?: number; maxVolume_1h?: number; minVolume_6h?: number; maxVolume_6h?: number; minVolume_12h?: number; maxVolume_12h?: number; minVolume_24h?: number; maxVolume_24h?: number; minBuys?: number; maxBuys?: number; minSells?: number; maxSells?: number; minTotalTransactions?: number; maxTotalTransactions?: number; minHolders?: number; maxHolders?: number; minTop10?: number; maxTop10?: number; minDev?: number; maxDev?: number; minInsiders?: number; maxInsiders?: number; minSnipers?: number; maxSnipers?: number; lpBurn?: number; /** Filter by market(s) - single value or array (e.g., 'raydium' or ['raydium', 'orca', 'pumpfun']) */ market?: string | string[]; freezeAuthority?: string; mintAuthority?: string; deployer?: string; creator?: string; status?: string; minCurvePercentage?: number; maxCurvePercentage?: number; twitter?: string; telegram?: string; discord?: string; website?: string; facebook?: string; instagram?: string; youtube?: string; reddit?: string; tiktok?: string; github?: string; minBundlers?: number; maxBundlers?: number; minBundlerPercentage?: number; maxBundlerPercentage?: number; minRiskScore?: number; maxRiskScore?: number; minFeesTotal?: number; maxFeesTotal?: number; minFeesTrading?: number; maxFeesTrading?: number; minFeesTips?: number; maxFeesTips?: number; hasImage?: boolean; image?: string; hasSocials?: boolean; /** When `true`, only tokens with at least one monitored community message. When `false`, only tokens with zero messages. */ hasCoinCommunity?: boolean; /** Minimum live community message count (inclusive). */ minCommunityMessages?: number; /** Maximum live community message count (inclusive). */ maxCommunityMessages?: number; /** Filter by launchpad(s) - single value or array (e.g., 'pumpfun' or ['pumpfun', 'boop']) */ launchpad?: string | string[]; minGraduatedAt?: number; maxGraduatedAt?: number; /** Return full token objects (same shape as /tokens/:token). Max limit is capped at 100. */ format?: 'full'; [key: string]: string | number | boolean | string[] | undefined; } interface SearchResult { id: string; name: string; symbol: string; mint: string; image?: string; decimals: number; hasSocials: boolean; poolAddress: string; liquidityUsd: number; marketCapUsd: number; priceUsd: number; lpBurn: number; market: string; quoteToken: string; freezeAuthority: string | null; mintAuthority: string | null; deployer: string; status: string; createdAt: number; lastUpdated: number; holders: number; buys: number; sells: number; totalTransactions: number; volume: number; volume_5m: number; volume_15m: number; volume_30m: number; volume_1h: number; volume_6h: number; volume_12h: number; volume_24h: number; jupiter?: boolean; verified?: boolean; top10?: number; dev?: number; insiders?: number; snipers?: number; bundlers?: { count: number; balance: number; percentage: number; }; riskScore?: number; socials?: { twitter?: string; telegram?: string; discord?: string; website?: string; facebook?: string; instagram?: string; youtube?: string; reddit?: string; tiktok?: string; github?: string; }; fees?: { total?: number; totalTrading?: number; totalTips?: number; }; tokenDetails?: { creator: string; tx: string; time: number; }; launchpad?: { name: string; curvePercentage?: number; }; graduatedAt?: number; /** Whether the token has monitored Coin Communities chat activity. */ hasCoinCommunity?: boolean; /** Live community message count (messages observed since the feed monitor started). */ communityMessages?: number; events?: { "1m"?: { priceChangePercentage: number; }; "5m"?: { priceChangePercentage: number; }; "15m"?: { priceChangePercentage: number; }; "30m"?: { priceChangePercentage: number; }; "1h"?: { priceChangePercentage: number; }; "2h"?: { priceChangePercentage: number; }; "3h"?: { priceChangePercentage: number; }; "4h"?: { priceChangePercentage: number; }; "5h"?: { priceChangePercentage: number; }; "6h"?: { priceChangePercentage: number; }; "12h"?: { priceChangePercentage: number; }; "24h"?: { priceChangePercentage: number; }; }; } interface SearchResponse<T = SearchResult> { status: string; data: T[]; total?: number; pages?: number; page?: number; cursor?: string; nextCursor?: string; hasMore?: boolean; } interface TokenOverview { latest: TokenDetailResponse[]; graduating: TokenDetailResponse[]; graduated: TokenDetailResponse[]; } interface PriceData { price: number; liquidity: number; marketCap: number; lastUpdated: number; } interface PriceHistoryData { current: number; "3d"?: number; "5d"?: number; "7d"?: number; "14d"?: number; "30d"?: number; } interface PriceTimestampData { price: number; timestamp: number; timestamp_unix: number; pool: string; } interface PriceRangeData { token: string; price: { lowest: { price: number; time: number; }; highest: { price: number; time: number; }; }; } interface PriceChange { timeframe: string; percentage: number; } interface MultiPriceResponse { [tokenAddress: string]: PriceData; } interface WalletTokenData { address: string; balance: number; value: number; price: TokenValuePair; marketCap: TokenValuePair; liquidity: TokenValuePair; } interface WalletBasicResponse { tokens: WalletTokenData[]; total: number; totalSol: number; } interface TokenMetadata$1 { name: string; symbol: string; image?: string; decimals: number; } interface TradeTokenInfo { address: string; amount: number; token: TokenMetadata$1; } interface TradeTransaction { tx: string; from?: TradeTokenInfo; to?: TradeTokenInfo; amount?: number; priceUsd?: number; volume?: number; solVolume?: number; type?: string; wallet: string; time: number; program: string; pools?: string[]; token?: { from: TradeTokenInfo; to: TradeTokenInfo; }; } interface TradesResponse { trades: Trade[]; nextCursor?: number; hasNextPage?: boolean; } interface WalletTradesResponse { trades: WalletTrade[]; nextCursor?: number; hasNextPage?: boolean; } interface WalletTokenDetail { token: TokenInfo; pools?: PoolInfo[]; events?: TokenEvents; risk?: TokenRisk; balance: number; value: number; } interface WalletResponse { tokens: WalletTokenDetail[]; total: number; totalSol: number; timestamp: string; } interface OHLCVData { open: number; close: number; low: number; high: number; volume: number; time: number; } interface ChartResponse { oclhv: OHLCVData[]; } interface HolderChartData { holders: number; time: number; } interface HoldersChartResponse { holders: HolderChartData[]; } interface SnipersChartData { percentage: number; time: number; } interface SnipersChartResponse { snipers: SnipersChartData[]; } interface InsidersChartData { percentage: number; time: number; } interface InsidersChartResponse { insiders: InsidersChartData[]; } interface BundlersChartData { percentage: number; time: number; } interface BundlersChartResponse { bundlers: BundlersChartData[]; } interface PnLData { holding: number; held: number; sold: number; realized: number; unrealized: number; total: number; total_sold: number; total_invested: number; average_buy_amount: number; current_value: number; cost_basis: number; sold_usd?: number; first_buy_time?: number; last_buy_time?: number; last_sell_time?: number; last_trade_time?: number; buy_transactions?: number; sell_transactions?: number; total_transactions?: number; } interface PnLSummary { realized: number; unrealized: number; total: number; totalInvested: number; averageBuyAmount: number; totalWins: number; totalLosses: number; winPercentage: number; lossPercentage: number; neutralPercentage?: number; } interface PnLResponse { tokens: { [tokenAddress: string]: PnLData; }; summary: PnLSummary; } interface TokenPnLResponse extends PnLData { } interface FirstBuyTransaction { signature: string; amount: number; volume_usd: number; time: number; } interface FirstBuyerData { wallet: string; first_buy_time: number; first_buy: FirstBuyTransaction; first_sell_time: number | null; last_transaction_time: number; held: number; sold: number; sold_usd: number; holding: number; realized: number; unrealized: number; total: number; total_invested: number; buy_transactions: number; sell_transactions: number; total_transactions: number; average_buy_amount: number; average_sell_amount: number; current_value: number; cost_basis: number; } interface TopTrader { wallet: string; summary: PnLSummary; } interface TopTradersResponse { wallets: TopTrader[]; } interface TokenStats { "1m"?: TimeframeStats; "5m"?: TimeframeStats; "15m"?: TimeframeStats; "30m"?: TimeframeStats; "1h"?: TimeframeStats; "4h"?: TimeframeStats; "24h"?: TimeframeStats; } interface TokenStatsTotal { buys: number; sells: number; total: number; volume: number; } interface WalletChartDataPoint { date: string; value: number; timestamp: number; pnlPercentage: number; } interface WalletChartPnLPeriod { value: number; percentage: number; } interface WalletChartResponse { chartData: WalletChartDataPoint[]; pnl: { '24h': WalletChartPnLPeriod; '30d': WalletChartPnLPeriod; }; } interface CreditsResponse { credits: number; } interface TradeMetadataToken { name: string; symbol: string; image?: string; decimals: number; amount: number; address: string; priceUsd: number; mint?: string; uri?: string; isMutable?: boolean; description?: string; tags?: string[]; extensions?: { website?: string; twitter?: string; telegram?: string; }; hasFileMetaData?: boolean; [key: string]: any; } interface TradeMetadata { from: TradeMetadataToken; to: TradeMetadataToken; } interface Trade { tx: string; amount: number; priceUsd: number; volume: number; volumeSol: number; type: "buy" | "sell"; wallet: string; time: number; program: string; pools: string[]; meta?: TradeMetadata; } interface WalletTrade { tx: string; from: { address: string; amount: number; token?: { name: string; symbol: string; image: string; decimals: number; price?: { usd: number; }; }; priceUsd: number; }; to: { address: string; amount: number; token?: { name: string; symbol: string; image: string; decimals: number; price?: { usd: number; }; }; priceUsd: number; }; price: { usd: number; sol?: string; }; volume: { usd: number; sol?: number; }; wallet: string; program: string; time: number; } interface EventsParams { /** Whether to decode the binary data into events array */ decode?: boolean; /** Whether to process events into statistics */ process?: boolean; /** Whether to process events asynchronously (for large datasets) */ async?: boolean; } interface TimeframeStats { buyers: number; sellers: number; volume: { buys: number; sells: number; total: number; }; transactions: number; buys: number; sells: number; wallets: number; price: number; priceChangePercentage: number; } interface TimeframeStats { buyers: number; sellers: number; volume: { buys: number; sells: number; total: number; }; transactions: number; buys: number; sells: number; wallets: number; price: number; priceChangePercentage: number; } interface ProcessedStats { '1m'?: TimeframeStats; '5m'?: TimeframeStats; '15m'?: TimeframeStats; '30m'?: TimeframeStats; '1h'?: TimeframeStats; '2h'?: TimeframeStats; '3h'?: TimeframeStats; '4h'?: TimeframeStats; '5h'?: TimeframeStats; '6h'?: TimeframeStats; '12h'?: TimeframeStats; '24h'?: TimeframeStats; } interface ProcessedEvent { wallet: string; amount: number; priceUsd: number; volume: number; type: 'buy' | 'sell'; time: number; } interface ProcessedEvent { wallet: string; amount: number; priceUsd: number; volume: number; type: 'buy' | 'sell'; time: number; } interface SubscriptionResponse { credits: number; plan: string; next_billing_date: string; status: string; } interface WalletBalanceUpdate { wallet: string; token: string; amount: number; } type PnlMode = 'strict' | 'adjusted' | 'raw'; interface PnlV2Block { realized: number | null; realizedRaw?: number | null; unrealized: number | null; total: number | null; } interface PnlV2Pagination { hasMore: boolean; nextCursor: string | null; count: number; total: number; pnlMode?: PnlMode; enrich?: string[]; } interface PnlV2IdentityBot { name: string | null; avatar: string | null; } interface PnlV2IdentityPool { program: string | null; poolAddress: string | null; tokenA?: string | null; tokenB?: string | null; } interface PnlV2IdentityDeveloper { token?: string | null; via?: string[]; pools?: string[]; creationTx?: string | null; createdAt?: number | null; tokens?: string[]; } interface PnlV2IdentityHacker { label: string | null; } interface PnlV2IdentitySpamDusting { label: string | null; } interface PnlV2IdentityExchange { name: string | null; } /** Primary `.sol` domain from Ridge (Solscan-style domain label). */ interface PnlV2IdentitySns { domain: string; } interface PnlV2Identity { /** * Display name. For SNS-only wallets this is the primary domain (e.g. `solanatracker.sol`). * When a higher-priority label exists (KOL, exchange, bot, etc.), that label keeps `name` * and the domain is still available on `sns.domain`. */ name?: string | null; twitter?: string | null; avatar?: string | null; /** Primary label type, e.g. `kol`, `sns`, `bot`, `developer`, `pool`, `exchange`. */ type?: string | null; /** All resolved labels, e.g. `['kol', 'sns']`. */ tags?: string[]; platforms?: string[]; /** Present when the wallet has a primary `.sol` domain (may coexist with other tags). */ sns?: PnlV2IdentitySns; bot?: PnlV2IdentityBot; pool?: PnlV2IdentityPool; developer?: PnlV2IdentityDeveloper; hacker?: PnlV2IdentityHacker; spamDusting?: PnlV2IdentitySpamDusting; exchange?: PnlV2IdentityExchange; } interface PnlV2WalletLifetimePnl { realized: number | null; unrealized: number | null; total: number | null; invested: number | null; proceeds: number | null; totalTrades: number; tokensTraded: number; } interface PnlV2TokenScopedPnl { token: PnlV2Block; /** * Lifetime wallet PnL summary. Only populated when the underlying response * is enriched with wallet PnL data (always on for `/v2/pnl/tokens/...` endpoints, * opt-in for `/tokens/:token/holders?enrich=walletPnl`). */ wallet?: PnlV2WalletLifetimePnl; } interface PnlV2PnlAdjustments { mode: PnlMode; invalidPnl: number | null; adjustedCorrection: number | null; } interface PnlV2TokenMeta { symbol: string | null; name: string | null; image?: string; decimals: number | null; price: number | null; snapshotPrice?: number | null; marketCap: number | null; liquidity: number | null; primaryMarket: string | null; } interface PnlV2WalletQueued { indexed: false; queued: true; message: string; } interface PnlV2Trader { wallet: string; pnl: PnlV2Block; invested: number | null; proceeds: number | null; openPositions: { cost: number | null; value: number | null; }; counts: { buys: number; sells: number; trades: number; tokensTraded: number; tokensHeldEver: number; }; averages: { buy: number | null; sell: number | null; }; tokens: { profitable: number; losing: number; closed: number; }; winRate: number | null; roi: number | null; timing: { firstTrade: number | null; lastTrade: number | null; }; updatedAt: string | null; } interface PnlV2TraderWithIdentity extends PnlV2Trader { identity: PnlV2Identity | null; } interface PnlV2PeriodTrader { wallet: string; period: { realized: number | null; volume: number | null; tradingDays: number; }; ending: { pnl: PnlV2Block; }; lastSnapshotDate: string | null; } interface PnlV2PeriodTraderWithIdentity extends PnlV2PeriodTrader { identity: PnlV2Identity | null; } interface PnlV2DayTrader { wallet: string; day: { realized: number | null; volume: number | null; cost: number | null; buys: number; sells: number; }; cumulative: { pnl: PnlV2Block; invested: number | null; proceeds: number | null; }; } interface PnlV2DayTraderWithIdentity extends PnlV2DayTrader { identity: PnlV2Identity | null; } interface PnlV2Top90dTrader { wallet: string; period: { realized: number | null; realizedRaw?: number | null; volume: number | null; tradingDays: number; roi: number | null; days?: { profitable: number; losing: number; maxSinglePnl: number | null; winRate: number | null; }; }; pnlAdjustments?: PnlV2PnlAdjustments; ending: { pnl: { realized: number | null; total: number | null; }; }; invested: number | null; proceeds: number | null; counts: { buys: number; sells: number; trades: number; tokensTraded: number; }; averages: { buy: number | null; sell: number | null; }; tokens: { profitable: number; losing: number; closed: number; }; winRate: number | null; timing: { firstTrade: number | null; lastTrade: number | null; }; lastSnapshotDate: string | null; updatedAt: string | null; identity?: PnlV2Identity | null; } interface PnlV2Holder { wallet: string; pnl: PnlV2TokenScopedPnl; identity?: PnlV2Identity | null; /** Legacy current-position snapshot. Same values as `current` (kept for compatibility). */ position: { balance: number | null; costBasis: number | null; value: number | null; price: number | null; }; /** Legacy. Same as `volume.buyUsd` / `invested`. */ buyUsd: number | null; /** Legacy. Same as `volume.sellUsd` / `proceeds`. */ sellUsd: number | null; counts: { buys: number; sells: number; total: number; }; roi: number | null; /** Total cost basis (USD spent buying). */ invested: number | null; /** Total USD received from selling. */ proceeds: number | null; volume: { tokensBought: number | null; tokensSold: number | null; buyUsd: number | null; sellUsd: number | null; }; averages: { buy: number | null; sell: number | null; }; current: { balance: number | null; costBasis: number | null; value: number | null; price: number | null; avgCost: number | null; }; /** Trade timing. All values are unix ms except `holdTimeSecs` (seconds). */ timing: { firstTrade: number | null; lastTrade: number | null; firstBuy: number | null; lastBuy: number | null; firstSell: number | null; lastSell: number | null; holdTimeSecs: number | null; }; } interface PnlV2Summary { pnl: PnlV2Block; invested: number | null; proceeds: number | null; openPositions: { cost: number | null; value: number | null; }; counts: { buys: number; sells: number; trades: number; tokensTraded: number; tokensHeldEver: number; }; averages: { buy: number | null; sell: number | null; }; roi: number | null; timing: { firstTrade: number | null; lastTrade: number | null; /** Average hold time in seconds across all positions with a first buy. */ avgHoldTimeSecs?: number | null; }; } interface PnlV2Position { token: string; pnl: PnlV2Block; invested: number | null; proceeds: number | null; roi: number | null; current: { balance: number | null; costBasis: number | null; value: number | null; price: number | null; avgCost: number | null; }; volume: { tokensBought: number | null; tokensSold: number | null; buyUsd: number | null; sellUsd: number | null; }; averages: { buy: number | null; sell: number | null; }; counts: { buys: number; sells: number; total: number; }; timing: { firstBuy: number | null; lastBuy: number | null; firstSell: number | null; lastSell: number | null; firstTrade: number | null; lastTrade: number | null; holdTimeSecs: number | null; }; meta?: PnlV2TokenMeta; portfolioPercent?: number | null; } interface PnlV2PositionWithWallet extends PnlV2Position { wallet: string; } interface PnlV2Snapshot { date: string; cumulative: { pnl: PnlV2Block; cost: number | null; proceeds: number | null; openPositions: { cost: number | null; value: number | null; }; counts: { buys: number; sells: number; tokensTraded: number; }; }; activity: { pnl: { realized: number | null; }; counts: { buys: number; sells: number; }; volume: { costUsd: number | null; total: number | null; }; averages: { buy: number | null; sell: number | null; realizedPnl: number | null; holdTimeSecs: number | null; }; }; } interface PnlV2ChartPoint { date: string; time: number; pnl: { realized: number | null; total: number | null; }; invested: number | null; proceeds: number | null; activity: { realizedPnl: number | null; buys: number; sells: number; volume: number | null; avgHoldTimeSecs: number | null; }; counts: { buys: number; sells: number; tokensTraded: number; }; } interface PnlV2KOLLeaderboardParams { sort?: 'total' | 'realized' | 'unrealized' | 'invested' | 'proceeds' | 'value' | 'trades' | 'tokens' | 'roi' | 'win_percentage' | 'last_trade'; direction?: 'asc' | 'desc'; limit?: number; cursor?: string; } interface PnlV2KOLPeriodParams { sort?: 'realized' | 'volume' | 'days' | 'ending_total'; direction?: 'asc' | 'desc'; limit?: number; cursor?: string; period?: '1d' | '7d' | '14d' | '30d' | '90d' | 'all'; start?: string; end?: string; } interface PnlV2KOLCalendarParams { year?: number; month?: number; } interface PnlV2KOLByDateParams { date?: string; } interface PnlV2TopTradersParams { sort?: 'realized' | 'volume' | 'days' | 'roi' | 'win_percentage' | 'trades' | 'tokens'; direction?: 'asc' | 'desc'; limit?: number; cursor?: string; platform?: string; excludeArbitrage?: string; pnlMode?: PnlMode; days?: number; minTrades?: number; minInvested?: number; minDays?: number; minWinRate?: number; minRoi?: number; minClosedTokens?: number; maxSingleTokenPct?: number; } interface PnlV2TokenTradersParams { sort?: 'holding' | 'value' | 'pnl' | 'realized' | 'unrealized' | 'invested' | 'roi' | 'last_trade' | 'first_trade'; direction?: 'asc' | 'desc'; limit?: number; cursor?: string; platform?: string; excludeArbitrage?: string; excludeZeroBuys?: string; activeOnly?: string; minTrades?: number; } interface PnlV2TokenFirstBuyersParams { sort?: 'first_trade'; direction?: 'asc'; limit?: number; cursor?: string; platform?: string; excludeArbitrage?: string; excludeZeroBuys?: string; activeOnly?: string; minTrades?: number; } interface PnlV2WalletHistoryParams { period?: '1d' | '7d' | '14d' | '30d' | '90d' | 'all'; start?: string; end?: string; limit?: number; } interface PnlV2WalletPerformanceParams { period?: '1d' | '7d' | '14d' | '30d' | '90d' | 'all'; days?: number; } interface PnlV2WalletPositionsParams { sort?: 'last_trade' | 'pnl' | 'realized' | 'unrealized' | 'roi' | 'value' | 'holding' | 'invested' | 'cost' | 'proceeds' | 'buys' | 'sells'; direction?: 'asc' | 'desc'; cursor?: string; limit?: number; filter?: 'all' | 'holding' | 'active' | 'sold' | 'profitable' | 'losing'; period?: '1d' | '7d' | '14d' | '30d' | '90d' | 'all'; pnlMode?: PnlMode; tokens?: string; minValue?: number; maxValue?: number; minPnl?: number; maxPnl?: number; minInvested?: number; maxInvested?: number; minRoi?: number; maxRoi?: number; minTrades?: number; minHolding?: number; market?: string; minLiquidity?: number; minMarketCap?: number; } interface PnlV2WalletChartParams { time_from?: number; time_to?: number; } interface PnlV2WalletOverviewParams { pnlMode?: PnlMode; } interface PnlV2WalletTokenPositionParams { pnlMode?: PnlMode; } interface PnlV2BatchParams { pnlMode?: PnlMode; } interface PnlV2KOLLeaderboardResponse { traders: PnlV2TraderWithIdentity[]; pagination: PnlV2Pagination; } interface PnlV2KOLPeriodResponse { traders: PnlV2PeriodTraderWithIdentity[]; pagination: PnlV2Pagination; } interface PnlV2KOLCalendarDayData { realizedPnl: number | null; volume: number | null; buys: number; sells: number; traders: number; } interface PnlV2KOLCalendarResponse { year: number; month: number; days: { [day: string]: PnlV2KOLCalendarDayData; }; summary: { tradingDays: number; positiveDays: number; negativeDays: number; totalRealizedPnl: number | null; totalVolume: number | null; }; } interface PnlV2KOLByDateResponse { traders: PnlV2DayTraderWithIdentity[]; summary: { totalRealizedPnl: number | null; totalVolume: number | null; }; date: string; } interface PnlV2TopTradersResponse { traders: PnlV2Top90dTrader[]; pagination: PnlV2Pagination; } interface PnlV2TokenTradersResponse { meta: PnlV2TokenMeta; traders: PnlV2Holder[]; pagination: PnlV2Pagination; } interface PnlV2WalletTokenPositionResponse extends PnlV2Position { wallet?: string; identity?: PnlV2Identity | null; pnlMode?: PnlMode; } interface PnlV2WalletHistoryResponse { wallet?: string; identity?: PnlV2Identity | null; days: PnlV2Snapshot[]; summary: { days: { trading: number; positive: number; negative: number; breakEven: number; }; totals: { realizedPnl: number | null; volume: number | null; }; winRate: number | null; totalDays: number; deltas: { realized: number | null; total: number | null; } | null; }; } interface PnlV2WalletPerformanceDay { date: string; realizedPnl: number | null; unrealizedPnl: number | null; totalPnl: number | null; volume: number | null; trades: number; } interface PnlV2WalletPerformanceResponse { wallet?: string; identity?: PnlV2Identity | null; window: number; totals: { realizedPnl: number | null; volume: number | null; trades: number; }; bestDay: { date: string; realizedPnl: number | null; volume: number | null; totalPnl: number | null; trades: number; } | null; worstDay: { date: string; realizedPnl: number | null; volume: number | null; totalPnl: number | null; trades: number; } | null; streaks: { positive: number | null; negative: number | null; currentPositive: number | null; currentNegative: number | null; }; drawdown: { amount: number | null; percent: number | null; }; days: PnlV2WalletPerformanceDay[]; updatedAt: string | null; } interface PnlV2WalletHighlightsResponse { wallet?: string; identity?: PnlV2Identity | null; counts: { positions: number; open: number; closed: number; }; highlights: { biggestWinner: PnlV2Position | null; biggestLoser: PnlV2Position | null; biggestBag: PnlV2Position | null; mostProfitableClosed: PnlV2Position | null; fastestFlip: PnlV2Position | null; longestHold: PnlV2Position | null; mostActive: PnlV2Position | null; }; updatedAt: string | null; } interface PnlV2WalletRiskResponse { wallet?: string; identity?: PnlV2Identity | null; openPositions: { count: number; cost: number | null; value: number | null; profitableValue: number | null; profitableValuePercent: number | null; }; concentration: { top1Percent: number | null; top5Percent: number | null; score: number | null; }; pnlMix: { realized: number | null; unrealized: number | null; realizedPercent: number | null; unrealizedPercent: number | null; }; largestPositions: PnlV2Position[]; updatedAt: string | null; } interface PnlV2WalletPositionsResponse { wallet?: string; identity?: PnlV2Identity | null; positions: PnlV2Position[]; stats: { total: number; filtered: number; holding: number; sold: number; profitable: number; losing: number; }; pagination: PnlV2Pagination; } interface PnlV2WalletChartResponse { wallet?: string; identity?: PnlV2Identity | null; points: PnlV2ChartPoint[]; summary: { days: { trading: number; positive: number; negative: number; breakEven: number; }; totals: { realizedPnl: number | null; volume: number | null; }; winRate: number | null; bestDay: { date: string; realizedPnl: number | null; } | null; worstDay: { date: string; realizedPnl: number | null; } | null; streaks: { positive: number; negative: number; currentPositive: number; currentNegative: number; }; drawdown: { amount: number | null; percent: number | null; }; averages: { dailyVolume: number | null; dailyRealizedPnl: number | null; holdTimeSecs: number | null; }; }; pagination: { count: number; hasMore: boolean; nextTimeTo: number | null; }; } interface PnlV2WalletOverviewResponse { wallet?: string; identity?: PnlV2Identity | null; pnlMode?: PnlMode; summary: PnlV2Summary; analysis: { winRate: number | null; avgPnlPerAsset: number | null; avgBuyValue: number | null; tokens: { closed: number; winning: number; losing: number; }; distribution: Array<{ range: string; count: number; rate: number | null; }>; }; stats: { total: number; holding: number; sold: number; profitable: number; losing: number; }; tags: { isArbitrage: boolean; platforms: string[]; }; updatedAt: string | null; } interface PnlV2BatchWalletPositionsResponse { wallet: string; identity?: PnlV2Identity | null; pnlMode?: PnlMode; count: number; positions: PnlV2Position[]; notFound: string[]; invalid?: string[]; } interface PnlV2BatchWalletSummary { wallet: string; identity?: PnlV2Identity | null; summary: PnlV2Summary; tags: { isArbitrage: boolean; platforms: string[]; }; updatedAt: string | number | null; } interface PnlV2BatchWalletSummariesResponse { count: number; wallets: PnlV2BatchWalletSummary[]; notFound?: string[]; invalid?: string[]; truncated?: { requested: number; limit: number; }; } interface PnlV2TokenScopedPositionWithWallet extends Omit<PnlV2Position, 'pnl'> { wallet: string; identity?: PnlV2Identity | null; pnl: PnlV2TokenScopedPnl; } interface PnlV2BatchTokenPositionsResponse { token: string; pnlMode?: PnlMode; count: number; positions: PnlV2TokenScopedPositionWithWallet[]; notFound: string[]; invalid?: string[]; } interface PnlV2BatchPositionPairsResponse { pnlMode?: PnlMode; count: number; positions: (PnlV2PositionWithWallet & { identity?: PnlV2Identity | null; })[]; notFound: Array<{ wallet: string; token: string; }>; invalid?: Array<{ wallet?: string; token?: string; }>; } interface ChartDataParams { /** Token address */ tokenAddress: string; /** Pool address (only for pool-specific charts) */ poolAddress?: string; /** Time interval (e.g., "1s", "1m", "1h", "1d") */ type?: string; /** Start time (Unix timestamp in seconds) */ timeFrom?: number; /** End time (Unix timestamp in seconds) */ timeTo?: number; /** Return chart for market cap instead of pricing */ marketCap?: boolean; /** Disable outlier removal if set to false (default: true) */ removeOutliers?: boolean; /** Dynamically picks the main pool over time for consistent charts (default: true, only applies without pool) */ dynamicPools?: boolean; /** Timezone for chart data - use "current" for auto-detection or specify timezone (e.g., "PST", "UTC", "America/New_York") */ timezone?: string | 'current'; /** Enable live cache for faster response times (default: false) */ fastCache?: boolean; /** Currency for price data (default: "usd") */ currency?: 'usd' | 'eur' | 'sol'; } /** * Represents a holder in the paginated response with account address */ interface PaginatedHolder { wallet: string; account: string; amount: number; value: TokenValuePair; percentage: number; } /** * Response for paginated token holders endpoint */ interface PaginatedTokenHoldersResponse { total: number; accounts: PaginatedHolder[]; cursor: string; hasMore: boolean; limit: number; } /** Status of a single DCA order. */ type DcaOrderStatus = 'active' | 'paused' | 'completed' | 'pending'; /** Status filter accepted by DCA list endpoints (adds `'all'`). */ type DcaOrderStatusFilter = DcaOrderStatus | 'all'; /** Trade direction relative to the wallet across its DCA orders. */ type DcaDirection = 'buying' | 'selling' | 'mixed'; /** Sort field accepted by DCA list endpoints. */ type DcaSort = 'volume' | 'deposited' | 'remaining' | 'progress' | 'recent' | 'created' | 'status'; /** A supported DCA program. */ interface DcaProgram { id: string; label: string; programId: string; } interface DcaProgramsResponse { programs: DcaProgram[]; } /** Token metadata embedded on a DCA order. */ interface DcaToken { mint: string; symbol: string; name: string; decimals: number; image?: string | null; uri?: string | null; description?: string | null; twitter?: string | null; website?: string | null; hasFileMetaData?: boolean; /** Current USD price; null/omitted when unavailable. */ priceUsd?: number | null; } /** Raw on-chain amounts (strings, base units). Keys depend on program. */ type DcaOrderRaw = Record<string, string>; /** A single DCA (recurring) order. */ interface DcaOrder { program: string; programId: string; /** DCA account pubkey. */ address: string; owner: string; status: DcaOrderStatus; direction: DcaDirection; /** Human readable pair, e.g. "USDC → SOL". */ pair: string; input: DcaToken; output: DcaToken; deposited: number; depositedUsd?: number | null; used: number; usedUsd?: number | null; remaining: number; remainingUsd?: number | null; received: number; receivedUsd?: number | null; perCycle: number; perCycleUsd?: number | null; /** Cycle frequency, e.g. "1h". */ frequency: string; progressPercent: number; volume: number; volumeUsd?: number | null; /** ISO 8601 timestamp. */ createdAt: string; /** ISO 8601 timestamp; null when no further cycle is scheduled. */ nextCycleAt: string | null; raw: DcaOrderRaw; } /** Status counts for a wallet's DCA orders. */ interface DcaSummary { total: number; active: number; paused: number; completed: number; pending: number; } /** Pagination block returned by paginated DCA endpoints. */ interface DcaPagination { limit: number; /** Cursor to pass as `cursor` for the next page; null when no more results. */ nextCursor: string | null; hasMore: boolean; count: number; total: number; } /** Common query parameters for DCA list endpoints. */ interface DcaListParams { /** DCA program id (default `"jupiter"`). */ program?: string; /** Alias for `program`. */ dex?: string; /** Alias for `program`. */ platform?: string; /** * Page size. Defaults differ by endpoint: * - wallet / wallet orders / pair: default `50`, max `100` * - token buyers / sellers / users: default `200`, max `1000` */ limit?: number; /** Opaque cursor (the previous page's last order `address`). */ cursor?: string; sort?: DcaSort; /** Alias for `sort`. */ sortBy?: DcaSort; status?: DcaOrderStatusFilter; } /** Query parameters accepted by single-order/program endpoints. */ interface DcaProgramParams { /** DCA program id (default `"jupiter"`). */ program?: string; /** Alias for `program`. */ dex?: string; /** Alias for `program`. */ platform?: string; } /** Standard error envelope returned by DCA endpoints on failure. */ interface DcaErrorResponse { error: { code: 'INVALID_WALLET' | 'INVALID_MINT' | 'INVALID_ORDER' | 'NOT_FOUND' | 'INVALID_SORT' | 'INVALID_STATUS' | 'INVALID_LIMIT' | 'INVALID_PROGRAM' | 'PROGRAM_PARAM_CONFLICT' | 'INVALID_CURSOR' | 'TIMEOUT' | 'SERVER_ERROR'; message: string; }; } interface DcaWalletResponse { wallet: string; summary: DcaSummary; orders: DcaOrder[]; pagination: DcaPagination;