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.
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.
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.zksdefi-master.zksuser123.zksmy-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
// 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');
// 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 });
- 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.
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?
