Skip to main content

Welcome to ZKScore Guides

This section provides step-by-step guides for integrating ZKScore into your applications, from basic setup to advanced features.

Quick Start Path

1

Get API Key

Create your API key in the Builder Portal API Keys Guide →
2

Install SDK

Add ZKScore SDK to your project Getting Started →
3

Create Identity

Mint your first ZKScore identity Identity Guide →
4

Build Features

Add trust and reputation to your app Trust Gating →

Integration Patterns

Score-Gated Applications

Control access based on reputation scores:
import { ZKScoreSDK } from '@zkscore/sdk';

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

async function checkAccess(userAddress: string, minScore: number) {
  const score = await sdk.scores.getScore(userAddress);
  return score.overall >= minScore;
}

// Gate premium features
if (await checkAccess(userAddress, 700)) {
  showPremiumContent();
} else {
  showUpgradePrompt();
}

Achievement Systems

Gamify user engagement with achievements:
// Track user progress
const progress = await sdk.achievements.getProgress(userAddress, 'defi-expert');

// Show progress bar
<ProgressBar 
  current={progress.requirements.defiTransactions.current}
  total={progress.requirements.defiTransactions.required}
  label="DeFi Transactions"
/>

// Claim when eligible
if (progress.completed) {
  await sdk.achievements.claim({ achievementId: 'defi-expert' });
}

Privacy-Preserving Verification

Use zero-knowledge proofs for private verification:
// Generate proof without revealing exact score
const proof = await sdk.zkProofs.generate({
  address: userAddress,
  type: 'score-threshold',
  threshold: 700,
  hideExactScore: true,
});

// Verify on server
const isValid = await sdk.zkProofs.verify(proof);

Trust Systems

Build custom trust frameworks with attestations:
// Create KYC attestation
await sdk.trustLayer.createAttestation({
  subject: userAddress,
  schema: 'kyc-verification',
  data: {
    verified: true,
    level: 'tier-2',
    provider: 'Synaps',
  },
});

// Check trust requirements
const evaluation = await sdk.trustLayer.evaluatePolicy(userAddress, {
  rules: [
    {
      schema: 'kyc-verification',
      required: true,
      conditions: { 'data.verified': true },
    },
  ],
});

Common Use Cases

Platform-Specific Guides

Web Applications

Mobile Applications

Backend Services

Advanced Topics

Best Practices

Security

API Key Security

Never expose API keys in client-side code

Input Validation

Always validate user inputs

Error Handling

Implement comprehensive error handling

Rate Limiting

Respect API rate limits

Performance

Caching

Cache frequently accessed data

Batch Requests

Combine multiple API calls

Lazy Loading

Load data only when needed

Optimistic Updates

Update UI before API confirmation

User Experience

Loading States

Show loading indicators

Error Messages

Provide clear error feedback

Progressive Enhancement

Graceful degradation

Accessibility

Ensure inclusive design

Troubleshooting

Common Issues

Problem: Getting 401 Unauthorized errors
Solution: Verify your API key is correct and active in the Builder Portal
Problem: User doesn’t have a ZKScore identity
Solution: Prompt user to create an identity using sdk.identity.mint()
Problem: Too many API requests
Solution: Implement exponential backoff and caching
Problem: Scores appear outdated
Solution: Scores update in real-time, check for caching issues

Debug Mode

Enable debug logging to troubleshoot issues:
const sdk = new ZKScoreSDK({
  apiKey: 'your-key',
  debug: true, // Enable debug logging
});

// Debug logs will show:
// - API requests and responses
// - Cache hits and misses
// - Error details
// - Performance metrics

Community Resources

Migration Guides

From v1 to v2

1

Update Dependencies

Install the latest SDK version
npm install @zkscore/sdk@latest
2

Update API Calls

Replace deprecated methods with new ones
// Old
const client = new ZKScoreClient(apiKey);
const score = await client.getScore(address);

// New
const sdk = new ZKScoreSDK({ apiKey });
const score = await sdk.scores.getScore(address);
3

Test Integration

Verify all features work correctly

Support


New to ZKScore? Start with our Getting Started Guide for a quick 5-minute setup.