# Quick Start

Quantis v3 serves the same Venezuelan exchange-rate data as v2, with the same endpoints and response bodies. What changes is how you get access: API keys are created at [center.quantis.vzla.io](https://center.quantis.vzla.io), and usage is tracked per account under a tier.

1. **Create your API key**

   Go to [center.quantis.vzla.io](https://center.quantis.vzla.io), sign up with your email and create a key. Copy it immediately: the raw key is shown only once.

   Keys look like this:

   ```
   qapi_a1b2c3d4e5f6...
   ```

2. **Make your first request**

   Pass your key in the `Authorization` header:

   ```bash
   curl --request GET \
     --url 'https://app.vzla.io/api/quantis/v3/rates/bcv/' \
     --header 'Authorization: Bearer qapi_YOUR_KEY_HERE'
   ```

3. **Read the response**

   A successful response wraps data in the `{data, meta}` envelope:

   ```json
   {
     "data": {
       "current": {
         "valid_date": "2026-05-06",
         "timestamp": "2026-05-06T09:32:03.108501+00:00",
         "rates": {
           "USD": {
             "rate": "493.37650000",
             "indicator_pct": "0.78066864",
             "indicator_amount": "3.82180000"
           },
           "EUR": { "...": "..." }
         }
       },
       "next": null
     },
     "meta": {
       "source": "BCV",
       "currency_quote": "VES"
     }
   }
   ```

## Base URL

```
https://app.vzla.io/api/quantis/v3/
```

## Authentication

Every request, including [My Quota](/quantis/v3/me/quota/), must include:

```http
Authorization: Bearer qapi_YOUR_KEY_HERE
```

Requests without a valid key, or with a key you revoked at [center.quantis.vzla.io](https://center.quantis.vzla.io), return `401 Unauthorized`.

## Quota and rate limit

Your monthly quota belongs to your account and is shared by all its keys. Every call except [My Quota](/quantis/v3/me/quota/) counts 1 request. Every tier also has a per-second rate limit. See [Tiers and limits](/quantis/v3/tiers-and-limits/) for how both work and how to handle a `429`.

## Endpoints

| Endpoint | What it returns | Cache |
|---|---|---|
| [`GET /api/quantis/v3/rates/bcv/`](/quantis/v3/rates/bcv/) | Official BCV rates (USD, EUR, CNY, TRY, RUB) | 60 min |
| [`GET /api/quantis/v3/rates/markets/`](/quantis/v3/rates/markets/) | USDT Binance rate + AVG + DIFF vs BCV | 5 min |
| [`GET /api/quantis/v3/rates/banks/`](/quantis/v3/rates/banks/) | Per-bank buy/sell/avg rates | 30 min |
| [`GET /api/quantis/v3/rates/international/`](/quantis/v3/rates/international/) | ~170 world currencies (USD base) | 30 min |
| [`GET /api/quantis/v3/rates/crypto/`](/quantis/v3/rates/crypto/) | USD prices for BTC, ETH, USDT and more | 5 min |
| [`GET /api/quantis/v3/rates/history/`](/quantis/v3/rates/history/) | Last 30 daily closing rates | Until end of day |
| [`GET /api/quantis/v3/holidays/`](/quantis/v3/holidays/) | Venezuelan bank and public holidays | 24 h |
| [`GET /api/quantis/v3/me/quota/`](/quantis/v3/me/quota/) | Your tier and usage (no quota used) | None |

## Error format

All errors follow a standard envelope. `details` is only present when there is something to add:

```json
{
  "error": {
    "code": "auth_token_unknown",
    "message": "Invalid token format"
  }
}
```

| Error code | HTTP status | Meaning |
|---|---|---|
| `invalid_parameter` | 400 | A query parameter is invalid, e.g. `year` or `type` on [Holidays](/quantis/v3/holidays/) |
| `auth_missing` | 401 | No `Authorization` header sent |
| `auth_token_unknown` | 401 | Key unknown, malformed or revoked |
| `quota_exceeded` | 429 | Your account's monthly quota is spent. It resets on the 1st |
| `throttled` | 429 | Too many requests per second. Wait the seconds in the `Retry-After` header (also in `details.retry_after`) |
**Caution:** v3 keys are separate from v2 tokens. A v2 `vzlaio_...` token will not authenticate against v3 endpoints, and a `qapi_...` key will not work on v2. Create a v3 key at [center.quantis.vzla.io](https://center.quantis.vzla.io).