> ## Documentation Index
> Fetch the complete documentation index at: https://core.anylayer.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Score

> Get the ZKScore for a user by ZKS ID or wallet address

## Overview

Retrieve the complete ZKScore for a user, including total score, rank, tier, and breakdown by category.

## Parameters

<ParamField path="identity" type="string" required>
  ZKS ID (e.g., `alice.zks`) or wallet address (e.g., `0x742d35Cc...`)
</ParamField>

<ParamField query="chainId" type="number">
  Specific chain ID to get score for (optional, defaults to aggregated score)
</ParamField>

<Note>
  **ZKS ID Support**: When using a ZKS ID, the API returns aggregated scores across all linked wallets for that identity.
</Note>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="zksId" type="string | null">
  The ZKS ID (without .zks suffix), or null if not set
</ResponseField>

<ResponseField name="address" type="string">
  The primary wallet address
</ResponseField>

<ResponseField name="score" type="object">
  <Expandable title="properties">
    <ResponseField name="total" type="number">
      Total ZKScore (0-10000)
    </ResponseField>

    <ResponseField name="rank" type="number">
      Global rank position
    </ResponseField>

    <ResponseField name="tier" type="string">
      Score tier: `bronze`, `silver`, `gold`, `platinum`, `diamond`, `legendary`
    </ResponseField>

    <ResponseField name="percentile" type="number">
      Percentile ranking (0-100)
    </ResponseField>

    <ResponseField name="breakdown" type="object">
      Score breakdown by category (activity, volume, age, diversity, governance, social, risk, loyalty)
    </ResponseField>

    <ResponseField name="lastUpdated" type="string">
      ISO 8601 timestamp of last score update
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL (ZKS ID) theme={null}
  curl https://api.onzks.com/v1/score/alice.zks \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (Wallet Address) theme={null}
  curl https://api.onzks.com/v1/score/0x742d35Cc6635C0532925a3b844D1FF4e1321 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onzks.com/v1/score/alice.zks', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });

  const data = await response.json();
  console.log(`Score: ${data.score.total}, Rank: #${data.score.rank}`);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://api.onzks.com/v1/score/alice.zks',
      headers={'Authorization': 'Bearer YOUR_API_KEY'}
  )

  data = response.json()
  print(f"Score: {data['score']['total']}, Rank: #{data['score']['rank']}")
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "success": true,
  "zksId": "alice",
  "address": "0x742d35cc6635c0532925a3b844d1ff4e1321",
  "score": {
    "total": 9847,
    "rank": 1,
    "tier": "legendary",
    "percentile": 99.9,
    "breakdown": {
      "activity": 1200,
      "volume": 1800,
      "age": 950,
      "diversity": 1400,
      "governance": 1100,
      "social": 897,
      "risk": 750,
      "loyalty": 1750
    },
    "lastUpdated": "2024-01-20T14:30:00Z"
  }
}
```

## Score Tiers

| Tier      | Score Range | Description       |
| --------- | ----------- | ----------------- |
| Bronze    | 0-299       | New users         |
| Silver    | 300-499     | Active users      |
| Gold      | 500-699     | Experienced users |
| Platinum  | 700-899     | Power users       |
| Diamond   | 900-1199    | Elite users       |
| Legendary | 1200+       | Top users         |

## Related Endpoints

* [Get Score Breakdown](/api-reference/scores/get-breakdown) - Detailed score breakdown
* [Get Score History](/api-reference/scores/get-history) - Historical score data
* [Get Leaderboard](/api-reference/scores/get-leaderboard) - Top scores