# Quick Start

sidebar:
  order: 1

Quantis v2 is a new, richer API surface for Venezuelan exchange-rate data. It uses separate tokens from v1, a new response envelope, and dedicated endpoints per data source.

1. **Create your API token**

   Open the vzla.io mobile app, go to **Settings → API → Generate token**. Copy it immediately — the raw token is shown only once.

   Tokens look like this:

   ```
   vzlaio_a1b2c3d4e5f6...
   ```

2. **Make your first request**

   Pass your token in the `Authorization` header:

   ```bash
   curl --request GET \
     --url 'https://app.vzla.io/api/quantis/v2/rates/bcv/' \
     --header 'Authorization: Bearer vzlaio_YOUR_TOKEN_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"
     }
   }
   ```

## Authentication

Every request (except [My Quota](/quantis/v2/me/quota)) must include:

```http
Authorization: Bearer vzlaio_YOUR_TOKEN_HERE
```

Requests without a valid token return `401 Unauthorized`.

## Quota headers

Every response includes these headers so you can track usage without calling `/me/quota/`:

| Header | Description |
|---|---|
| `X-Quota-Limit` | Your monthly request limit |
| `X-Quota-Remaining` | Requests remaining this month |
| `X-Quota-Reset` | ISO 8601 timestamp of next quota reset |
| `X-Request-ID` | UUID for this request — include when contacting support |

Quotas reset on the **first day of each calendar month**. When you exceed your limit the API returns `429 Too Many Requests`.

## Endpoints

| Endpoint | What it returns | Cache |
|---|---|---|
| [`GET /api/quantis/v2/rates/bcv/`](/quantis/v2/rates/bcv) | Official BCV rates (USD, EUR, CNY, TRY, RUB) | 60 min |
| [`GET /api/quantis/v2/rates/markets/`](/quantis/v2/rates/markets) | USDT Binance rate + AVG + DIFF vs BCV | 5 min |
| [`GET /api/quantis/v2/rates/banks/`](/quantis/v2/rates/banks) | Per-bank buy/sell/avg rates | 30 min |
| [`GET /api/quantis/v2/rates/international/`](/quantis/v2/rates/international) | ~170 world currencies (USD base) | 30 min |
| [`GET /api/quantis/v2/rates/crypto/`](/quantis/v2/rates/crypto) | USD prices for BTC, ETH, USDT and more | 5 min |
| [`GET /api/quantis/v2/holidays/`](/quantis/v2/holidays) | Venezuelan bank and public holidays | 24 h |
| [`GET /api/quantis/v2/me/quota/`](/quantis/v2/me/quota) | Your current quota status (free, no quota used) | — |

## Error format

All errors follow a standard envelope:

```json
{
  "error": {
    "code": "auth_token_unknown",
    "message": "Invalid or inactive token.",
    "details": {}
  }
}
```

| Error code | HTTP status | Meaning |
|---|---|---|
| `auth_missing` | 401 | No `Authorization` header sent |
| `auth_token_unknown` | 401 | Token not found or inactive |
| `quota_exceeded` | 429 | Monthly limit reached |
**Note:** v2 tokens are separate from v1 tokens. A `gtbe_...` token will not authenticate against v2 endpoints.