Skip to main content

​
useTradingStats

Get trading statistics for an address. 
import { useTradingStats } from '@zkscore/react';

function TradingStats({ address }: { address: string }) {
  const { stats, loading, error } = useTradingStats(address);

  if (loading) return <div>Loading stats...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!stats) return <div>No trading data</div>;

  return (
    <div className="trading-stats">
      <div className="stat-card">
        <h3>Total Volume</h3>
        <p>${parseFloat(stats.totalVolume).toLocaleString()}</p>
      </div>
      <div className="stat-card">
        <h3>Total Trades</h3>
        <p>{stats.totalTrades.toLocaleString()}</p>
      </div>
      <div className="stat-card">
        <h3>Win Rate</h3>
        <p>{(stats.winRate * 100).toFixed(1)}%</p>
      </div>
      <div className="stat-card">
        <h3>P&L</h3>
        <p className={stats.profitLoss.startsWith('+') ? 'profit' : 'loss'}>
          {stats.profitLoss}
        </p>
      </div>
    </div>
  );
}

​
Parameters

​
address
string
required
Ethereum address to query
​
options
object
Query options

​
useTradingHistory

Get trading history with pagination. 
import { useTradingHistory } from '@zkscore/react';
import { useState } from 'react';

function TradingHistory({ address }: { address: string }) {
  const [page, setPage] = useState(0);
  const { history, loading, pagination } = useTradingHistory(address, {
    limit: 20,
    offset: page * 20,
  });

  if (loading) return <div>Loading trades...</div>;

  return (
    <div className="trading-history">
      <table>
        <thead>
          <tr>
            <th>Date</th>
            <th>Type</th>
            <th>From</th>
            <th>To</th>
            <th>Value</th>
            <th>DEX</th>
          </tr>
        </thead>
        <tbody>
          {history?.trades.map((trade) => (
            <tr key={trade.txHash}>
              <td>{new Date(trade.timestamp).toLocaleDateString()}</td>
              <td>{trade.type}</td>
              <td>{trade.tokenIn.symbol}</td>
              <td>{trade.tokenOut.symbol}</td>
              <td>${trade.tokenIn.valueUsd}</td>
              <td>{trade.dex}</td>
            </tr>
          ))}
        </tbody>
      </table>
      
      {pagination && (
        <div className="pagination">
          <button 
            onClick={() => setPage(p => Math.max(0, p - 1))}
            disabled={page === 0}
          >
            Previous
          </button>
          <span>Page {page + 1}</span>
          <button 
            onClick={() => setPage(p => p + 1)}
            disabled={!pagination.hasMore}
          >
            Next
          </button>
        </div>
      )}
    </div>
  );
}

​
useTradingLeaderboard

Get the trading leaderboard. 
import { useTradingLeaderboard } from '@zkscore/react';

function TradingLeaderboard() {
  const { leaders, loading, userRank } = useTradingLeaderboard({
    metric: 'volume',
    timeRange: '30d',
    limit: 100,
  });

  if (loading) return <div>Loading leaderboard...</div>;

  return (
    <div className="leaderboard">
      {userRank && (
        <div className="user-rank">
          Your Rank: #{userRank.rank} (${userRank.value})
        </div>
      )}
      
      <table>
        <thead>
          <tr>
            <th>Rank</th>
            <th>Trader</th>
            <th>Volume</th>
            <th>24h Change</th>
          </tr>
        </thead>
        <tbody>
          {leaders?.map((leader) => (
            <tr key={leader.address}>
              <td>{leader.rank}</td>
              <td>{leader.username || leader.address.slice(0, 8)}</td>
              <td>${parseFloat(leader.value).toLocaleString()}</td>
              <td className={leader.change24h > 0 ? 'up' : 'down'}>
                {leader.change24h > 0 ? '+' : ''}{leader.change24h.toFixed(2)}%
              </td>
            </tr>
          ))}
        </tbody>
      </table>
    </div>
  );
}

​
useTokenStats

Get trading stats for a specific token. 
import { useTokenStats } from '@zkscore/react';

function TokenStats({ address, tokenSymbol }: Props) {
  const { stats, loading } = useTokenStats(address, tokenSymbol);

  if (loading) return <div>Loading token stats...</div>;
  if (!stats) return null;

  return (
    <div className="token-stats">
      <h3>{tokenSymbol} Trading Stats</h3>
      <div className="stats-grid">
        <div>
          <label>Trades</label>
          <span>{stats.trades}</span>
        </div>
        <div>
          <label>Volume</label>
          <span>${stats.volume}</span>
        </div>
        <div>
          <label>Net Position</label>
          <span className={stats.netPosition.startsWith('+') ? 'positive' : 'negative'}>
            {stats.netPosition} {tokenSymbol}
          </span>
        </div>
        <div>
          <label>Realized P&L</label>
          <span className={stats.realizedPnL.startsWith('+') ? 'profit' : 'loss'}>
            {stats.realizedPnL}
          </span>
        </div>
      </div>
    </div>
  );
}

​
Advanced Examples

​
Trading Dashboard

import { useTradingStats, useTradingHistory, useTradingLeaderboard } from '@zkscore/react';

function TradingDashboard({ address }: { address: string }) {
  const { stats } = useTradingStats(address, { timeRange: '30d' });
  const { history } = useTradingHistory(address, { limit: 5 });
  const { userRank } = useTradingLeaderboard({
    metric: 'volume',
    timeRange: '30d',
    userAddress: address,
  });

  return (
    <div className="dashboard">
      <div className="overview">
        <h2>Trading Overview (30d)</h2>
        <div className="stats-grid">
          <StatCard label="Volume" value={`$${stats?.totalVolume || 0}`} />
          <StatCard label="Trades" value={stats?.totalTrades || 0} />
          <StatCard label="Win Rate" value={`${((stats?.winRate || 0) * 100).toFixed(1)}%`} />
          <StatCard label="Rank" value={`#${userRank?.rank || '-'}`} />
        </div>
      </div>

      <div className="recent-trades">
        <h3>Recent Trades</h3>
        <TradesList trades={history?.trades || []} />
      </div>

      <div className="top-tokens">
        <h3>Top Tokens</h3>
        <TokensList tokens={stats?.topTokens || []} />
      </div>
    </div>
  );
}

​
Real-Time Trading Monitor

import { useTradingHistory } from '@zkscore/react';
import { useEffect, useState } from 'react';

function RealTimeTrades({ address }: { address: string }) {
  const { history, refetch } = useTradingHistory(address, {
    limit: 10,
    refreshInterval: 30000, // Poll every 30 seconds
  });

  return (
    <div className="real-time-trades">
      <div className="header">
        <h3>Recent Trades</h3>
        <span className="live-indicator">● LIVE</span>
      </div>
      
      {history?.trades.map((trade) => (
        <div key={trade.txHash} className="trade-item">
          <span className="time">
            {new Date(trade.timestamp).toLocaleTimeString()}
          </span>
          <span className="swap">
            {trade.tokenIn.amount} {trade.tokenIn.symbol} → {trade.tokenOut.amount} {trade.tokenOut.symbol}
          </span>
          <span className="value">${trade.tokenIn.valueUsd}</span>
        </div>
      ))}
    </div>
  );
}

​
Performance Metrics

import { useTradingStats } from '@zkscore/react';

function PerformanceMetrics({ address }: { address: string }) {
  const timeRanges = ['7d', '30d', '90d', '1y'] as const;
  
  return (
    <div className="performance-metrics">
      <h2>Performance Over Time</h2>
      <table>
        <thead>
          <tr>
            <th>Period</th>
            <th>Volume</th>
            <th>Trades</th>
            <th>Win Rate</th>
            <th>P&L</th>
          </tr>
        </thead>
        <tbody>
          {timeRanges.map((range) => (
            <PerformanceRow key={range} address={address} timeRange={range} />
          ))}
        </tbody>
      </table>
    </div>
  );
}

function PerformanceRow({ address, timeRange }: Props) {
  const { stats } = useTradingStats(address, { timeRange });

  return (
    <tr>
      <td>{timeRange}</td>
      <td>${stats?.totalVolume || 0}</td>
      <td>{stats?.totalTrades || 0}</td>
      <td>{((stats?.winRate || 0) * 100).toFixed(1)}%</td>
      <td className={stats?.profitLoss.startsWith('+') ? 'profit' : 'loss'}>
        {stats?.profitLoss || '$0'}
      </td>
    </tr>
  );
}

​
TypeScript Types

interface TradingStats {
  address: string;
  totalTrades: number;
  totalVolume: string;
  uniqueTokens: number;
  uniqueDexs: number;
  winRate: number;
  profitLoss: string;
  topTokens: TokenStats[];
  topDexs: DexStats[];
}

interface Trade {
  txHash: string;
  timestamp: string;
  dex: string;
  type: 'swap' | 'add_liquidity' | 'remove_liquidity';
  tokenIn: TokenAmount;
  tokenOut: TokenAmount;
  gasUsed: string;
  profit?: string;
  status: 'success' | 'failed';
}

interface TradingHistory {
  trades: Trade[];
  pagination: {
    total: number;
    limit: number;
    offset: number;
    hasMore: boolean;
  };
}

​
Next Steps

Components

Pre-built React components

Examples

Complete examples

Trading API

Trading API reference

Trading Use Case

Trading integration guide