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

# API Reference

> Complete API reference for ZKScore platform

## Base URL

All API requests should be made to:

```
https://api-mainnet.onzks.com
```

## Authentication

ZKScore API uses Bearer token authentication. Include your API key in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Get your API key from the [Developer Portal](https://builder.onzks.com/keys).

<Warning>
  Never expose your API key in client-side code. Always make API calls from your backend server.
</Warning>

## Request Format

All requests should include the following headers:

```bash theme={null}
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
```

## Response Format

All API responses follow this structure:

```json theme={null}
{
  "success": true,
  "data": {
    // Response data here
  },
  "timestamp": "2025-10-22T10:30:00Z"
}
```

### Error Responses

Error responses include an error code and message:

```json theme={null}
{
  "success": false,
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests. Please try again later.",
  "timestamp": "2025-10-22T10:30:00Z"
}
```

## Rate Limits

API rate limits depend on your subscription tier:

| Tier         | Requests per Minute | Requests per Day |
| ------------ | ------------------- | ---------------- |
| Free         | 60                  | 10,000           |
| Starter      | 300                 | 100,000          |
| Professional | 1,000               | 1,000,000        |
| Enterprise   | Custom              | Custom           |

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1698765432
```

## Pagination

List endpoints support pagination using `limit` and `offset` parameters:

```bash theme={null}
GET /api/v1/achievements?limit=50&offset=100
```

Paginated responses include metadata:

```json theme={null}
{
  "success": true,
  "data": [...],
  "pagination": {
    "total": 250,
    "limit": 50,
    "offset": 100,
    "hasMore": true
  }
}
```

## Filtering & Sorting

Many endpoints support filtering and sorting:

```bash theme={null}
# Filter by category
GET /api/v1/achievements?category=wallet_age

# Sort by score
GET /api/v1/scores/leaderboard?sort=totalScore&order=desc

# Multiple filters
GET /api/v1/attestations?status=active&chainId=998899
```

## Webhooks

Subscribe to real-time events using webhooks. See the [Webhooks Guide](/guides/webhooks) for setup instructions.

Available events:

* `identity.created`
* `identity.activated`
* `score.updated`
* `achievement.earned`
* `attestation.created`
* `attestation.revoked`

## SDKs

We provide official SDKs for easy integration:

<CardGroup cols={2}>
  <Card title="JavaScript/TypeScript" icon="js" href="/sdk/javascript/getting-started">
    ```bash theme={null}
    npm install @zkscore/sdk
    ```
  </Card>

  <Card title="React" icon="react" href="/sdk/react/getting-started">
    ```bash theme={null}
    npm install @zkscore/sdk-react
    ```
  </Card>
</CardGroup>

## API Endpoints

### Identity Management

* [Get Identity](/api-reference/identity/get-identity) - Retrieve identity information
* [Mint Identity](/api-reference/identity/mint-identity) - Create a new identity
* [Activate Identity](/api-reference/identity/activate-identity) - Activate an identity
* [Check Availability](/api-reference/identity/check-availability) - Check name availability

### Trust Scores

* [Get Score](/api-reference/scores/get-score) - Get user's trust score
* [Get Breakdown](/api-reference/scores/get-breakdown) - Detailed score breakdown
* [Get History](/api-reference/scores/get-history) - Historical score data
* [Get Leaderboard](/api-reference/scores/get-leaderboard) - Global leaderboard

### Achievements

* [List Achievements](/api-reference/achievements/list-achievements) - All available achievements
* [Get User Achievements](/api-reference/achievements/get-user-achievements) - User's achievements
* [Claim Achievement](/api-reference/achievements/claim-achievement) - Claim an achievement
* [Get Progress](/api-reference/achievements/get-progress) - Achievement progress

### Trading

* [Get Trading Stats](/api-reference/trading/get-stats) - User's trading statistics
* [Get Trading History](/api-reference/trading/get-history) - Trade history
* [Get Trading Leaderboard](/api-reference/trading/get-leaderboard) - Trading leaderboard

### Trust Layer

* [Get Attestations](/api-reference/trust-layer/get-attestations) - User's attestations
* [Create Attestation](/api-reference/trust-layer/create-attestation) - Create attestation
* [Revoke Attestation](/api-reference/trust-layer/revoke-attestation) - Revoke attestation
* [Get Modules](/api-reference/trust-layer/get-modules) - Available modules
* [Evaluate Policy](/api-reference/trust-layer/evaluate-policy) - Evaluate trust policy

### Developer Tools

* [Create API Key](/api-reference/developer/create-api-key) - Generate new API key
* [List API Keys](/api-reference/developer/list-api-keys) - List your API keys
* [Revoke API Key](/api-reference/developer/revoke-api-key) - Revoke an API key
* [Get Usage](/api-reference/developer/get-usage) - API usage statistics

## Status Codes

| Code | Description           |
| ---- | --------------------- |
| 200  | Success               |
| 201  | Created               |
| 400  | Bad Request           |
| 401  | Unauthorized          |
| 403  | Forbidden             |
| 404  | Not Found             |
| 429  | Rate Limit Exceeded   |
| 500  | Internal Server Error |
| 503  | Service Unavailable   |

## Support

Need help? Contact us:

* **Email**: [support@onzks.com](mailto:support@onzks.com)
* **Discord**: [Join our community](https://discord.gg/zkscore)
* **GitHub**: [Report issues](https://github.com/metalanddev/ZKScoreEVM/issues)

<Card title="Quick Start" icon="rocket" href="/quickstart">
  New to ZKScore? Start with our Quick Start guide
</Card>