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

# Authentication

> API keys, rate-limit headers, tier behavior, and error responses.

Every request to `api.coinversa.ai/api/public/v1/*` requires an API key. Get one at [developers.coinversa.ai](https://developers.coinversa.ai).

This page is about the **REST API**. The [WebSocket](https://docs.coinversa.ai/websocket/overview.md) uses the same key but a different protocol: a Bearer token on the upgrade (or the `bearer` subprotocol from a browser), refusals as HTTP `401` / `429` / `503` or close codes rather than problem details, and capacity limits rather than request quotas. Its rules live in [WebSocket authentication](https://docs.coinversa.ai/websocket/overview.md#authentication), not here.

## Sending the key

Pass your key in the `X-API-Key` header on every request:

```bash theme={null}
curl https://api.coinversa.ai/api/public/v1/pulse/stats \
  -H "X-API-Key: cvsa_..."
```

That's it — no OAuth, no bearer prefix, no signing. (The REST API ignores an `Authorization: Bearer` header entirely; that header is how the [WebSocket](https://docs.coinversa.ai/websocket/overview.md#authentication) authenticates.)

> [!WARNING]
>
> Never commit your key to a public repo, and never ship it in a page served to other people — a key in someone else's browser is a key you have published. For a REST call from a browser, keep the key on a server you control and proxy the request. The [WebSocket](https://docs.coinversa.ai/websocket/overview.md#authentication) can be opened directly from **your own** browser tools with the `bearer` subprotocol; the same publishing rule applies. Use a separate key per environment so you can rotate without disrupting other clients.

## Tiers

Your key's tier is set by your active subscription. Free is the default; paid tiers are managed in the [billing portal](https://developers.coinversa.ai/billing).

| Tier | Rate / min | Per day | Per month | Keys | Price |
| - | -: | -: | -: | -: | -: |
| Free | 30 | 1,000 | unlimited | 1 | \$0 |
| Starter | 120 | 2,000 | 50,000 | 3 | \$29 / mo |
| Agent | 300 | 10,000 | 250,000 | 5 | \$49 / mo |
| Pro | 600 | 20,000 | 500,000 | 10 | \$199 / mo |
| Enterprise | 10,000+ | unlimited | unlimited | unlimited | from \$1,999 / mo |

See [pricing](https://docs.coinversa.ai/pricing.md) for what each tier unlocks.

> [!NOTE]
>
> **Access is checked per key; request usage is shared by account.** Additional keys do not multiply your REST RPM or daily/monthly allowance. A key serves the tier it was provisioned at, capped by your account's active entitlement — a Free key calling alongside an unused Pro key on the same account still has Free endpoint access and daily/monthly caps. See [how tier resolution works](https://docs.coinversa.ai/api-reference/tiers.md#how-tier-resolution-works).

## Rate-limit headers

Authenticated responses include these, 429s included:

| Header | Meaning |
| - | - |
| `X-RateLimit-Tier` | Tier resolved for this request (`free`, `starter`, `agent`, `pro`, `enterprise`) |
| `X-RateLimit-Remaining` | Minimum remaining tokens across the account minute and per-route buckets |
| `X-RateLimit-Next` | Time until the next token is available across the checked buckets (a duration string, e.g. `12.4s`), not a full-window refill |
| `X-RateLimit-Route` | Remaining allowance on the per-route limit, where one applies |
| `X-RateLimit-Daily` | Requests remaining today (only on tiers with a daily cap) |
| `X-RateLimit-Monthly` | Requests remaining this billing month (only on tiers with a monthly cap) |
| `X-RateLimit-Scope` | Identity the limits were counted against: `account` (keyed request) or `ip` |
| `X-RateLimit-Reset` | Unix seconds when the next token is available |
| `X-RateLimit-Daily-Reset` / `X-RateLimit-Monthly-Reset` | Unix seconds when the daily / monthly allowance resets (only on tiers with that cap) |
| `Retry-After` | Seconds to wait before retrying (on `429` only) |
| `X-Billing-State` / `X-Billing-Grace-Expires` | Present only during a payment grace window: the state (`grace`) and when the window ends |

## Error responses

All errors are JSON **problem details**: `title`, `status`, a human-readable `detail`, a machine-matchable `code` (retained for compatibility) and, when available, a more specific `reason` (`missing_api_key`, `invalid_api_key`, `insufficient_tier`, `invalid_parameters` or `account_suspended`). Match on `reason` when present, else `code` — the `detail` wording can change. There is no 401 in this API: every auth failure is a `403`.

> [accordion] 403 Forbidden — missing key (code TIER\_GATE)
>
> ```json theme={null}
> {
>   "title": "Forbidden",
>   "status": 403,
>   "detail": "Api key needed for this request",
>   "code": "TIER_GATE",
>   "reason": "missing_api_key",
>   "current_tier": "none",
>   "required_tier": "free",
>   "upgrade_url": "https://coinversa.ai/developers#pricing"
> }
> ```
>
> Action: include the `X-API-Key` header. `required_tier` names the minimum tier for the endpoint — even `free` endpoints need a key. A key that is recognized but inactive gets this same `Api key needed` body with `reason` `invalid_api_key`.

> [accordion] 403 Forbidden — invalid key (code FORBIDDEN)
>
> ```json theme={null}
> {
>   "title": "Forbidden",
>   "status": 403,
>   "detail": "Invalid API key",
>   "code": "FORBIDDEN",
>   "reason": "invalid_api_key"
> }
> ```
>
> Action: check the key isn't revoked or rotated in the [portal](https://developers.coinversa.ai/keys).

> [accordion] 403 Forbidden — insufficient tier (code TIER\_GATE)
>
> ```json theme={null}
> {
>   "title": "Forbidden",
>   "status": 403,
>   "detail": "Tool not available for current tier, must be pro or higher",
>   "code": "TIER_GATE",
>   "reason": "insufficient_tier",
>   "current_tier": "starter",
>   "required_tier": "pro",
>   "upgrade_url": "https://coinversa.ai/developers#pricing"
> }
> ```
>
> `required_tier` is one of `starter`, `agent`, `pro` or `enterprise` — tiers rank `free` \< `starter` \< `agent` \< `pro` \< `enterprise`.
>
> Action: upgrade at `upgrade_url`, or (for [builder endpoints](https://docs.coinversa.ai/api-reference/builders.md)) fall back to the endpoint's [x402 pay-per-call twin](https://docs.coinversa.ai/api-reference/tiers.md#x402-pay-per-call). Agents: report `required_tier` to the human rather than retrying.

> [accordion] 403 Forbidden — account suspended (code ACCOUNT\_SUSPENDED)
>
> ```json theme={null}
> {
>   "title": "Forbidden",
>   "status": 403,
>   "detail": "Account flagged for suspicious activity, check email or contact support",
>   "code": "ACCOUNT_SUSPENDED",
>   "reason": "account_suspended"
> }
> ```
>
> Action: check your email or contact support. Do not retry or upgrade — the hold applies to every key on the account.

> [accordion] 429 Too Many Requests — per-minute rate limit (code RATE\_LIMITED)
>
> ```json theme={null}
> {
>   "title": "Too Many Requests",
>   "status": 429,
>   "detail": "Rate limit exceeded for requests (Exceeded requests per minute)",
>   "code": "RATE_LIMITED"
> }
> ```
>
> Action: wait the number of seconds in `Retry-After` (or until `X-RateLimit-Reset`), or upgrade for higher RPM.

> [accordion] 429 Too Many Requests — daily or monthly cap (code RATE\_LIMITED)
>
> ```json theme={null}
> {
>   "title": "Too Many Requests",
>   "status": 429,
>   "detail": "Exceeded daily and/or monthly request allowance update plan or wait for next reset",
>   "code": "RATE_LIMITED"
> }
> ```
>
> Action: the daily window resets at 00:00 UTC; the monthly bucket at your billing period boundary. `Retry-After` gives the seconds to wait, and `X-RateLimit-Daily-Reset` / `X-RateLimit-Monthly-Reset` give the reset times. Or upgrade.

> [accordion] 502 Bad Gateway (code BAD\_GATEWAY)
>
> The upstream Hyperliquid endpoint timed out or returned an error. Retry with backoff. (The MCP server retries timeouts and short-lived 429s, not 502s.)

> [!NOTE]
>
> **No key at all?** Every GET endpoint has a keyless [x402 pay-per-call twin](https://docs.coinversa.ai/api-reference/tiers.md#x402-pay-per-call) — payment is negotiated per request via the x402 protocol instead of a subscription. The [builder analytics endpoints](https://docs.coinversa.ai/api-reference/builders.md) are the documented x402 surface today.

## Historical-window caps

Caller-controlled history windows (`since`, `hours`/`days` params, explicit `startTime`/`endTime` ranges) are capped at **90 days** on every tier — the cap is universal, not tier-based. How a route enforces it differs: routes with a documented `since` **ceiling reject** an overlong window with a `400` (`since=<value> exceeds this route's <ceiling> ceiling`), while the rest run against the capped window and may echo the range you asked for. Compare response timestamps against your requested range to detect truncation, and see [data windows](https://docs.coinversa.ai/api-reference/data-windows.md) for the per-route ceilings. Risk endpoints (`/live/risk/liquidations/*`, etc.) are additionally clamped to data starting `2026-01-01` (the day we began collecting L1 liquidation events).

Longer windows are available on Enterprise as custom exports and negotiated data delivery, not as an API parameter. See [Data windows](https://docs.coinversa.ai/api-reference/data-windows.md) for per-endpoint window semantics.

## Usage logging

Authenticated requests that pass the access and rate-limit checks are logged with the response time and status code so you can audit usage in **Usage** in the portal. Logs include endpoint, method, IP, and user-agent — but never the key itself (only the SHA-256 hash).


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