DeepLens exposes a set of REST API endpoints for leaderboard data, composite scores, wallet activity, protocol attribution, and system health. All endpoints return JSON and support standard HTTP caching.
https://deeplens.appAll endpoints are rate-limited using in-memory sliding window counters based on client IP. Exceeding the limit returns a 429 Too Many Requests response with a Retry-After: 10 header.
| Endpoint Group | Window | Max Requests |
|---|---|---|
| Leaderboard | 10 seconds | 20 |
| V2 Scores & Wallet | 10 seconds | 30 |
| V2 Protocols | 10 seconds | 40 |
Most data endpoints include cache-control headers to optimize repeated requests:
private — Response is specific to the request and should not be stored by shared caches.max-age=30 — Consider the response fresh for 30 seconds.stale-while-revalidate=300 — Serve stale content for up to 5 minutes while revalidating in the background.The health endpoint uses Cache-Control: no-store since it must always reflect the current state.
/api/leaderboardReturns the full DeepBook leaderboard with points, volume, trade counts, SuiNS names, rank deltas, and protocol attribution.
| Parameter | Type | Default | Description |
|---|---|---|---|
| search | string | — | Filter by address, SuiNS name, or protocol name |
| page | number | 1 | Page number (1-indexed) |
| pageSize | number | 50 | Results per page (max 100) |
| paginate | boolean | false | Enable server-side pagination |
# Example
curl "https://deeplens.app/api/leaderboard?paginate=true&page=1&pageSize=10"
{
"updatedAt": "2026-03-28T12:00:00Z",
"totals": {
"eligibleTraders": 50123,
"totalPoints": 9312456,
"totalVolume": 482000000,
"totalActions": 1250000,
"totalPnl": 1200000
},
"leaderboard": [
{
"address": "0xabc...def",
"suinsName": "alice.sui",
"points": 125000,
"volume": 5200000,
"actions": 3200,
"pnl": 45000,
"rankDelta": 3,
"mainProtocol": "Cetus",
"mainProtocolId": "cetus"
}
],
"pagination": {
"page": 1,
"pageSize": 10,
"total": 50123,
"totalPages": 5013
}
}/api/v2/scoresReturns composite scores for all wallets with tier assignments, score breakdowns, and ranking metadata.
| Parameter | Type | Default | Description |
|---|---|---|---|
| page | number | 1 | Page number |
| pageSize | number | 50 | Results per page (max 100) |
| search | string | — | Filter by address or SuiNS name |
| tier | string | — | Filter by tier (diamond, platinum, gold, silver, bronze) |
# Example
curl "https://deeplens.app/api/v2/scores?tier=diamond&pageSize=5"
{
"updatedAt": "2026-03-28T12:00:00Z",
"version": "v2.1",
"weights": {
"points": 0.35,
"volume": 0.25,
"tradeCount": 0.15,
"protocolDiversity": 0.15,
"consistency": 0.10
},
"totals": {
"scoredWallets": 50123,
"averageScore": 12.45,
"medianScore": 5.32
},
"tiers": {
"diamond": 501,
"platinum": 2005,
"gold": 5018,
"silver": 12530,
"bronze": 30069
},
"leaderboard": [
{
"address": "0xabc...def",
"compositeScore": 94.21,
"normalizedPoints": 1.0,
"normalizedVolume": 0.89,
"normalizedTrades": 0.95,
"protocolDiversity": 0.917,
"consistencyRatio": 0.82,
"rank": 1,
"tier": "diamond",
"rawPoints": 125000,
"rawVolume": 5200000,
"rawTradeCount": 4750,
"uniqueProtocols": 11,
"currentPoints": 102500,
"totalPoints": 125000,
"suinsName": "alice.sui",
"rankDelta": 0
}
],
"pagination": {
"page": 1,
"pageSize": 5,
"total": 501,
"totalPages": 101
}
}/api/v2/wallet/{address}/scoreReturns the composite score breakdown for a single wallet. Address must be a valid 0x-prefixed Sui address (66 hex chars).
# Example
curl "https://deeplens.app/api/v2/wallet/0xabc.../score"
{
"address": "0xabc...def",
"updatedAt": "2026-03-28T12:00:00Z",
"score": {
"compositeScore": 67.84,
"normalizedPoints": 0.68,
"normalizedVolume": 0.55,
"normalizedTrades": 0.72,
"protocolDiversity": 0.5,
"consistencyRatio": 0.85,
"rank": 1245,
"tier": "gold",
"rawPoints": 68000,
"rawVolume": 550000,
"rawTradeCount": 3600,
"uniqueProtocols": 6,
"currentPoints": 57800,
"totalPoints": 68000,
"suinsName": "bob.sui",
"rankDelta": 12
}
}/api/v2/wallet/{address}/activityReturns the 7-metric activity model for a single wallet. See the Activity Model docs for metric definitions.
# Example
curl "https://deeplens.app/api/v2/wallet/0xabc.../activity"
{
"address": "0xabc...def",
"updatedAt": "2026-03-28T12:00:00Z",
"activity": {
"address": "0xabc...def",
"frequency": 3.456,
"recency": 1.2,
"consistency": 0.85,
"breadth": 6,
"trend": "improving",
"engagementDurability": 0.875,
"notionalConsistency": 0.925
}
}/api/v2/wallet/{address}/protocolsReturns all protocol interactions for a wallet: which protocols, frequency counts, and the most-used protocol.
# Example
curl "https://deeplens.app/api/v2/wallet/0xabc.../protocols"
{
"address": "0xabc...def",
"updatedAt": "2026-03-28T12:00:00Z",
"seasonStart": "2026-01-22T00:00:00Z",
"usage": {
"protocols": [
{ "protocolId": "cetus", "protocolName": "Cetus", "txCount": 145 },
{ "protocolId": "aftermath", "protocolName": "Aftermath", "txCount": 89 }
],
"mostUsedProtocol": {
"protocolId": "cetus",
"protocolName": "Cetus"
}
}
}/api/v2/protocolsReturns the aggregate protocol summary: all 12 tracked protocols with user counts, total points, and categories.
# Example
curl "https://deeplens.app/api/v2/protocols"
/api/v2/protocols/{protocolId}/usersReturns wallets attributed to a specific protocol with frequency counts.
| Parameter | Type | Default | Description |
|---|---|---|---|
| search | string | — | Filter by address |
| limit | number | 100 | Max results (up to 500) |
# Example
curl "https://deeplens.app/api/v2/protocols/cetus/users?limit=5"
/api/v2/healthSystem health check. Returns the status of all Redis data keys (leaderboard, scores, activity, protocols). Returns 200 if all keys are fresh, 503 if any are stale or missing.
# Example
curl "https://deeplens.app/api/v2/health"
{
"status": "healthy",
"timestamp": "2026-03-30T14:00:00Z",
"checks": [
{
"name": "leaderboard",
"status": "ok",
"updatedAt": "2026-03-28T12:00:00Z",
"ageMs": 180000000
},
{
"name": "composite_scores",
"status": "ok",
"updatedAt": "2026-03-28T12:05:00Z",
"ageMs": 179700000
}
],
"summary": {
"total": 6,
"ok": 6,
"stale": 0,
"missing": 0
}
}Stale threshold: 72 hours. Any data key older than 72h is reported as "stale". Missing keys report as "missing".
| Status | Meaning | Example Cause |
|---|---|---|
| 400 | Bad Request | Invalid Sui address format, invalid protocol ID |
| 404 | Not Found | Data not yet computed (run pipeline scripts first) |
| 429 | Too Many Requests | Rate limit exceeded. Retry after the Retry-After header value. |
| 500 | Internal Server Error | Redis connection failure, JSON parsing error, unexpected exception |
All error responses follow the format: { "error": "Human-readable error message" }