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

# SDK Overview

> ZKScore SDKs for JavaScript, TypeScript, and React applications

## What are ZKScore SDKs?

ZKScore SDKs provide easy-to-use libraries for integrating reputation scores, identity management, achievements, and trust systems into your applications. Available for JavaScript, TypeScript, and React.

<CardGroup cols={2}>
  <Card title="JavaScript SDK" icon="code" href="/sdk/javascript/getting-started">
    Full-featured SDK for Node.js and browser applications
  </Card>

  <Card title="React SDK" icon="react" href="/sdk/react/getting-started">
    React hooks and components for building user interfaces
  </Card>
</CardGroup>

## Key Features

### 🔐 Identity Management

Create and manage ZKScore identities with simple API calls:

```typescript theme={null}
import { ZKScoreSDK } from '@zkscore/sdk';

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

// Create identity
const identity = await sdk.identity.mint({
  address: '0x742d35...',
  username: 'alice',
});

// Get identity
const userIdentity = await sdk.identity.getIdentity('0x742d35...');
```

### 📊 Reputation Scoring

Access comprehensive reputation scores and analytics:

```typescript theme={null}
// Get overall score
const score = await sdk.scores.getScore('0x742d35...');

// Get detailed breakdown
const breakdown = await sdk.scores.getBreakdown('0x742d35...');

// Get score history
const history = await sdk.scores.getHistory('0x742d35...');
```

### 🏆 Achievement System

Track and manage user achievements:

```typescript theme={null}
// List all achievements
const achievements = await sdk.achievements.listAchievements();

// Get user achievements
const userAchievements = await sdk.achievements.getUserAchievements('0x742d35...');

// Claim achievement
await sdk.achievements.claim({
  achievementId: 'defi-expert',
  proof: zkProof,
});
```

### 🔒 Zero-Knowledge Proofs

Generate privacy-preserving proofs:

```typescript theme={null}
// Generate score proof
const proof = await sdk.zkProofs.generate({
  address: '0x742d35...',
  type: 'score-threshold',
  threshold: 700,
  hideExactScore: true,
});

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

### ✅ Trust Layer

Create and manage attestations:

```typescript theme={null}
// Create attestation
const attestation = await sdk.trustLayer.createAttestation({
  subject: '0x742d35...',
  schema: 'kyc-verification',
  data: { verified: true, level: 'tier-2' },
});

// Get attestations
const attestations = await sdk.trustLayer.getAttestations('0x742d35...');
```

## React Integration

Using React? We have hooks for everything:

```tsx theme={null}
import { useScore, useIdentity, useAchievements } from '@zkscore/react';

function UserProfile({ address }: { address: string }) {
  const { identity } = useIdentity(address);
  const { score } = useScore(address);
  const { achievements } = useAchievements(address);

  return (
    <div>
      <h1>{identity?.username || 'Anonymous'}</h1>
      <p>Score: {score?.overall}/1000</p>
      <p>Achievements: {achievements?.length || 0}</p>
    </div>
  );
}
```

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @zkscore/sdk @zkscore/react
  ```

  ```bash yarn theme={null}
  yarn add @zkscore/sdk @zkscore/react
  ```

  ```bash pnpm theme={null}
  pnpm add @zkscore/sdk @zkscore/react
  ```
</CodeGroup>

## Quick Start

1. **Get your API key** from the [Builder Portal](https://builder.onzks.com)
2. **Install the SDK** in your project
3. **Initialize** with your API key
4. **Start building** trust-enabled applications

```typescript theme={null}
import { ZKScoreSDK } from '@zkscore/sdk';

const sdk = new ZKScoreSDK({
  apiKey: process.env.ZKSCORE_API_KEY,
  network: 'mainnet',
});

// Get a user's score
const score = await sdk.scores.getScore('0x742d35...');
console.log(`Score: ${score.overall}/1000`);
```

## SDK Architecture

```mermaid theme={null}
graph TB
    A[Your Application] --> B[ZKScore SDK]
    B --> C[REST API]
    B --> D[Smart Contracts]
    C --> E[ZKScore Backend]
    D --> F[Blockchain]
    E --> G[Score Engine]
    E --> H[Identity Service]
    E --> I[Achievement System]
```

## Supported Platforms

<CardGroup cols={3}>
  <Card title="Node.js" icon="server">
    Full server-side support
  </Card>

  <Card title="Browser" icon="globe">
    Client-side applications
  </Card>

  <Card title="React" icon="react">
    React applications
  </Card>

  <Card title="Next.js" icon="nextjs">
    Next.js framework
  </Card>

  <Card title="Vue.js" icon="vue">
    Vue.js applications
  </Card>

  <Card title="Angular" icon="angular">
    Angular framework
  </Card>
</CardGroup>

## TypeScript Support

All SDKs are built with TypeScript and provide full type safety:

```typescript theme={null}
import { ZKScoreSDK } from '@zkscore/sdk';
import type { Score, Identity, Achievement } from '@zkscore/types';

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

// Fully typed responses
const score: Score = await sdk.scores.getScore('0x742d35...');
const identity: Identity = await sdk.identity.getIdentity('0x742d35...');
```

## Error Handling

Comprehensive error handling with detailed error codes:

```typescript theme={null}
try {
  const score = await sdk.scores.getScore(address);
} catch (error) {
  if (error.code === 'IDENTITY_NOT_FOUND') {
    console.log('User needs to create an identity first');
  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
    console.log('Too many requests, please wait');
  }
}
```

## Performance & Caching

Built-in caching and performance optimizations:

```typescript theme={null}
const sdk = new ZKScoreSDK({
  apiKey: 'your-key',
  cacheTime: 300000, // 5 minutes
  retryAttempts: 3,
});

// Automatic caching
const score1 = await sdk.scores.getScore(address); // API call
const score2 = await sdk.scores.getScore(address); // Cached
```

## Development Tools

<CardGroup cols={2}>
  <Card title="TypeScript Definitions" icon="code">
    Full TypeScript support with IntelliSense
  </Card>

  <Card title="Error Codes" icon="exclamation-triangle">
    Comprehensive error handling
  </Card>

  <Card title="Debug Mode" icon="bug">
    Detailed logging and debugging
  </Card>

  <Card title="Mock Data" icon="test-tube">
    Testing utilities and mock data
  </Card>
</CardGroup>

## Common Use Cases

### Score-Gated Access

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

### Achievement Tracking

```typescript theme={null}
async function trackProgress(userAddress: string) {
  const achievements = await sdk.achievements.getUserAchievements(userAddress);
  const progress = await sdk.achievements.getProgress(userAddress, 'defi-expert');
  
  return { earned: achievements.length, progress };
}
```

### Privacy-Preserving Verification

```typescript theme={null}
async function verifyWithPrivacy(userAddress: string) {
  const proof = await sdk.zkProofs.generate({
    address: userAddress,
    type: 'score-threshold',
    threshold: 700,
    hideExactScore: true,
  });
  
  return sdk.zkProofs.verify(proof);
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="API Key Security" icon="shield">
    Never expose API keys in client-side code
  </Card>

  <Card title="Error Handling" icon="exclamation-triangle">
    Always handle errors gracefully
  </Card>

  <Card title="Caching" icon="database">
    Use appropriate cache times for your use case
  </Card>

  <Card title="Rate Limiting" icon="gauge">
    Respect API rate limits
  </Card>
</CardGroup>

## Migration Guide

### From v1 to v2

```typescript theme={null}
// v1 (deprecated)
const client = new ZKScoreClient(apiKey);
const score = await client.getScore(address);

// v2 (current)
const sdk = new ZKScoreSDK({ apiKey });
const score = await sdk.scores.getScore(address);
```

## Community & Support

<CardGroup cols={2}>
  <Card title="GitHub" icon="github" href="https://github.com/metalanddev/ZKScoreEVM">
    Source code and issues
  </Card>

  <Card title="Discord" icon="discord" href="https://discord.gg/zkscore">
    Developer community
  </Card>

  <Card title="Documentation" icon="book" href="/docs">
    Complete documentation
  </Card>

  <Card title="Examples" icon="code" href="/sdk/examples">
    Code examples and tutorials
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Choose Your SDK">
    Pick JavaScript or React SDK based on your needs
    [Get Started →](/sdk/installation)
  </Step>

  <Step title="Install & Configure">
    Install the SDK and configure with your API key
    [Installation →](/sdk/installation)
  </Step>

  <Step title="Build Your First App">
    Create your first trust-enabled application
    [Quickstart →](/quickstart)
  </Step>

  <Step title="Explore Examples">
    See real-world integration examples
    [Examples →](/sdk/examples)
  </Step>
</Steps>

***

<Note>
  **Need help?** Check out our [Discord community](https://discord.gg/zkscore) or [GitHub issues](https://github.com/metalanddev/ZKScoreEVM/issues)
</Note>