Skip to main content

​
Using ZKS IDs

ZKS IDs are human-readable identifiers that serve as your primary identity in the ZKScore ecosystem. Instead of using long wallet addresses, you can use memorable names like alice.zks or defi-master.zks.

​
What is a ZKS ID?

A ZKS ID is a unique, human-readable identifier that:
  • Ends with .zks suffix (e.g., alice.zks)
  • Maps to your primary wallet address
  • Becomes soulbound (non-transferable) after activation
  • Can be used across all ZKScore APIs and SDKs

​
Benefits

​
1. User-Friendly

Before: 0x742d35Cc6635C0532925a3b844D1FF4e1321
After:  alice.zks

​
2. Privacy Layer

Your ZKS ID acts as a privacy layer, keeping your wallet address private while maintaining your identity.

​
3. Cross-Platform

Use the same ZKS ID across:
  • ZKScore Explorer
  • Third-party integrations
  • DeFi protocols
  • NFT marketplaces

​
4. Memorable

Easy to share, remember, and communicate.

​
Getting Started

​
Step 1: Mint Your Identity

import { ZKScoreSDK } from '@zkscore/sdk';

const sdk = new ZKScoreSDK({
  apiKey: 'your-api-key',
  network: 'mainnet'
});

// Mint a new identity
const identity = await sdk.identity.mint({
  name: 'alice',  // Will become alice.zks
  walletAddress: '0x742d35Cc...'
});

​
Step 2: Activate Your Identity

// Activate to make it soulbound
const activated = await sdk.identity.activate({
  tokenId: identity.tokenId
});

​
Step 3: Use Your ZKS ID

// Now you can use your ZKS ID everywhere
const score = await sdk.getScore('alice.zks');
const achievements = await sdk.getAchievements('alice.zks');

​
Using ZKS IDs in APIs

​
Identity Endpoints

# Get identity by ZKS ID
curl https://api.onzks.com/v1/identity/alice.zks

# Get identity by wallet address (still supported)
curl https://api.onzks.com/v1/identity/0x742d35Cc...

​
Score Endpoints

# Get score by ZKS ID
curl https://api.onzks.com/v1/score/alice.zks

# Get score breakdown
curl https://api.onzks.com/v1/score/alice.zks/breakdown

​
Achievement Endpoints

# Get achievements by ZKS ID
curl https://api.onzks.com/v1/achievements/alice.zks

# Get achievement progress
curl https://api.onzks.com/v1/achievements/alice.zks/progress/defi-pioneer

​
Using ZKS IDs in SDK

​
JavaScript/TypeScript

import { ZKScoreSDK } from '@zkscore/sdk';

const sdk = new ZKScoreSDK({ apiKey: 'your-api-key' });

// All methods accept ZKS ID or wallet address
const score = await sdk.getScore('alice.zks');
const history = await sdk.getScoreHistory('alice.zks');
const achievements = await sdk.getAchievements('alice.zks');

​
React

import { useScore, useIdentity } from '@zkscore/sdk-react';

function ProfileCard({ identity }: { identity: string }) {
  // Works with both ZKS ID and wallet address
  const { score, isLoading } = useScore(identity);
  const { data: identityData } = useIdentity(identity);

  return (
    <div>
      <h2>{identityData?.name}.zks</h2>
      <p>Score: {score?.total}</p>
    </div>
  );
}

// Usage
<ProfileCard identity="alice.zks" />

​
Requirements

​
For Using ZKS ID as Parameter

To use a ZKS ID as a parameter in API calls or SDK methods, it must be:
  1. Minted: The identity must exist on-chain
  2. Activated: The identity must be soulbound (activated)
  3. Valid Format: Must match ^[a-z0-9-]+\.zks$

​
Validation Rules

✅ Valid ZKS IDs:
  • alice.zks
  • defi-master.zks
  • user123.zks
  • my-identity.zks
❌ Invalid ZKS IDs:
  • alice (missing .zks suffix)
  • Alice.zks (uppercase not allowed)
  • -alice.zks (cannot start with hyphen)
  • alice-.zks (cannot end with hyphen)
  • al.zks (too short, minimum 3 characters)

​
Best Practices

​
1. Choose a Memorable Name

// Good
'alice.zks'
'defi-trader.zks'
'nft-collector.zks'

// Avoid
'x.zks'  // Too short
'asdfjkl123.zks'  // Not memorable

​
2. Activate Immediately

// Mint and activate in sequence
const identity = await sdk.identity.mint({ name: 'alice' });
await sdk.identity.activate({ tokenId: identity.tokenId });

​
3. Use Consistently

// Use ZKS ID everywhere for consistency
const identity = 'alice.zks';

const score = await sdk.getScore(identity);
const achievements = await sdk.getAchievements(identity);
const history = await sdk.getScoreHistory(identity);

​
4. Handle Errors Gracefully

try {
  const score = await sdk.getScore('alice.zks');
} catch (error) {
  if (error.message.includes('not activated')) {
    // Prompt user to activate their identity
    console.log('Please activate your identity first');
  } else if (error.message.includes('not found')) {
    // Identity doesn't exist
    console.log('Identity not found');
  }
}

​
Migration Guide

​
From Wallet Addresses to ZKS IDs

If you’re currently using wallet addresses, here’s how to migrate: Before: 
const score = await sdk.getScore('0x742d35Cc6635C0532925a3b844D1FF4e1321');
After: 
// Both work! No breaking changes
const score = await sdk.getScore('alice.zks');
// OR
const score = await sdk.getScore('0x742d35Cc6635C0532925a3b844D1FF4e1321');

​
Update Your UI

// Before
<input placeholder="Enter wallet address (0x...)" />

// After
<input placeholder="Enter ZKS ID (e.g., alice.zks)" />

​
Advanced Usage

​
Resolving ZKS IDs

// SDK automatically resolves ZKS IDs to addresses
const resolved = await sdk.identity.resolve('alice.zks');
console.log(resolved.primaryAddress);  // 0x742d35Cc...
console.log(resolved.zksId);           // alice

​
Caching

The SDK caches ZKS ID resolutions for 5 minutes to improve performance: 
// First call: API request
const score1 = await sdk.getScore('alice.zks');

// Second call within 5 minutes: Uses cache
const score2 = await sdk.getScore('alice.zks');

​
Multiple Wallets (Future)

In the future, ZKS IDs will support multiple linked wallets: 
// Coming soon
const identity = await sdk.identity.get('alice.zks');
console.log(identity.primaryAddress);   // Main wallet
console.log(identity.linkedAddresses);  // Additional wallets
console.log(identity.aggregatedScore);  // Combined score

​
Troubleshooting

​
”Identity not found”

Cause: The ZKS ID hasn’t been minted yet. Solution: Mint the identity first: 
await sdk.identity.mint({ name: 'alice' });

​
“Identity must be activated”

Cause: The identity exists but hasn’t been activated (made soulbound). Solution: Activate the identity: 
await sdk.identity.activate({ tokenId: identity.tokenId });

​
“Invalid ZKS ID format”

Cause: The ZKS ID doesn’t match the required format. Solution: Ensure your ZKS ID:
  • Is 3-32 characters long (excluding .zks)
  • Contains only lowercase letters, numbers, and hyphens
  • Starts and ends with a letter or number
  • Ends with .zks suffix

​
FAQs

​
Can I change my ZKS ID?

No, ZKS IDs are soulbound and cannot be transferred or changed after activation.

​
Can I have multiple ZKS IDs?

Yes, you can mint multiple ZKS IDs, but each wallet can only have one primary ZKS ID.

​
What happens to my old wallet address?

Your wallet address still works! All APIs and SDKs support both ZKS IDs and wallet addresses.

​
Is my ZKS ID private?

ZKS IDs are public identifiers, but they provide a privacy layer by not directly exposing your wallet address.

​
Can I use ZKS IDs on other platforms?

Yes! ZKS IDs are on-chain and can be used by any platform that integrates with ZKScore.

​
Examples

​
Complete Integration Example

import { ZKScoreSDK } from '@zkscore/sdk';

async function setupIdentity() {
  const sdk = new ZKScoreSDK({ apiKey: 'your-api-key' });

  // 1. Mint identity
  const identity = await sdk.identity.mint({
    name: 'alice',
    walletAddress: '0x742d35Cc...'
  });

  // 2. Activate identity
  await sdk.identity.activate({
    tokenId: identity.tokenId
  });

  // 3. Use ZKS ID everywhere
  const score = await sdk.getScore('alice.zks');
  const achievements = await sdk.getAchievements('alice.zks');
  const history = await sdk.getScoreHistory('alice.zks');

  return {
    zksId: 'alice.zks',
    score,
    achievements,
    history
  };
}

​
React Component Example

import { useScore, useIdentity, useAchievements } from '@zkscore/sdk-react';

function UserProfile({ zksId }: { zksId: string }) {
  const { score, isLoading: scoreLoading } = useScore(zksId);
  const { data: identity, isLoading: identityLoading } = useIdentity(zksId);
  const { data: achievements, isLoading: achievementsLoading } = useAchievements(zksId);

  if (scoreLoading || identityLoading || achievementsLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <h1>{identity?.name}.zks</h1>
      <p>Score: {score?.total}</p>
      <p>Rank: #{score?.rank}</p>
      <h2>Achievements</h2>
      <ul>
        {achievements?.map(achievement => (
          <li key={achievement.id}>{achievement.title}</li>
        ))}
      </ul>
    </div>
  );
}

​
Next Steps

​
Support

Need help with ZKS IDs?