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

# Rate Limits

> Understand Sharpe API rate limit tiers, monthly quotas, retry headers, 429 responses, and usage patterns for reliable integrations.

The Sharpe API enforces rate limits per API key to keep usage fair and the platform stable. Limits are applied as requests per minute and requests per month, and they come from your plan.

## Plans and limits

The API is paid-only: every key belongs to a plan, and there is no free tier. Each account has one API key. REST calls and [MCP](https://docs.sharpe.ai/mcp-server.md) tool calls use that key and draw on the same monthly quota.

| Plan | Requests / min | Requests / month | Price |
| - | - | - | - |
| **Hobbyist** | 30 | 50,000 | $29/month or $290/year |
| **Pro** | 120 | 300,000 | $79/month or $790/year |
| **Commercial** | 500 | 1,000,000 | $149/month or $1,490/year |
| **Enterprise** | Custom | Custom | [Contact us](https://www.sharpe.ai/contact) |

Hobbyist is for personal projects and Pro for personal trading and research. Commercial covers use inside your own product; reselling the data is not allowed. A year costs ten months.

### Trial

Every account gets one trial before it needs a plan: 7 days and 250 requests, at 10 requests a minute, across REST and MCP. Create a key at [/dashboard/api-keys](https://www.sharpe.ai/dashboard/api-keys); no payment is asked for. The 7 days start with the key's first request. A key issued before 2026-11-11 gets the same trial, starting with its first request after that day. When the 7 days are over the key answers `401 expired_api_key`, and when the 250 requests are used it answers `429 monthly_quota_exceeded`, until the account has a plan. Paying keeps the same key.

The monthly quota resets on the 1st of each month (UTC), whatever day your plan started.

### Paying and renewing

Plans are paid in USDC, or in any token swapped at checkout, through MoonPay Commerce at [/dashboard/billing](https://www.sharpe.ai/dashboard/billing). There is no card payment and nothing is charged automatically: you get a renewal reminder on each of the 5 days before the paid period ends, and the key keeps working for 3 days after it. Then the key stops and answers `401 expired_api_key` until you renew; the same key works again once the plan is active. An upgrade starts a new paid period.

> [!NOTE]
>
> Creating a key needs an active plan or an unused trial: with neither, key
> creation answers `402`. Choose a plan at [/pricing](https://www.sharpe.ai/pricing).

## Rate limit and quota headers

Every authenticated v1 API response includes headers so you can track per-minute rate limits and monthly quota usage in real time:

**X-RateLimit-Limit** `integer`

Maximum requests allowed per minute on your plan.

**X-RateLimit-Remaining** `integer`

Requests remaining in the current one-minute window.

**X-RateLimit-Reset** `integer`

Unix timestamp (seconds) when the current window resets.

**X-Quota-Limit** `integer`

Monthly request quota of your plan.

**X-Quota-Remaining** `integer`

Monthly requests remaining in the current billing period.

**X-Quota-Reset** `string`

ISO 8601 timestamp when the monthly quota resets. Included when the quota store returns a reset timestamp.

**X-Request-Id** `string`

Unique identifier for this request. Include when contacting support.

```bash Example response headers theme={null}
HTTP/2 200
x-ratelimit-limit: 30
x-ratelimit-remaining: 27
x-ratelimit-reset: 1743062460
x-quota-limit: 50000
x-quota-remaining: 49812
x-quota-reset: 2026-12-01T00:00:00.000Z
x-request-id: req_abc123def456
```

***

## 429 Too Many Requests

Both limits return a `429`: the per-minute rate limit with type `rate_limit_exceeded`, and the monthly quota with type `monthly_quota_exceeded`. Both are temporary and retryable, and both carry a `Retry-After` header with the seconds until the limit reopens.

The response body follows the standard [RFC 9457 error format](https://docs.sharpe.ai/errors.md). The `type` and `detail` fields tell you whether you hit the per-minute rate limit or the monthly quota.

### Response properties

**type** `string`

`rate_limit_exceeded` for per-minute limits, `monthly_quota_exceeded` for monthly caps. Both return status `429`.

**detail** `string`

Human-readable explanation of which limit was exceeded.

**doc\_url** `string`

Link to relevant documentation page for the error.

> [!NOTE]
>
> Quota exhaustion used to answer `403`, which tells most HTTP clients and
> agent frameworks never to retry. It is now a `429` so a key that will work
> again at the next monthly reset is not permanently parked.

```json 429 response body theme={null}
{
  "type": "https://www.sharpe.ai/errors/rate_limit_exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit of 30 requests per minute exceeded.",
  "request_id": "req_abc123def456",
  "doc_url": "https://www.sharpe.ai/docs/rate-limits",
  "suggested_action": "Wait until the time in the X-RateLimit-Reset header before retrying. Upgrade your plan for higher limits."
}
```

```bash 429 response headers theme={null}
HTTP/2 429
x-ratelimit-limit: 30
x-ratelimit-remaining: 0
x-ratelimit-reset: 1743062472
x-quota-limit: 50000
x-quota-remaining: 49811
x-quota-reset: 2026-12-01T00:00:00.000Z
retry-after: 12
x-request-id: req_abc123def456
```

```json Monthly quota response body theme={null}
{
  "type": "https://www.sharpe.ai/errors/monthly_quota_exceeded",
  "title": "Monthly Quota Exceeded",
  "status": 429,
  "detail": "Monthly quota of 50,000 requests exceeded. Resets at 2026-12-01T00:00:00.000Z.",
  "request_id": "req_abc123def456",
  "doc_url": "https://www.sharpe.ai/docs/rate-limits",
  "suggested_action": "Retry after the seconds given in the Retry-After header, when the monthly quota resets. Upgrade your plan for a higher monthly quota. Check usage at GET /v1/usage."
}
```

***

## Best practices

### Monitor your usage

Read `X-RateLimit-Remaining` and `X-Quota-Remaining` on every authenticated v1 response. When either drops below 10% of its limit, slow down, queue requests, or move heavy jobs to the next reset window.

### Implement backoff

When you receive a 429, use the `Retry-After` header when present, or fall back to `X-RateLimit-Reset` to calculate how long to wait before retrying. A `monthly_quota_exceeded` 429 sets `Retry-After` to the seconds until the quota resets, which can be days: queue the work rather than spinning on retries.

```ts Backoff example theme={null}
async function fetchWithRetry(url: string, headers: HeadersInit) {
  const res = await fetch(url, { headers })

  if (res.status === 429) {
    const retryAfter = parseInt(res.headers.get('Retry-After') ?? '0', 10)
    const reset = parseInt(res.headers.get('X-RateLimit-Reset') ?? '0', 10)
    const waitMs = retryAfter > 0
      ? retryAfter * 1000
      : Math.max(reset * 1000 - Date.now(), 1000)
    await new Promise((resolve) => setTimeout(resolve, waitMs))
    return fetch(url, { headers })
  }

  return res
}
```

### Cache responses

Many Sharpe API endpoints return data that updates on a known schedule (for example, current funding rates refresh every 5 minutes, while heatmap data refreshes every 3 hours). Cache responses locally and respect `Cache-Control` headers to avoid redundant requests.

### Use bulk endpoints

Prefer endpoints that return data for multiple symbols in a single request rather than making one request per symbol. For example, `/v1/funding/rates?type=current` without a `coin` parameter returns all rates at once.

[Learn about authentication](https://docs.sharpe.ai/authentication.md)


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