> ## Documentation Index
> Fetch the complete documentation index at: https://coinstats.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Understanding the credit-based rate limiting system

The CoinStats API uses a credit-based system for rate limiting. Different endpoints consume different amounts of credits based on the complexity and data requirements of the request.

## Credit System

Each API request consumes a specific number of credits:

| Endpoint Category | Credit Cost   | Description                                                           |
| ----------------- | ------------- | --------------------------------------------------------------------- |
| Basic Market Data | 1-2 credits   | Simple data like coin lists, basic info                               |
| Detailed Data     | 3-5 credits   | Historical charts, detailed analytics                                 |
| Wallet Operations | 40-50 credits | Wallet balance, transaction sync (4,000 for HD wallet xpub/ypub/zpub) |
| Portfolio Data    | 8-10 credits  | Portfolio management features                                         |
| DeFi Data         | 400 credits   | Comprehensive DeFi portfolio data                                     |

## Managing Your Credits

### Check Your Usage

Monitor your credit usage through the CoinStats dashboard or programmatically via the API.

<Card title="Check Credit Usage" icon="gauge" href="/openapi/get-credit-usage">
  Use the `/usage/credits` endpoint to check your remaining credits programmatically.
</Card>

```bash theme={null}
curl -X GET "https://api.coinstats.app/v1/usage/credits" \
  -H "X-API-KEY: your-api-key"
```

**Response:**

```json theme={null}
{
  "totalCredits": 20000,
  "usedCredits": 9000,
  "remainingCredits": 11000,
  "subscription": "FREE"
}
```

<Note>The `/usage/credits` endpoint is free and does not consume any credits.</Note>

### Plan Limits

Different subscription plans have different credit limits:

| Plan           | Credits/Month | Rate Limit  | Price         |
| -------------- | ------------- | ----------- | ------------- |
| **Free**       | 20,000        | 2 req/sec   | Free          |
| **Starter**    | 1,000,000     | 30 req/sec  | \$49/month    |
| **Pro**        | 5,000,000     | 30 req/sec  | \$199/month   |
| **Business**   | 80,000,000    | 100 req/sec | \$999/month   |
| **Enterprise** | Custom        | Custom      | Contact sales |

<Card title="Plans & Pricing" icon="gem" href="https://openapi.coinstats.app/pricing">
  View full pricing details and features
</Card>

### Best Practices

* **Cache responses**: Store frequently requested data locally
* **Batch requests**: Combine multiple requests when possible
* **Monitor usage**: Track your credit consumption
* **Optimize queries**: Use filters to reduce data transfer

## Error Responses

When you exceed your credit limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "message": "Insufficient credits for this request"
}
```

## Credit Reset

Credits are typically reset monthly based on your subscription plan.