@solana-tracker/data-api
Version:
Official Solana Tracker Data API client for accessing Solana Data
1,979 lines (1,977 loc) • 112 kB
text/typescript
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;