> ## Documentation Index
> Fetch the complete documentation index at: https://coinstats.app/api-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.

> **[Check Credit Usage](/api-docs/api-docs/openapi/get-credit-usage)**
>
> Use the `/usage/credits` endpoint to check your remaining credits programmatically.

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

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

> **[Plans & Pricing](https://openapi.coinstats.app/pricing)**
>
> View full pricing details and features

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

### Coin List Batch Limit

`GET /v1/coins` accepts a maximum of **100 coin IDs** in the comma-separated
`coinIds` query parameter. Split larger sets across multiple requests. The
`limit` parameter controls response pagination and does not increase the
100-ID batch limit.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.