Get Trading History
curl --request GET \
--url https://api-mainnet.onzks.com/v1/trading/history/:identity \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-mainnet.onzks.com/v1/trading/history/:identity"
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/history/:identity', 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/history/:identity",
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/history/:identity"
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/history/:identity")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-mainnet.onzks.com/v1/trading/history/:identity")
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,
"address": "<string>",
"zksId": "<string>",
"trades": [
{
"id": "<string>",
"timestamp": "<string>",
"type": "<string>",
"protocol": "<string>",
"chainId": 123,
"transactionHash": "<string>",
"blockNumber": 123,
"value": "<string>",
"volume": "<string>",
"fees": "<string>",
"pnl": "<string>",
"assets": [
{
"symbol": "<string>",
"name": "<string>",
"amount": "<string>",
"value": "<string>",
"action": "<string>"
}
],
"metadata": {
"gasUsed": "<string>",
"gasPrice": "<string>",
"slippage": 123,
"priceImpact": 123,
"route": [
{}
]
}
}
],
"pagination": {
"total": 123,
"limit": 123,
"offset": 123,
"hasMore": true
},
"summary": {
"totalTrades": 123,
"totalVolume": "<string>",
"totalFees": "<string>",
"totalPnL": "<string>",
"winRate": 123,
"averageTrade": "<string>"
},
"timestamp": "<string>"
}Trading
Get Trading History
Get detailed trading history for a user
GET
/
v1
/
trading
/
history
/
:identity
Get Trading History
curl --request GET \
--url https://api-mainnet.onzks.com/v1/trading/history/:identity \
--header 'Authorization: Bearer <token>'import requests
url = "https://api-mainnet.onzks.com/v1/trading/history/:identity"
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/history/:identity', 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/history/:identity",
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/history/:identity"
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/history/:identity")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-mainnet.onzks.com/v1/trading/history/:identity")
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,
"address": "<string>",
"zksId": "<string>",
"trades": [
{
"id": "<string>",
"timestamp": "<string>",
"type": "<string>",
"protocol": "<string>",
"chainId": 123,
"transactionHash": "<string>",
"blockNumber": 123,
"value": "<string>",
"volume": "<string>",
"fees": "<string>",
"pnl": "<string>",
"assets": [
{
"symbol": "<string>",
"name": "<string>",
"amount": "<string>",
"value": "<string>",
"action": "<string>"
}
],
"metadata": {
"gasUsed": "<string>",
"gasPrice": "<string>",
"slippage": 123,
"priceImpact": 123,
"route": [
{}
]
}
}
],
"pagination": {
"total": 123,
"limit": 123,
"offset": 123,
"hasMore": true
},
"summary": {
"totalTrades": 123,
"totalVolume": "<string>",
"totalFees": "<string>",
"totalPnL": "<string>",
"winRate": 123,
"averageTrade": "<string>"
},
"timestamp": "<string>"
}Overview
Retrieve comprehensive trading history including individual trades, transactions, and performance metrics. This endpoint provides detailed transaction data perfect for building trading analytics, tax reporting, and performance tracking.Use this endpoint to display individual trades, analyze trading patterns, generate reports, and provide detailed transaction history to users.
Parameters
string
required
User identity (ZKS ID or wallet address)
ZKS ID is recommended for better performance and user experience
number
Number of trades to return (default: 50, max: 1000)
number
Number of trades to skip for pagination (default: 0)
string
Time period for trades
7d- Last 7 days30d- Last 30 days90d- Last 90 days1y- Last yearall- All time (default)
string
Filter by specific protocol
uniswap- Uniswapsushiswap- SushiSwap1inch- 1inchcurve- Curvebalancer- Balancerpancakeswap- PancakeSwap
string
Filter by asset symbol (e.g., ETH, USDC, WBTC)
number
Filter by specific blockchain
1- Ethereum mainnet137- Polygon56- BSC42161- Arbitrum10- Optimism250- Fantom43114- Avalanche
string
Filter by trade type
swap- Token swapsliquidity- Liquidity provision/removallending- Lending/borrowingstaking- Staking operationsyield- Yield farming
string
Sort trades by field
timestamp- By timestamp (default)value- By trade valuepnl- By profit/lossvolume- By volume
string
Sort order
desc- Descending (default)asc- Ascending
Response
boolean
Indicates if the request was successful
string
Resolved wallet address
string
ZKS ID if available, null otherwise
array
Array of trade objects
Show trade properties
Show trade properties
string
Unique trade identifier
string
ISO 8601 timestamp of the trade
string
Type of trade (swap, liquidity, lending, staking, yield)
string
Protocol name where trade occurred
number
Blockchain where trade occurred
string
Blockchain transaction hash
number
Block number of the transaction
string
Total value of the trade in USD
string
Trading volume in USD
string
Fees paid for the trade
string
Profit/loss from the trade
array
object
object
string
ISO 8601 timestamp of the response
Examples
curl "https://api.onzks.com/v1/trading/history/alice.zks" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.onzks.com/v1/trading/history/alice.zks?timeframe=30d&limit=100" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.onzks.com/v1/trading/history/alice.zks?protocol=uniswap&type=swap" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.onzks.com/v1/trading/history/alice.zks?asset=ETH&sortBy=value&sortOrder=desc" \
-H "Authorization: Bearer YOUR_API_KEY"
curl "https://api.onzks.com/v1/trading/history/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
-H "Authorization: Bearer YOUR_API_KEY"
async function getTradingHistory(identity, options = {}) {
const {
limit = 50,
offset = 0,
timeframe = 'all',
protocol,
asset,
chainId,
type,
sortBy = 'timestamp',
sortOrder = 'desc'
} = options;
const params = new URLSearchParams({
limit: limit.toString(),
offset: offset.toString(),
timeframe,
sortBy,
sortOrder
});
if (protocol) params.append('protocol', protocol);
if (asset) params.append('asset', asset);
if (chainId) params.append('chainId', chainId.toString());
if (type) params.append('type', type);
const response = await fetch(
`https://api.onzks.com/v1/trading/history/${identity}?${params}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const data = await response.json();
console.log(`Trading History for ${data.zksId || data.address}:`);
console.log(`Total Trades: ${data.summary.totalTrades}`);
console.log(`Total Volume: $${parseFloat(data.summary.totalVolume).toLocaleString()}`);
console.log(`Win Rate: ${data.summary.winRate}%`);
console.log(`Total P&L: $${parseFloat(data.summary.totalPnL).toLocaleString()}`);
return data;
}
// Usage examples
await getTradingHistory('alice.zks');
await getTradingHistory('alice.zks', { timeframe: '30d', limit: 100 });
await getTradingHistory('alice.zks', { protocol: 'uniswap', type: 'swap' });
await getTradingHistory('alice.zks', { asset: 'ETH', sortBy: 'value', sortOrder: 'desc' });
import requests
def get_trading_history(identity, limit=50, offset=0, timeframe='all', protocol=None,
asset=None, chain_id=None, type=None, sort_by='timestamp', sort_order='desc'):
params = {
'limit': limit,
'offset': offset,
'timeframe': timeframe,
'sortBy': sort_by,
'sortOrder': sort_order
}
if protocol:
params['protocol'] = protocol
if asset:
params['asset'] = asset
if chain_id:
params['chainId'] = chain_id
if type:
params['type'] = type
response = requests.get(
f'https://api.onzks.com/v1/trading/history/{identity}',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params=params
)
data = response.json()
print(f"Trading History for {data.get('zksId', data['address'])}:")
print(f"Total Trades: {data['summary']['totalTrades']}")
print(f"Total Volume: ${float(data['summary']['totalVolume']):,.2f}")
print(f"Win Rate: {data['summary']['winRate']}%")
print(f"Total P&L: ${float(data['summary']['totalPnL']):,.2f}")
return data
# Usage examples
get_trading_history('alice.zks')
get_trading_history('alice.zks', timeframe='30d', limit=100)
get_trading_history('alice.zks', protocol='uniswap', type='swap')
get_trading_history('alice.zks', asset='ETH', sort_by='value', sort_order='desc')
Response Example
{
"success": true,
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"zksId": "alice.zks",
"trades": [
{
"id": "trade_12345",
"timestamp": "2024-01-20T15:45:00Z",
"type": "swap",
"protocol": "Uniswap V3",
"chainId": 1,
"transactionHash": "0xabcdef1234567890...",
"blockNumber": 19000000,
"value": "5000.00",
"volume": "5000.00",
"fees": "15.00",
"pnl": "250.00",
"assets": [
{
"symbol": "ETH",
"name": "Ethereum",
"amount": "2.0",
"value": "5000.00",
"action": "sell"
},
{
"symbol": "USDC",
"name": "USD Coin",
"amount": "5000.00",
"value": "5000.00",
"action": "buy"
}
],
"metadata": {
"gasUsed": "150000",
"gasPrice": "20",
"slippage": 0.5,
"priceImpact": 0.1,
"route": ["ETH", "USDC"]
}
},
{
"id": "trade_12346",
"timestamp": "2024-01-20T14:30:00Z",
"type": "liquidity",
"protocol": "Uniswap V3",
"chainId": 1,
"transactionHash": "0x1234567890abcdef...",
"blockNumber": 18999950,
"value": "10000.00",
"volume": "0.00",
"fees": "30.00",
"pnl": "0.00",
"assets": [
{
"symbol": "ETH",
"name": "Ethereum",
"amount": "4.0",
"value": "10000.00",
"action": "add"
},
{
"symbol": "USDC",
"name": "USD Coin",
"amount": "10000.00",
"value": "10000.00",
"action": "add"
}
],
"metadata": {
"gasUsed": "200000",
"gasPrice": "20",
"slippage": 0.0,
"priceImpact": 0.0,
"route": []
}
},
{
"id": "trade_12347",
"timestamp": "2024-01-20T13:15:00Z",
"type": "swap",
"protocol": "1inch",
"chainId": 1,
"transactionHash": "0x9876543210fedcba...",
"blockNumber": 18999900,
"value": "2500.00",
"volume": "2500.00",
"fees": "7.50",
"pnl": "-50.00",
"assets": [
{
"symbol": "USDC",
"name": "USD Coin",
"amount": "2500.00",
"value": "2500.00",
"action": "sell"
},
{
"symbol": "WBTC",
"name": "Wrapped Bitcoin",
"amount": "0.1",
"value": "2450.00",
"action": "buy"
}
],
"metadata": {
"gasUsed": "120000",
"gasPrice": "18",
"slippage": 1.2,
"priceImpact": 0.3,
"route": ["USDC", "ETH", "WBTC"]
}
}
],
"pagination": {
"total": 342,
"limit": 50,
"offset": 0,
"hasMore": true
},
"summary": {
"totalTrades": 342,
"totalVolume": "1250000.50",
"totalFees": "3750.00",
"totalPnL": "125000.75",
"winRate": 68.5,
"averageTrade": "3654.97"
},
"timestamp": "2024-01-20T15:45:00Z"
}
Use Cases
1. Trading Analytics Dashboard
Create a comprehensive trading analytics dashboard:function createTradingAnalytics(trades) {
const analytics = {
performance: calculatePerformance(trades),
patterns: analyzeTradingPatterns(trades),
assets: analyzeAssetDistribution(trades),
protocols: analyzeProtocolUsage(trades),
timing: analyzeTradingTiming(trades)
};
return analytics;
}
function calculatePerformance(trades) {
const totalPnL = trades.reduce((sum, trade) => sum + parseFloat(trade.pnl), 0);
const totalVolume = trades.reduce((sum, trade) => sum + parseFloat(trade.volume), 0);
const totalFees = trades.reduce((sum, trade) => sum + parseFloat(trade.fees), 0);
const profitableTrades = trades.filter(trade => parseFloat(trade.pnl) > 0);
const winRate = (profitableTrades.length / trades.length) * 100;
return {
totalPnL,
totalVolume,
totalFees,
winRate,
averageTrade: totalVolume / trades.length,
roi: (totalPnL / totalVolume) * 100
};
}
2. Trade Analysis
Analyze individual trades:function analyzeTrade(trade) {
const analysis = {
profitability: parseFloat(trade.pnl) > 0 ? 'Profitable' : 'Loss',
efficiency: parseFloat(trade.pnl) / parseFloat(trade.value) * 100,
gasEfficiency: parseFloat(trade.value) / parseFloat(trade.metadata.gasUsed),
slippage: trade.metadata.slippage,
priceImpact: trade.metadata.priceImpact
};
return analysis;
}
function findBestTrades(trades, limit = 10) {
return trades
.sort((a, b) => parseFloat(b.pnl) - parseFloat(a.pnl))
.slice(0, limit);
}
function findWorstTrades(trades, limit = 10) {
return trades
.sort((a, b) => parseFloat(a.pnl) - parseFloat(b.pnl))
.slice(0, limit);
}
3. Protocol Analysis
Analyze trading by protocol:function analyzeProtocols(trades) {
const protocolStats = {};
trades.forEach(trade => {
if (!protocolStats[trade.protocol]) {
protocolStats[trade.protocol] = {
trades: 0,
volume: 0,
pnl: 0,
fees: 0
};
}
protocolStats[trade.protocol].trades++;
protocolStats[trade.protocol].volume += parseFloat(trade.volume);
protocolStats[trade.protocol].pnl += parseFloat(trade.pnl);
protocolStats[trade.protocol].fees += parseFloat(trade.fees);
});
return Object.entries(protocolStats).map(([protocol, stats]) => ({
protocol,
...stats,
efficiency: stats.pnl / stats.volume * 100,
averageTrade: stats.volume / stats.trades
}));
}
4. Asset Analysis
Analyze trading by asset:function analyzeAssets(trades) {
const assetStats = {};
trades.forEach(trade => {
trade.assets.forEach(asset => {
if (!assetStats[asset.symbol]) {
assetStats[asset.symbol] = {
name: asset.name,
trades: 0,
volume: 0,
pnl: 0,
actions: { buy: 0, sell: 0, add: 0, remove: 0 }
};
}
assetStats[asset.symbol].trades++;
assetStats[asset.symbol].volume += parseFloat(asset.value);
assetStats[asset.symbol].actions[asset.action]++;
});
});
return Object.entries(assetStats).map(([symbol, stats]) => ({
symbol,
...stats,
averageTrade: stats.volume / stats.trades
}));
}
5. Time-based Analysis
Analyze trading patterns over time:function analyzeTradingTiming(trades) {
const hourlyStats = {};
const dailyStats = {};
const monthlyStats = {};
trades.forEach(trade => {
const date = new Date(trade.timestamp);
const hour = date.getHours();
const day = date.getDay();
const month = date.getMonth();
// Hourly analysis
if (!hourlyStats[hour]) {
hourlyStats[hour] = { trades: 0, volume: 0, pnl: 0 };
}
hourlyStats[hour].trades++;
hourlyStats[hour].volume += parseFloat(trade.volume);
hourlyStats[hour].pnl += parseFloat(trade.pnl);
// Daily analysis
if (!dailyStats[day]) {
dailyStats[day] = { trades: 0, volume: 0, pnl: 0 };
}
dailyStats[day].trades++;
dailyStats[day].volume += parseFloat(trade.volume);
dailyStats[day].pnl += parseFloat(trade.pnl);
// Monthly analysis
if (!monthlyStats[month]) {
monthlyStats[month] = { trades: 0, volume: 0, pnl: 0 };
}
monthlyStats[month].trades++;
monthlyStats[month].volume += parseFloat(trade.volume);
monthlyStats[month].pnl += parseFloat(trade.pnl);
});
return {
hourly: hourlyStats,
daily: dailyStats,
monthly: monthlyStats
};
}
Best Practices
1. Pagination
Handle large trading histories with pagination:async function getAllTradingHistory(identity, options = {}) {
const allTrades = [];
let offset = 0;
const limit = 100;
while (true) {
const data = await getTradingHistory(identity, {
...options,
limit,
offset
});
allTrades.push(...data.trades);
if (!data.pagination.hasMore) {
break;
}
offset += limit;
}
return allTrades;
}
2. Filtering
Implement efficient filtering:function filterTrades(trades, filters) {
return trades.filter(trade => {
if (filters.protocol && trade.protocol !== filters.protocol) return false;
if (filters.type && trade.type !== filters.type) return false;
if (filters.asset && !trade.assets.some(a => a.symbol === filters.asset)) return false;
if (filters.chainId && trade.chainId !== filters.chainId) return false;
if (filters.minValue && parseFloat(trade.value) < filters.minValue) return false;
if (filters.maxValue && parseFloat(trade.value) > filters.maxValue) return false;
if (filters.profitable && parseFloat(trade.pnl) <= 0) return false;
return true;
});
}
3. Caching
Cache trading history for performance:let tradingHistoryCache = new Map();
const CACHE_TTL = 2 * 60 * 1000; // 2 minutes
async function getCachedTradingHistory(identity, options = {}) {
const cacheKey = `${identity}-${JSON.stringify(options)}`;
const cached = tradingHistoryCache.get(cacheKey);
if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
return cached.data;
}
const data = await getTradingHistory(identity, options);
tradingHistoryCache.set(cacheKey, {
data,
timestamp: Date.now()
});
return data;
}
4. Real-time Updates
Subscribe to new trades:function subscribeToNewTrades(identity, callback) {
const ws = new WebSocket(`wss://api.onzks.com/v1/trading/history/${identity}/subscribe`);
ws.onmessage = (event) => {
const newTrade = JSON.parse(event.data);
callback(newTrade);
};
return () => ws.close();
}
Related Endpoints
- Get Trading Stats - Trading statistics
- Get Trading Leaderboard - Top traders
- Get Score - Overall ZKScore
Troubleshooting
”No trading history found”
Cause: User has no trading activity or filters are too restrictive. Solution:- Remove filters to see all trades
- Check if the user has any trading activity
- Try a longer timeframe
”Invalid protocol”
Cause: Unsupported protocol value. Solution:- Use supported protocols: uniswap, sushiswap, 1inch, curve, balancer, pancakeswap
- Check for typos
”Invalid asset”
Cause: Unsupported asset symbol. Solution:- Use standard asset symbols (ETH, USDC, WBTC, etc.)
- Check for typos
Rate Limits
Trading history 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