> ## 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

> Complete guide to using ZKS IDs as your primary identity in the ZKScore ecosystem

# 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

```javascript theme={null}
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

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

### Step 3: Use Your ZKS ID

```javascript theme={null}
// 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```bash theme={null}
# 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

```typescript theme={null}
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

```tsx theme={null}
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

```javascript theme={null}
// Good
'alice.zks'
'defi-trader.zks'
'nft-collector.zks'

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

### 2. Activate Immediately

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

### 3. Use Consistently

```javascript theme={null}
// 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

```javascript theme={null}
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:**

```javascript theme={null}
const score = await sdk.getScore('0x742d35Cc6635C0532925a3b844D1FF4e1321');
```

**After:**

```javascript theme={null}
// Both work! No breaking changes
const score = await sdk.getScore('alice.zks');
// OR
const score = await sdk.getScore('0x742d35Cc6635C0532925a3b844D1FF4e1321');
```

### Update Your UI

```tsx theme={null}
// Before
<input placeholder="Enter wallet address (0x...)" />

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

## Advanced Usage

### Resolving ZKS IDs

```javascript theme={null}
// 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:

```javascript theme={null}
// 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:

```javascript theme={null}
// 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:

```javascript theme={null}
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:

```javascript theme={null}
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

```typescript theme={null}
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

```tsx theme={null}
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](/api-reference/introduction) - Complete API documentation
* [SDK Documentation](/sdk/javascript/getting-started) - JavaScript SDK guide
* [React SDK](/sdk/react/getting-started) - React integration guide
* [Smart Contracts](/contracts/identity-sbt) - On-chain identity contracts

## Support

Need help with ZKS IDs?

* **Discord**: [Join our community](https://discord.gg/zkscore)
* **Email**: [support@onzks.com](mailto:support@onzks.com)
* **Documentation**: [docs.onzks.com](https://docs.onzks.com)