Get Trading Leaderboard
curl --request GET \
--url https://api-mainnet.onzks.com/v1/trading/leaderboard \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-mainnet.onzks.com/v1/trading/leaderboard"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-mainnet.onzks.com/v1/trading/leaderboard', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-mainnet.onzks.com/v1/trading/leaderboard",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-mainnet.onzks.com/v1/trading/leaderboard"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-mainnet.onzks.com/v1/trading/leaderboard")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-mainnet.onzks.com/v1/trading/leaderboard")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"leaderboard": [
{
"rank": 123,
"address": "<string>",
"zksId": "<string>",
"score": 123,
"value": "<string>",
"change": {
"position": 123,
"direction": "<string>",
"percentage": 123
},
"stats": {
"totalVolume": "<string>",
"totalTrades": 123,
"winRate": 123,
"totalPnL": "<string>",
"averageTrade": "<string>",
"uniqueProtocols": 123,
"uniqueAssets": 123,
"riskScore": 123,
"consistency": 123
},
"badges": [
{
"id": "<string>",
"name": "<string>",
"icon": "<string>",
"rarity": "<string>"
}
]
}
],
"pagination": {
"total": 123,
"limit": 123,
"offset": 123,
"hasMore": true
},
"metadata": {
"metric": "<string>",
"timeframe": "<string>",
"lastUpdated": "<string>",
"totalTraders": 123,
"averageScore": 123,
"topScore": 123
},
"timestamp": "<string>"
}Trading
Get Trading Leaderboard
Get ranked list of top traders by various metrics
GET
/
v1
/
trading
/
leaderboard
Get Trading Leaderboard
curl --request GET \
--url https://api-mainnet.onzks.com/v1/trading/leaderboard \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-mainnet.onzks.com/v1/trading/leaderboard"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api-mainnet.onzks.com/v1/trading/leaderboard', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api-mainnet.onzks.com/v1/trading/leaderboard",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api-mainnet.onzks.com/v1/trading/leaderboard"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api-mainnet.onzks.com/v1/trading/leaderboard")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-mainnet.onzks.com/v1/trading/leaderboard")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"success": true,
"leaderboard": [
{
"rank": 123,
"address": "<string>",
"zksId": "<string>",
"score": 123,
"value": "<string>",
"change": {
"position": 123,
"direction": "<string>",
"percentage": 123
},
"stats": {
"totalVolume": "<string>",
"totalTrades": 123,
"winRate": 123,
"totalPnL": "<string>",
"averageTrade": "<string>",
"uniqueProtocols": 123,
"uniqueAssets": 123,
"riskScore": 123,
"consistency": 123
},
"badges": [
{
"id": "<string>",
"name": "<string>",
"icon": "<string>",
"rarity": "<string>"
}
]
}
],
"pagination": {
"total": 123,
"limit": 123,
"offset": 123,
"hasMore": true
},
"metadata": {
"metric": "<string>",
"timeframe": "<string>",
"lastUpdated": "<string>",
"totalTraders": 123,
"averageScore": 123,
"topScore": 123
},
"timestamp": "<string>"
}Overview
Retrieve ranked leaderboards of top traders based on different performance metrics. This endpoint provides competitive rankings perfect for building leaderboards, competitions, and showcasing top performers.Use this endpoint to display top traders, create competitions, and motivate users to improve their trading performance through gamification.
Parameters
string
Ranking metric
volume- Total trading volume (default)profit- Total profit/losswinRate- Win rate percentagetrades- Number of tradesefficiency- Profit per volume ratioconsistency- Consistency scoreriskAdjusted- Risk-adjusted returns
string
Time period for rankings
7d- Last 7 days30d- Last 30 days (default)90d- Last 90 days1y- Last yearall- All time
number
Filter by specific blockchain
1- Ethereum mainnet137- Polygon56- BSC42161- Arbitrum10- Optimism250- Fantom43114- Avalanche
string
Filter by specific protocol
uniswap- Uniswapsushiswap- SushiSwap1inch- 1inchcurve- Curvebalancer- Balancerpancakeswap- PancakeSwap
string
Trader category
all- All traders (default)whale- High volume tradersretail- Retail tradersprofessional- Professional tradersinstitutional- Institutional traders
number
Number of traders to return (default: 100, max: 1000)
number
Number of traders to skip for pagination (default: 0)
boolean
Include detailed statistics for each trader (default: true)
boolean
Include ranking information (default: true)
Response
boolean
Indicates if the request was successful
array
Array of ranked traders
Show trader properties
Show trader properties
number
Current ranking position
string
Wallet address
string
ZKS ID if available, null otherwise
number
Score for the ranking metric
string
Formatted value for display
object
object
Detailed trading statistics
object
object
string
ISO 8601 timestamp of the response
Examples
curl "https://api.onzks.com/v1/trading/leaderboard?metric=volume" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.onzks.com/v1/trading/leaderboard?metric=profit&timeframe=30d" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.onzks.com/v1/trading/leaderboard?metric=winRate&limit=50" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.onzks.com/v1/trading/leaderboard?chainId=1&metric=efficiency" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.onzks.com/v1/trading/leaderboard?category=whale&metric=volume" \
-H "Authorization: Bearer YOUR_API_KEY"
async function getTradingLeaderboard(options = {}) {
const {
metric = 'volume',
timeframe = '30d',
chainId,
protocol,
category = 'all',
limit = 100,
offset = 0,
includeStats = true,
includeRanking = true
} = options;
const params = new URLSearchParams({
metric,
timeframe,
category,
limit: limit.toString(),
offset: offset.toString(),
includeStats: includeStats.toString(),
includeRanking: includeRanking.toString()
});
if (chainId) params.append('chainId', chainId.toString());
if (protocol) params.append('protocol', protocol);
const response = await fetch(
`https://api.onzks.com/v1/trading/leaderboard?${params}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const data = await response.json();
console.log(`Trading Leaderboard - ${metric.toUpperCase()}:`);
console.log(`Timeframe: ${timeframe}`);
console.log(`Total Traders: ${data.metadata.totalTraders}`);
console.log(`Top Score: ${data.metadata.topScore}`);
data.leaderboard.slice(0, 10).forEach((trader, index) => {
console.log(`${trader.rank}. ${trader.zksId || trader.address} - ${trader.value}`);
});
return data;
}
// Usage examples
await getTradingLeaderboard({ metric: 'volume' });
await getTradingLeaderboard({ metric: 'profit', timeframe: '30d' });
await getTradingLeaderboard({ metric: 'winRate', limit: 50 });
await getTradingLeaderboard({ chainId: 1, metric: 'efficiency' });
await getTradingLeaderboard({ category: 'whale', metric: 'volume' });
import requests
def get_trading_leaderboard(metric='volume', timeframe='30d', chain_id=None, protocol=None,
category='all', limit=100, offset=0, include_stats=True, include_ranking=True):
params = {
'metric': metric,
'timeframe': timeframe,
'category': category,
'limit': limit,
'offset': offset,
'includeStats': include_stats,
'includeRanking': include_ranking
}
if chain_id:
params['chainId'] = chain_id
if protocol:
params['protocol'] = protocol
response = requests.get(
'https://api.onzks.com/v1/trading/leaderboard',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params=params
)
data = response.json()
print(f"Trading Leaderboard - {metric.upper()}:")
print(f"Timeframe: {timeframe}")
print(f"Total Traders: {data['metadata']['totalTraders']}")
print(f"Top Score: {data['metadata']['topScore']}")
for trader in data['leaderboard'][:10]:
print(f"{trader['rank']}. {trader.get('zksId', trader['address'])} - {trader['value']}")
return data
# Usage examples
get_trading_leaderboard(metric='volume')
get_trading_leaderboard(metric='profit', timeframe='30d')
get_trading_leaderboard(metric='winRate', limit=50)
get_trading_leaderboard(chain_id=1, metric='efficiency')
get_trading_leaderboard(category='whale', metric='volume')
Response Example
{
"success": true,
"leaderboard": [
{
"rank": 1,
"address": "0x1234567890abcdef...",
"zksId": "whale.trader",
"score": 1250000.50,
"value": "$1,250,000.50",
"change": {
"position": 2,
"direction": "up",
"percentage": 15.5
},
"stats": {
"totalVolume": "1250000.50",
"totalTrades": 342,
"winRate": 68.5,
"totalPnL": "125000.75",
"averageTrade": "3654.97",
"uniqueProtocols": 15,
"uniqueAssets": 28,
"riskScore": 42.3,
"consistency": 78.5
},
"badges": [
{
"id": "volume-king",
"name": "Volume King",
"icon": "https://cdn.onzks.com/badges/volume-king.png",
"rarity": "legendary"
},
{
"id": "defi-pioneer",
"name": "DeFi Pioneer",
"icon": "https://cdn.onzks.com/badges/defi-pioneer.png",
"rarity": "epic"
}
]
},
{
"rank": 2,
"address": "0xabcdef1234567890...",
"zksId": "profit.master",
"score": 98.5,
"value": "98.5%",
"change": {
"position": -1,
"direction": "down",
"percentage": -2.3
},
"stats": {
"totalVolume": "850000.25",
"totalTrades": 156,
"winRate": 98.5,
"totalPnL": "425000.12",
"averageTrade": "5448.72",
"uniqueProtocols": 8,
"uniqueAssets": 15,
"riskScore": 25.7,
"consistency": 95.2
},
"badges": [
{
"id": "win-rate-champion",
"name": "Win Rate Champion",
"icon": "https://cdn.onzks.com/badges/win-rate-champion.png",
"rarity": "legendary"
}
]
},
{
"rank": 3,
"address": "0x9876543210fedcba...",
"zksId": "efficiency.expert",
"score": 2.1,
"value": "2.1x",
"change": {
"position": 0,
"direction": "same",
"percentage": 0.0
},
"stats": {
"totalVolume": "650000.00",
"totalTrades": 89,
"winRate": 75.2,
"totalPnL": "136500.00",
"averageTrade": "7303.37",
"uniqueProtocols": 12,
"uniqueAssets": 22,
"riskScore": 35.8,
"consistency": 82.1
},
"badges": [
{
"id": "efficiency-master",
"name": "Efficiency Master",
"icon": "https://cdn.onzks.com/badges/efficiency-master.png",
"rarity": "epic"
}
]
}
],
"pagination": {
"total": 12547,
"limit": 100,
"offset": 0,
"hasMore": true
},
"metadata": {
"metric": "volume",
"timeframe": "30d",
"lastUpdated": "2024-01-20T15:45:00Z",
"totalTraders": 12547,
"averageScore": 125000.50,
"topScore": 1250000.50
},
"timestamp": "2024-01-20T15:45:00Z"
}
Use Cases
1. Trading Competition Dashboard
Create a competitive trading dashboard:function createTradingCompetition(leaderboard) {
const competition = {
topTraders: leaderboard.leaderboard.slice(0, 10),
categories: {
volume: leaderboard.leaderboard.filter(t => t.stats.totalVolume > 1000000),
profit: leaderboard.leaderboard.filter(t => parseFloat(t.stats.totalPnL) > 100000),
consistency: leaderboard.leaderboard.filter(t => t.stats.consistency > 80)
},
badges: extractBadges(leaderboard.leaderboard),
insights: generateInsights(leaderboard)
};
return competition;
}
function extractBadges(traders) {
const badgeCounts = {};
traders.forEach(trader => {
trader.badges.forEach(badge => {
badgeCounts[badge.id] = (badgeCounts[badge.id] || 0) + 1;
});
});
return Object.entries(badgeCounts)
.sort(([,a], [,b]) => b - a)
.slice(0, 10);
}
2. Trader Profile Analysis
Analyze individual trader performance:function analyzeTraderProfile(trader) {
const analysis = {
strengths: [],
weaknesses: [],
recommendations: [],
riskLevel: assessRiskLevel(trader.stats.riskScore),
performance: assessPerformance(trader.stats)
};
// Analyze strengths
if (trader.stats.winRate > 80) {
analysis.strengths.push('High win rate');
}
if (trader.stats.consistency > 85) {
analysis.strengths.push('Consistent performance');
}
if (trader.stats.uniqueProtocols > 10) {
analysis.strengths.push('Diversified protocol usage');
}
// Analyze weaknesses
if (trader.stats.riskScore > 70) {
analysis.weaknesses.push('High risk trading');
}
if (trader.stats.winRate < 60) {
analysis.weaknesses.push('Low win rate');
}
// Generate recommendations
if (trader.stats.riskScore > 60) {
analysis.recommendations.push('Consider reducing position sizes');
}
if (trader.stats.uniqueProtocols < 5) {
analysis.recommendations.push('Explore more protocols for diversification');
}
return analysis;
}
3. Leaderboard Trends
Analyze leaderboard trends over time:async function analyzeLeaderboardTrends(metric, timeframe) {
const [current, previous] = await Promise.all([
getTradingLeaderboard({ metric, timeframe }),
getTradingLeaderboard({ metric, timeframe: getPreviousTimeframe(timeframe) })
]);
const trends = {
topMovers: findTopMovers(current.leaderboard, previous.leaderboard),
newEntries: findNewEntries(current.leaderboard, previous.leaderboard),
droppedOut: findDroppedOut(current.leaderboard, previous.leaderboard),
averageChange: calculateAverageChange(current.leaderboard, previous.leaderboard)
};
return trends;
}
function findTopMovers(current, previous) {
const previousMap = new Map(previous.map(t => [t.address, t.rank]));
return current
.filter(trader => {
const previousRank = previousMap.get(trader.address);
return previousRank && trader.rank < previousRank;
})
.sort((a, b) => (previousMap.get(a.address) - a.rank) - (previousMap.get(b.address) - b.rank))
.slice(0, 10);
}
4. Category Analysis
Analyze different trader categories:function analyzeTraderCategories(leaderboard) {
const categories = {
whale: leaderboard.leaderboard.filter(t => parseFloat(t.stats.totalVolume) > 1000000),
retail: leaderboard.leaderboard.filter(t => parseFloat(t.stats.totalVolume) < 100000),
professional: leaderboard.leaderboard.filter(t => t.stats.consistency > 80),
institutional: leaderboard.leaderboard.filter(t => t.stats.uniqueProtocols > 15)
};
const analysis = {};
Object.entries(categories).forEach(([category, traders]) => {
analysis[category] = {
count: traders.length,
averageVolume: calculateAverage(traders, 'totalVolume'),
averageWinRate: calculateAverage(traders, 'winRate'),
averageRisk: calculateAverage(traders, 'riskScore'),
topPerformer: traders[0]
};
});
return analysis;
}
5. Badge System
Implement a badge system for achievements:function assignBadges(trader) {
const badges = [];
// Volume badges
if (parseFloat(trader.stats.totalVolume) > 1000000) {
badges.push({ id: 'volume-king', name: 'Volume King', rarity: 'legendary' });
} else if (parseFloat(trader.stats.totalVolume) > 500000) {
badges.push({ id: 'volume-master', name: 'Volume Master', rarity: 'epic' });
}
// Win rate badges
if (trader.stats.winRate > 95) {
badges.push({ id: 'win-rate-champion', name: 'Win Rate Champion', rarity: 'legendary' });
} else if (trader.stats.winRate > 85) {
badges.push({ id: 'win-rate-expert', name: 'Win Rate Expert', rarity: 'epic' });
}
// Consistency badges
if (trader.stats.consistency > 90) {
badges.push({ id: 'consistency-master', name: 'Consistency Master', rarity: 'legendary' });
} else if (trader.stats.consistency > 80) {
badges.push({ id: 'consistency-expert', name: 'Consistency Expert', rarity: 'epic' });
}
// Protocol diversity badges
if (trader.stats.uniqueProtocols > 20) {
badges.push({ id: 'protocol-explorer', name: 'Protocol Explorer', rarity: 'legendary' });
} else if (trader.stats.uniqueProtocols > 10) {
badges.push({ id: 'protocol-diversifier', name: 'Protocol Diversifier', rarity: 'epic' });
}
return badges;
}
Best Practices
1. Caching
Cache leaderboard data for performance:let leaderboardCache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
async function getCachedLeaderboard(options = {}) {
const cacheKey = JSON.stringify(options);
const cached = leaderboardCache.get(cacheKey);
if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
return cached.data;
}
const data = await getTradingLeaderboard(options);
leaderboardCache.set(cacheKey, {
data,
timestamp: Date.now()
});
return data;
}
2. Real-time Updates
Subscribe to leaderboard updates:function subscribeToLeaderboardUpdates(metric, callback) {
const ws = new WebSocket(`wss://api.onzks.com/v1/trading/leaderboard/${metric}/subscribe`);
ws.onmessage = (event) => {
const update = JSON.parse(event.data);
callback(update);
};
return () => ws.close();
}
3. Pagination
Handle large leaderboards with pagination:async function getAllLeaderboard(metric, options = {}) {
const allTraders = [];
let offset = 0;
const limit = 100;
while (true) {
const data = await getTradingLeaderboard({
...options,
metric,
limit,
offset
});
allTraders.push(...data.leaderboard);
if (!data.pagination.hasMore) {
break;
}
offset += limit;
}
return allTraders;
}
4. Performance Optimization
Optimize for large datasets:function optimizeLeaderboardDisplay(leaderboard, viewport = 10) {
return {
visible: leaderboard.leaderboard.slice(0, viewport),
total: leaderboard.pagination.total,
hasMore: leaderboard.pagination.hasMore,
loadMore: () => loadMoreTraders(viewport)
};
}
Related Endpoints
- Get Trading Stats - Individual trader statistics
- Get Trading History - Detailed trade history
- Get Score - Overall ZKScore
Troubleshooting
”No traders found”
Cause: No traders match the criteria or invalid filters. Solution:- Remove restrictive filters
- Check if the timeframe has trading activity
- Verify metric and category values
”Invalid metric”
Cause: Unsupported metric value. Solution:- Use supported metrics: volume, profit, winRate, trades, efficiency, consistency, riskAdjusted
- Check for typos
”Invalid category”
Cause: Unsupported category value. Solution:- Use supported categories: all, whale, retail, professional, institutional
- Check for typos
Rate Limits
Leaderboard 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
⌘I