Skip to content

leaderboards.categoryStats()

Get aggregated statistics for all categories on the platform.

Signature

leaderboards.categoryStats(): Promise<LeaderboardResponse<CategoryStats>>

Parameters

None - this method takes no parameters.

Returns

  • Type: Promise<LeaderboardResponse<CategoryStats>>
interface CategoryStats {
  category_id: string;
  category_name: string;
  category_description: string | null;
  category_icon_url: string | null;
  total_feeds: string;
  total_providers: string;
  total_entries: string;
  total_purchases: string;
  total_revenue: string;
  unique_buyers: string;
  avg_purchase_amount: string;
}

Usage

Basic Example

const stats = await grapevine.leaderboards.categoryStats();
 
stats.data.forEach(category => {
  console.log(`${category.category_name}:`);
  console.log(`  Feeds: ${category.total_feeds}`);
  console.log(`  Entries: ${category.total_entries}`);
  console.log(`  Revenue: ${formatUSDC(category.total_revenue)}`);
});
 
function formatUSDC(weiAmount: string): string {
  const usdc = Number(BigInt(weiAmount)) / 1e6;
  return `${usdc.toLocaleString('en-US', { minimumFractionDigits: 2 })}`;
}

Category Overview Dashboard

async function getCategoryOverview() {
  const stats = await grapevine.leaderboards.categoryStats();
  
  return stats.data.map(cat => ({
    id: cat.category_id,
    name: cat.category_name,
    description: cat.category_description,
    icon: cat.category_icon_url,
    metrics: {
      feeds: parseInt(cat.total_feeds),
      providers: parseInt(cat.total_providers),
      entries: parseInt(cat.total_entries),
      purchases: parseInt(cat.total_purchases),
      buyers: parseInt(cat.unique_buyers),
      revenue: formatUSDC(cat.total_revenue),
      avgPrice: formatUSDC(cat.avg_purchase_amount)
    }
  }));
}

Find Best Categories

async function getBestCategories() {
  const stats = await grapevine.leaderboards.categoryStats();
  
  // Sort by revenue
  const byRevenue = [...stats.data].sort(
    (a, b) => Number(BigInt(b.total_revenue) - BigInt(a.total_revenue))
  );
  
  // Sort by number of feeds
  const byFeeds = [...stats.data].sort(
    (a, b) => parseInt(b.total_feeds) - parseInt(a.total_feeds)
  );
  
  // Sort by average purchase price
  const byAvgPrice = [...stats.data].sort(
    (a, b) => Number(BigInt(b.avg_purchase_amount) - BigInt(a.avg_purchase_amount))
  );
  
  return {
    topRevenue: byRevenue.slice(0, 3).map(c => c.category_name),
    mostContent: byFeeds.slice(0, 3).map(c => c.category_name),
    highestPriced: byAvgPrice.slice(0, 3).map(c => c.category_name)
  };
}

Category Cards Grid

function CategoryStatsGrid() {
  const [categories, setCategories] = useState<CategoryStats[]>([]);
  
  useEffect(() => {
    grapevine.leaderboards.categoryStats()
      .then(result => setCategories(result.data));
  }, []);
  
  return (
    <div className="category-grid">
      {categories.map(cat => (
        <div key={cat.category_id} className="category-card">
          {cat.category_icon_url && (
            <img src={cat.category_icon_url} alt={cat.category_name} />
          )}
          
          <h3>{cat.category_name}</h3>
          {cat.category_description && (
            <p className="description">{cat.category_description}</p>
          )}
          
          <div className="stats">
            <div>
              <span className="value">{cat.total_feeds}</span>
              <span className="label">Feeds</span>
            </div>
            <div>
              <span className="value">{cat.total_entries}</span>
              <span className="label">Entries</span>
            </div>
            <div>
              <span className="value">{formatUSDC(cat.total_revenue)}</span>
              <span className="label">Revenue</span>
            </div>
            <div>
              <span className="value">{cat.total_providers}</span>
              <span className="label">Creators</span>
            </div>
          </div>
          
          <div className="avg-price">
            Avg. price: {formatUSDC(cat.avg_purchase_amount)}
          </div>
        </div>
      ))}
    </div>
  );
}

Category Comparison Chart

async function getCategoryChartData() {
  const stats = await grapevine.leaderboards.categoryStats();
  
  return {
    labels: stats.data.map(c => c.category_name),
    datasets: [
      {
        label: 'Total Revenue',
        data: stats.data.map(c => Number(BigInt(c.total_revenue)) / 1e6)
      },
      {
        label: 'Total Entries',
        data: stats.data.map(c => parseInt(c.total_entries))
      },
      {
        label: 'Unique Buyers',
        data: stats.data.map(c => parseInt(c.unique_buyers))
      }
    ]
  };
}

Platform Summary

async function getPlatformSummary() {
  const stats = await grapevine.leaderboards.categoryStats();
  
  const totals = stats.data.reduce((acc, cat) => ({
    feeds: acc.feeds + parseInt(cat.total_feeds),
    entries: acc.entries + parseInt(cat.total_entries),
    providers: acc.providers + parseInt(cat.total_providers),
    purchases: acc.purchases + parseInt(cat.total_purchases),
    buyers: acc.buyers + parseInt(cat.unique_buyers),
    revenue: acc.revenue + BigInt(cat.total_revenue)
  }), {
    feeds: 0,
    entries: 0,
    providers: 0,
    purchases: 0,
    buyers: 0,
    revenue: BigInt(0)
  });
  
  return {
    categories: stats.data.length,
    totalFeeds: totals.feeds,
    totalEntries: totals.entries,
    totalProviders: totals.providers,
    totalPurchases: totals.purchases,
    uniqueBuyers: totals.buyers,
    totalRevenue: formatUSDC(totals.revenue.toString())
  };
}

Stats Fields

FieldDescription
total_feedsNumber of feeds in this category
total_providersUnique content creators in this category
total_entriesTotal entries across all feeds
total_purchasesTotal purchase transactions
total_revenueTotal revenue generated (in wei)
unique_buyersUnique buyers in this category
avg_purchase_amountAverage transaction amount (in wei)

Notes

  • Authentication: Not required - public endpoint
  • Caching: Results may be cached for performance
  • Currency: All amounts are in wei (USDC has 6 decimals)

Related