Skip to main content
GET
/
v1
/
identity
/
:identity
Get Identity
curl --request GET \
  --url https://api-mainnet.onzks.com/v1/identity/:identity \
  --header 'Authorization: Bearer <token>'
{
  "success": false,
  "error": "Identity 'alice.zks' not found or not activated"
}

​
Overview

Get detailed information about a ZKScore identity, including their ZKS ID, wallet address, activation status, and metadata.

​
Parameters

​
identity
string
required
ZKS ID (e.g., alice.zks) or wallet address (e.g., 0x742d35Cc...)
ZKS ID Requirements: If using a ZKS ID, it must be activated (soulbound). The API will return the primary wallet address and aggregated data across all linked wallets.

​
Response

​
success
boolean
Indicates if the request was successful
​
zksId
string | null
The ZKS ID (without .zks suffix), or null if not set
​
address
string
The primary wallet address
​
identity
object

​
Examples

curl https://api.onzks.com/v1/identity/alice.zks \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response Example

{
  "success": true,
  "zksId": "alice",
  "address": "0x742d35cc6635c0532925a3b844d1ff4e1321",
  "identity": {
    "tokenId": 12345,
    "name": "alice",
    "ownerAddress": "0x742d35cc6635c0532925a3b844d1ff4e1321",
    "isActivated": true,
    "createdAt": "2024-01-15T10:30:00Z",
    "activatedAt": "2024-01-15T11:00:00Z"
  }
}

​
Error Responses

{
  "success": false,
  "error": "Identity 'alice.zks' not found or not activated"
}

​
Use Cases

​
1. Profile Lookup

Use ZKS ID for a cleaner user experience: 
// User enters their ZKS ID
const identity = await getIdentity('alice.zks');
displayProfile(identity);

​
2. Identity Verification

Check if an identity exists and is activated: 
const identity = await getIdentity('alice.zks');
if (identity.identity.isActivated) {
  console.log('Identity is verified and soulbound');
}

​
3. Address Resolution

Resolve a ZKS ID to a wallet address: 
const identity = await getIdentity('alice.zks');
const walletAddress = identity.address;