Wallet Score API

GET /api/v1/wallet/{network}/{address}

curl -X GET "https://zkcodex.com/api/v1/wallet/base/0xEAa823AB4C4eE00283d8ed7be713ddf8A5ba0Fac" \n  -H "Accept: application/json" \n  --max-time 65

async function getWalletScore(network: string, address: string) {
  const res = await fetch(`https://zkcodex.com/api/v1/wallet/${network}/${address}`, {
    headers: { Accept: "application/json" },
    // A wallet the cache does not hold is scanned for up to 55 s.
    signal: AbortSignal.timeout(65_000),
  });
  if (res.status === 429) {
    throw new Error(`Rate limited; retry in ${res.headers.get("Retry-After")} s`);
  }
  const body = await res.json();
  if (!body.success) throw new Error(body.error);
  return body;
}

// A network slug or its chain ID: "base" and "8453" are the same.
const base = await getWalletScore("base", "0xEAa823AB4C4eE00283d8ed7be713ddf8A5ba0Fac");
console.log(`Base score: ${base.data.score.total} [${base.data.score.tier}]`);

import requests

def get_wallet_score(network: str, address: str):
    url = f"https://zkcodex.com/api/v1/wallet/{network}/{address}"
    # A wallet the cache does not hold is scanned for up to 55 s.
    res = requests.get(url, headers={"Accept": "application/json"}, timeout=65)
    if res.status_code == 429:
        raise RuntimeError(f"Rate limited; retry in {res.headers.get('Retry-After')} s")
    body = res.json()
    if not body["success"]:
        raise RuntimeError(body["error"])
    return body

data = get_wallet_score("base", "0xEAa823AB4C4eE00283d8ed7be713ddf8A5ba0Fac")
print(f"Score: {data['data']['score']['total']} ({data['data']['score']['tier']})")

{
  "success": true,
  "data": {
    "address": "0xEAa823AB4C4eE00283d8ed7be713ddf8A5ba0Fac",
    "network": "base",
    "networkName": "Base",
    "chainId": 8453,
    "nativeCurrency": "ETH",
    "isTestnet": false,
    "score": {
      "version": "score-2.1",
      "total": 100,
      "tier": "Legend",
      "rank": 214,
      "ranked": 2548,
      "percentile": "Top 8.4%",
      "breakdown": {
        "activityScore": 88.67,
        "volumeScore": 96,
        "diversityScore": 100,
        "technicalScore": 92.5
      }
    },
    "metrics": {
      "totalTransactions": 2412,
      "uniqueContracts": 733,
      "totalVolumeUSD": 223184.26,
      "totalGasSpentNative": 0.03738,
      "totalGasSpentUSD": 92.7,
      "firstTransactionDate": "2023-07-15T12:37:35.000Z",
      "lastTransactionDate": "2026-08-24T20:08:29.000Z"
    },
    "activity": {
      "activeDays": 473,
      "activeWeeks": 145,
      "activeMonths": 38,
      "currentStreakDays": 1,
      "longestStreakDays": 26
    },
    "defi": {
      "totalDeFiActivities": 482,
      "swapCount": 215,
      "liquidityCount": 42,
      "stakingCount": 18,
      "lpStakingCount": 6,
      "deployedContracts": 8,
      "nftMintCount": 145
    },
    "tokens": {
      "uniqueTokens": 86,
      "tokenTransfers": 1240,
      "tokenDiversity": 68
    },
    "behavior": {
      "transactionFrequency": 2.14,
      "consistencyScore": 0.31
    },
    "badges": {
      "totalEarned": 58,
      "totalAvailable": 69,
      "items": [
        { "id": "first-steps", "numericId": 1, "name": "First Steps", "tier": "bronze", "category": "Transactions", "description": "Made your first transaction on-chain", "earned": true },
        { "id": "base-pioneer", "numericId": 54, "name": "Base Pioneer", "tier": "base", "category": "Base Exclusive", "description": "Made your first transaction on Base", "earned": true }
      ]
    }
  },
  "cached": false,
  "timestamp": "2026-08-25T12:00:00.000Z"
}

{
  "success": false,
  "error": "Too many wallet scans; try again in a minute"
}