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:

Minted: The identity must exist on-chain
Activated: The identity must be soulbound (activated)
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

API Reference - Complete API documentation
SDK Documentation - JavaScript SDK guide
React SDK - React integration guide
Smart Contracts - On-chain identity contracts

Support

Need help with ZKS IDs?

Discord: Join our community
Email: support@onzks.com
Documentation: docs.onzks.com

​Using ZKS IDs

​What is a ZKS ID?

​Benefits

​1. User-Friendly

​2. Privacy Layer

​3. Cross-Platform

​4. Memorable

​Getting Started

​Step 1: Mint Your Identity

​Step 2: Activate Your Identity

​Step 3: Use Your ZKS ID

​Using ZKS IDs in APIs

​Identity Endpoints

​Score Endpoints

​Achievement Endpoints

​Using ZKS IDs in SDK

​JavaScript/TypeScript

​React

​Requirements

​For Using ZKS ID as Parameter

​Validation Rules

​Best Practices

​1. Choose a Memorable Name

​2. Activate Immediately

​3. Use Consistently

​4. Handle Errors Gracefully

​Migration Guide

​From Wallet Addresses to ZKS IDs

​Update Your UI

​Advanced Usage

​Resolving ZKS IDs

​Caching

​Multiple Wallets (Future)

​Troubleshooting

​”Identity not found”

​“Identity must be activated”

​“Invalid ZKS ID format”

​FAQs

​Can I change my ZKS ID?

​Can I have multiple ZKS IDs?

​What happens to my old wallet address?

​Is my ZKS ID private?

​Can I use ZKS IDs on other platforms?

​Examples

​Complete Integration Example

​React Component Example

​Next Steps

​Support