> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Trading Stats

> Get comprehensive trading statistics for a user

## Overview

Retrieve detailed trading statistics and performance metrics for a specific user. This endpoint provides insights into trading volume, profitability, frequency, and protocol usage, making it perfect for building trading dashboards and analytics.

<Tip>
  Use this endpoint to display user trading performance, calculate risk scores, and provide insights into trading behavior patterns.
</Tip>

## Parameters

<ParamField path="identity" type="string" required>
  User identity (ZKS ID or wallet address)

  <Note>
    ZKS ID is recommended for better performance and user experience
  </Note>
</ParamField>

<ParamField query="timeframe" type="string">
  Time period for statistics

  * `7d` - Last 7 days
  * `30d` - Last 30 days (default)
  * `90d` - Last 90 days
  * `1y` - Last year
  * `all` - All time
</ParamField>

<ParamField query="chainId" type="number">
  Filter by specific blockchain

  * `1` - Ethereum mainnet
  * `137` - Polygon
  * `56` - BSC
  * `42161` - Arbitrum
  * `10` - Optimism
  * `250` - Fantom
  * `43114` - Avalanche
</ParamField>

<ParamField query="includeBreakdown" type="boolean">
  Include detailed breakdown by protocol and asset (default: true)
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="address" type="string">
  Resolved wallet address
</ResponseField>

<ResponseField name="zksId" type="string">
  ZKS ID if available, null otherwise
</ResponseField>

<ResponseField name="zksTradingStats" type="object">
  Comprehensive trading statistics

  <Expandable title="zksTradingStats properties">
    <ResponseField name="overview" type="object">
      High-level trading overview

      <Expandable title="overview properties">
        <ResponseField name="totalVolume" type="string">
          Total trading volume in USD
        </ResponseField>

        <ResponseField name="totalTrades" type="number">
          Total number of trades
        </ResponseField>

        <ResponseField name="uniqueProtocols" type="number">
          Number of unique protocols traded on
        </ResponseField>

        <ResponseField name="uniqueAssets" type="number">
          Number of unique assets traded
        </ResponseField>

        <ResponseField name="activeDays" type="number">
          Number of days with trading activity
        </ResponseField>

        <ResponseField name="firstTrade" type="string">
          ISO 8601 timestamp of first trade
        </ResponseField>

        <ResponseField name="lastTrade" type="string">
          ISO 8601 timestamp of most recent trade
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="profitability" type="object">
      Profit and loss metrics

      <Expandable title="profitability properties">
        <ResponseField name="totalPnL" type="string">
          Total profit/loss in USD
        </ResponseField>

        <ResponseField name="realizedPnL" type="string">
          Realized profit/loss in USD
        </ResponseField>

        <ResponseField name="unrealizedPnL" type="string">
          Unrealized profit/loss in USD
        </ResponseField>

        <ResponseField name="winRate" type="number">
          Percentage of profitable trades (0-100)
        </ResponseField>

        <ResponseField name="averageWin" type="string">
          Average profit per winning trade
        </ResponseField>

        <ResponseField name="averageLoss" type="string">
          Average loss per losing trade
        </ResponseField>

        <ResponseField name="profitFactor" type="number">
          Ratio of gross profit to gross loss
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="volume" type="object">
      Volume and frequency metrics

      <Expandable title="volume properties">
        <ResponseField name="dailyAverage" type="string">
          Average daily trading volume
        </ResponseField>

        <ResponseField name="weeklyAverage" type="string">
          Average weekly trading volume
        </ResponseField>

        <ResponseField name="monthlyAverage" type="string">
          Average monthly trading volume
        </ResponseField>

        <ResponseField name="largestTrade" type="string">
          Largest single trade value
        </ResponseField>

        <ResponseField name="tradesPerDay" type="number">
          Average trades per day
        </ResponseField>

        <ResponseField name="volumeGrowth" type="number">
          Volume growth percentage over timeframe
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="risk" type="object">
      Risk assessment metrics

      <Expandable title="risk properties">
        <ResponseField name="maxDrawdown" type="string">
          Maximum drawdown in USD
        </ResponseField>

        <ResponseField name="maxDrawdownPercentage" type="number">
          Maximum drawdown as percentage
        </ResponseField>

        <ResponseField name="volatility" type="number">
          Trading volatility score (0-100)
        </ResponseField>

        <ResponseField name="riskScore" type="number">
          Overall risk score (0-100)
        </ResponseField>

        <ResponseField name="consecutiveLosses" type="number">
          Maximum consecutive losing trades
        </ResponseField>

        <ResponseField name="consecutiveWins" type="number">
          Maximum consecutive winning trades
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="protocols" type="array">
      Trading activity by protocol

      <Expandable title="protocol properties">
        <ResponseField name="name" type="string">
          Protocol name
        </ResponseField>

        <ResponseField name="volume" type="string">
          Volume on this protocol
        </ResponseField>

        <ResponseField name="trades" type="number">
          Number of trades on this protocol
        </ResponseField>

        <ResponseField name="pnl" type="string">
          P\&L on this protocol
        </ResponseField>

        <ResponseField name="percentage" type="number">
          Percentage of total volume
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="assets" type="array">
      Trading activity by asset

      <Expandable title="asset properties">
        <ResponseField name="symbol" type="string">
          Asset symbol
        </ResponseField>

        <ResponseField name="name" type="string">
          Asset name
        </ResponseField>

        <ResponseField name="volume" type="string">
          Volume of this asset
        </ResponseField>

        <ResponseField name="trades" type="number">
          Number of trades of this asset
        </ResponseField>

        <ResponseField name="pnl" type="string">
          P\&L from this asset
        </ResponseField>

        <ResponseField name="percentage" type="number">
          Percentage of total volume
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="timeDistribution" type="object">
      Trading activity by time periods

      <Expandable title="timeDistribution properties">
        <ResponseField name="byHour" type="array">
          Trading activity by hour of day
        </ResponseField>

        <ResponseField name="byDay" type="array">
          Trading activity by day of week
        </ResponseField>

        <ResponseField name="byMonth" type="array">
          Trading activity by month
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of the response
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL (Basic Stats) theme={null}
  curl "https://api.onzks.com/v1/trading/stats/alice.zks" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (Last 30 Days) theme={null}
  curl "https://api.onzks.com/v1/trading/stats/alice.zks?timeframe=30d" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (Ethereum Only) theme={null}
  curl "https://api.onzks.com/v1/trading/stats/alice.zks?chainId=1&timeframe=90d" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (Wallet Address) theme={null}
  curl "https://api.onzks.com/v1/trading/stats/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  async function getTradingStats(identity, options = {}) {
    const {
      timeframe = '30d',
      chainId,
      includeBreakdown = true
    } = options;

    const params = new URLSearchParams({
      timeframe,
      includeBreakdown: includeBreakdown.toString()
    });

    if (chainId) params.append('chainId', chainId.toString());

    const response = await fetch(
      `https://api.onzks.com/v1/trading/stats/${identity}?${params}`,
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY'
        }
      }
    );

    const data = await response.json();

    console.log(`Trading Stats for ${data.zksId || data.address}:`);
    console.log(`Total Volume: $${parseFloat(data.zksTradingStats.overview.totalVolume).toLocaleString()}`);
    console.log(`Total Trades: ${data.zksTradingStats.overview.totalTrades}`);
    console.log(`Win Rate: ${data.zksTradingStats.profitability.winRate}%`);
    console.log(`Total P&L: $${parseFloat(data.zksTradingStats.profitability.totalPnL).toLocaleString()}`);

    return data;
  }

  // Usage examples
  await getTradingStats('alice.zks');
  await getTradingStats('alice.zks', { timeframe: '90d', chainId: 1 });
  await getTradingStats('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb');
  ```

  ```python Python theme={null}
  import requests

  def get_trading_stats(identity, timeframe='30d', chain_id=None, include_breakdown=True):
      params = {
          'timeframe': timeframe,
          'includeBreakdown': include_breakdown
      }
      
      if chain_id:
          params['chainId'] = chain_id
      
      response = requests.get(
          f'https://api.onzks.com/v1/trading/stats/{identity}',
          headers={'Authorization': 'Bearer YOUR_API_KEY'},
          params=params
      )
      
      data = response.json()
      
      print(f"Trading Stats for {data.get('zksId', data['address'])}:")
      print(f"Total Volume: ${float(data['zksTradingStats']['overview']['totalVolume']):,.2f}")
      print(f"Total Trades: {data['zksTradingStats']['overview']['totalTrades']}")
      print(f"Win Rate: {data['zksTradingStats']['profitability']['winRate']}%")
      print(f"Total P&L: ${float(data['zksTradingStats']['profitability']['totalPnL']):,.2f}")
      
      return data

  # Usage examples
  get_trading_stats('alice.zks')
  get_trading_stats('alice.zks', timeframe='90d', chain_id=1)
  get_trading_stats('0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb')
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "success": true,
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
  "zksId": "alice.zks",
  "zksTradingStats": {
    "overview": {
      "totalVolume": "1250000.50",
      "totalTrades": 342,
      "uniqueProtocols": 15,
      "uniqueAssets": 28,
      "activeDays": 45,
      "firstTrade": "2023-06-15T10:30:00Z",
      "lastTrade": "2024-01-20T15:45:00Z"
    },
    "profitability": {
      "totalPnL": "125000.75",
      "realizedPnL": "98000.25",
      "unrealizedPnL": "27000.50",
      "winRate": 68.5,
      "averageWin": "2500.00",
      "averageLoss": "-1200.00",
      "profitFactor": 2.1
    },
    "volume": {
      "dailyAverage": "27777.78",
      "weeklyAverage": "194444.44",
      "monthlyAverage": "833333.33",
      "largestTrade": "50000.00",
      "tradesPerDay": 7.6,
      "volumeGrowth": 15.2
    },
    "risk": {
      "maxDrawdown": "-15000.00",
      "maxDrawdownPercentage": 12.0,
      "volatility": 35.5,
      "riskScore": 42.3,
      "consecutiveLosses": 4,
      "consecutiveWins": 8
    },
    "protocols": [
      {
        "name": "Uniswap V3",
        "volume": "450000.00",
        "trades": 125,
        "pnl": "45000.00",
        "percentage": 36.0
      },
      {
        "name": "1inch",
        "volume": "300000.00",
        "trades": 89,
        "pnl": "25000.00",
        "percentage": 24.0
      },
      {
        "name": "SushiSwap",
        "volume": "200000.00",
        "trades": 67,
        "pnl": "18000.00",
        "percentage": 16.0
      }
    ],
    "assets": [
      {
        "symbol": "ETH",
        "name": "Ethereum",
        "volume": "500000.00",
        "trades": 150,
        "pnl": "50000.00",
        "percentage": 40.0
      },
      {
        "symbol": "USDC",
        "name": "USD Coin",
        "volume": "300000.00",
        "trades": 100,
        "pnl": "25000.00",
        "percentage": 24.0
      },
      {
        "symbol": "WBTC",
        "name": "Wrapped Bitcoin",
        "volume": "200000.00",
        "trades": 50,
        "pnl": "20000.00",
        "percentage": 16.0
      }
    ],
    "timeDistribution": {
      "byHour": [
        {"hour": 0, "trades": 5, "volume": "10000.00"},
        {"hour": 1, "trades": 3, "volume": "5000.00"},
        {"hour": 9, "trades": 25, "volume": "50000.00"},
        {"hour": 14, "trades": 30, "volume": "60000.00"},
        {"hour": 21, "trades": 20, "volume": "40000.00"}
      ],
      "byDay": [
        {"day": "Monday", "trades": 50, "volume": "100000.00"},
        {"day": "Tuesday", "trades": 45, "volume": "90000.00"},
        {"day": "Wednesday", "trades": 55, "volume": "110000.00"},
        {"day": "Thursday", "trades": 48, "volume": "95000.00"},
        {"day": "Friday", "trades": 52, "volume": "105000.00"},
        {"day": "Saturday", "trades": 35, "volume": "70000.00"},
        {"day": "Sunday", "trades": 30, "volume": "60000.00"}
      ],
      "byMonth": [
        {"month": "2023-06", "trades": 25, "volume": "50000.00"},
        {"month": "2023-07", "trades": 30, "volume": "60000.00"},
        {"month": "2023-08", "trades": 35, "volume": "70000.00"},
        {"month": "2023-09", "trades": 40, "volume": "80000.00"},
        {"month": "2023-10", "trades": 45, "volume": "90000.00"},
        {"month": "2023-11", "trades": 50, "volume": "100000.00"},
        {"month": "2023-12", "trades": 55, "volume": "110000.00"},
        {"month": "2024-01", "trades": 60, "volume": "120000.00"}
      ]
    }
  },
  "timestamp": "2024-01-20T15:45:00Z"
}
```

## Use Cases

### 1. Trading Dashboard

Create a comprehensive trading dashboard:

```javascript theme={null}
function createTradingDashboard(stats) {
  const { overview, profitability, volume, risk } = stats.zksTradingStats;
  
  return {
    summary: {
      totalVolume: `$${parseFloat(overview.totalVolume).toLocaleString()}`,
      totalTrades: overview.totalTrades,
      winRate: `${profitability.winRate}%`,
      totalPnL: `$${parseFloat(profitability.totalPnL).toLocaleString()}`,
      riskScore: risk.riskScore
    },
    performance: {
      profitFactor: profitability.profitFactor,
      averageWin: `$${parseFloat(profitability.averageWin).toLocaleString()}`,
      averageLoss: `$${parseFloat(profitability.averageLoss).toLocaleString()}`,
      maxDrawdown: `$${parseFloat(risk.maxDrawdown).toLocaleString()}`
    },
    activity: {
      dailyAverage: `$${parseFloat(volume.dailyAverage).toLocaleString()}`,
      tradesPerDay: volume.tradesPerDay,
      activeDays: overview.activeDays,
      uniqueProtocols: overview.uniqueProtocols
    }
  };
}
```

### 2. Risk Assessment

Analyze trading risk:

```javascript theme={null}
function assessTradingRisk(stats) {
  const { risk, profitability } = stats.zksTradingStats;
  
  const riskLevel = risk.riskScore < 30 ? 'Low' :
                   risk.riskScore < 60 ? 'Medium' : 'High';
  
  const riskFactors = [];
  
  if (risk.maxDrawdownPercentage > 20) {
    riskFactors.push('High maximum drawdown');
  }
  
  if (risk.consecutiveLosses > 5) {
    riskFactors.push('Long losing streaks');
  }
  
  if (profitability.winRate < 50) {
    riskFactors.push('Low win rate');
  }
  
  if (risk.volatility > 70) {
    riskFactors.push('High volatility');
  }
  
  return {
    riskLevel,
    riskScore: risk.riskScore,
    riskFactors,
    recommendations: generateRiskRecommendations(risk, profitability)
  };
}

function generateRiskRecommendations(risk, profitability) {
  const recommendations = [];
  
  if (risk.maxDrawdownPercentage > 15) {
    recommendations.push('Consider reducing position sizes');
  }
  
  if (profitability.winRate < 60) {
    recommendations.push('Focus on improving trade selection');
  }
  
  if (risk.consecutiveLosses > 3) {
    recommendations.push('Implement stop-loss strategies');
  }
  
  return recommendations;
}
```

### 3. Protocol Analysis

Analyze trading by protocol:

```javascript theme={null}
function analyzeProtocols(stats) {
  const protocols = stats.zksTradingStats.protocols;
  
  const analysis = {
    topProtocol: protocols[0],
    totalProtocols: protocols.length,
    diversification: calculateDiversification(protocols),
    protocolPerformance: protocols.map(p => ({
      name: p.name,
      efficiency: parseFloat(p.pnl) / parseFloat(p.volume) * 100,
      volume: parseFloat(p.volume),
      trades: p.trades
    }))
  };
  
  return analysis;
}

function calculateDiversification(protocols) {
  const totalVolume = protocols.reduce((sum, p) => sum + parseFloat(p.volume), 0);
  const top3Volume = protocols.slice(0, 3).reduce((sum, p) => sum + parseFloat(p.volume), 0);
  
  return (top3Volume / totalVolume * 100).toFixed(1);
}
```

### 4. Time-based Analysis

Analyze trading patterns over time:

```javascript theme={null}
function analyzeTradingPatterns(stats) {
  const { timeDistribution } = stats.zksTradingStats;
  
  const patterns = {
    peakHours: findPeakHours(timeDistribution.byHour),
    peakDays: findPeakDays(timeDistribution.byDay),
    monthlyTrend: analyzeMonthlyTrend(timeDistribution.byMonth),
    consistency: calculateConsistency(timeDistribution)
  };
  
  return patterns;
}

function findPeakHours(hourlyData) {
  return hourlyData
    .sort((a, b) => b.trades - a.trades)
    .slice(0, 3)
    .map(h => ({ hour: h.hour, trades: h.trades }));
}

function findPeakDays(dailyData) {
  return dailyData
    .sort((a, b) => b.trades - a.trades)
    .slice(0, 3)
    .map(d => ({ day: d.day, trades: d.trades }));
}
```

### 5. Performance Comparison

Compare with market benchmarks:

```javascript theme={null}
function compareWithBenchmarks(stats) {
  const { profitability, volume } = stats.zksTradingStats;
  
  const benchmarks = {
    averageWinRate: 55, // Market average
    averageProfitFactor: 1.5,
    averageVolatility: 50
  };
  
  const comparison = {
    winRate: {
      value: profitability.winRate,
      benchmark: benchmarks.averageWinRate,
      performance: profitability.winRate > benchmarks.averageWinRate ? 'Above' : 'Below'
    },
    profitFactor: {
      value: profitability.profitFactor,
      benchmark: benchmarks.averageProfitFactor,
      performance: profitability.profitFactor > benchmarks.averageProfitFactor ? 'Above' : 'Below'
    },
    overall: calculateOverallPerformance(profitability, benchmarks)
  };
  
  return comparison;
}
```

## Best Practices

### 1. Cache Trading Stats

Trading stats can be cached for short periods:

```javascript theme={null}
let tradingStatsCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedTradingStats(identity, options = {}) {
  const cacheKey = `${identity}-${JSON.stringify(options)}`;
  const cached = tradingStatsCache.get(cacheKey);
  
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const data = await getTradingStats(identity, options);
  tradingStatsCache.set(cacheKey, {
    data,
    timestamp: Date.now()
  });
  
  return data;
}
```

### 2. Real-time Updates

Subscribe to trading updates:

```javascript theme={null}
function subscribeToTradingUpdates(identity, callback) {
  const ws = new WebSocket(`wss://api.onzks.com/v1/trading/stats/${identity}/subscribe`);
  
  ws.onmessage = (event) => {
    const update = JSON.parse(event.data);
    callback(update);
  };
  
  return () => ws.close();
}
```

### 3. Batch Analysis

Analyze multiple users:

```javascript theme={null}
async function analyzeMultipleTraders(identities) {
  const promises = identities.map(id => getTradingStats(id));
  const results = await Promise.all(promises);
  
  return results.map((stats, index) => ({
    identity: identities[index],
    stats: stats.zksTradingStats,
    risk: assessTradingRisk(stats),
    performance: compareWithBenchmarks(stats)
  }));
}
```

### 4. Historical Comparison

Compare different time periods:

```javascript theme={null}
async function compareTimePeriods(identity) {
  const [current, previous] = await Promise.all([
    getTradingStats(identity, { timeframe: '30d' }),
    getTradingStats(identity, { timeframe: '60d' })
  ]);
  
  return {
    current: current.zksTradingStats,
    previous: previous.zksTradingStats,
    changes: calculateChanges(current.zksTradingStats, previous.zksTradingStats)
  };
}
```

## Related Endpoints

* [Get Trading History](/api-reference/trading/get-history) - Detailed trade history
* [Get Trading Leaderboard](/api-reference/trading/get-leaderboard) - Top traders
* [Get Score](/api-reference/scores/get-score) - Overall ZKScore

## Troubleshooting

### "No trading data found"

**Cause**: User has no trading activity or invalid timeframe.

**Solution**:

* Check if the user has any trading activity
* Try a longer timeframe
* Verify the identity is correct

### "Invalid timeframe"

**Cause**: Unsupported timeframe value.

**Solution**:

* Use supported timeframes: `7d`, `30d`, `90d`, `1y`, `all`
* Check for typos

### "Chain not supported"

**Cause**: Unsupported chain ID.

**Solution**:

* Use supported chain IDs: 1, 137, 56, 42161, 10, 250, 43114
* Check chain ID format

## Rate Limits

Trading stats requests are subject to rate limits:

* **Free tier**: 60 requests per minute
* **Starter tier**: 300 requests per minute
* **Professional tier**: 1,000 requests per minute
* **Enterprise tier**: Custom limits

Implement caching to reduce API calls.