# History

## GET /api/quantis/v2/rates/history/

Returns the most recent end-of-day **closing rates** — one entry per day, up to the last 30 days — newest first. A closing rate is the snapshot taken at the end of each day (America/Caracas timezone). Each entry is grouped exactly like the live endpoints: a `bcv` block (the official BCV rates, same shape as [GET /rates/bcv/](/quantis/v2/rates/bcv/)) and a `markets` block (the Binance P2P USDT rate plus the computed average and difference, same shape as [GET /rates/markets/](/quantis/v2/rates/markets/)). All rates are quoted in Venezuelan Bolivar (VES).

| | |
|---|---|
| **Method** | `GET` |
| **URL** | `https://app.vzla.io/api/quantis/v2/rates/history/` |
| **Authentication** | `Authorization: Bearer vzlaio_...` |
| **Parameters** | None |

### Request

```bash
curl --request GET \
  --url 'https://app.vzla.io/api/quantis/v2/rates/history/' \
  --header 'Authorization: Bearer vzlaio_YOUR_TOKEN_HERE'
```

---

### Response

#### `data`

An array of up to 30 closing-rate entries, ordered newest first.

| Field | Type | Description |
|---|---|---|
| `date` | string (ISO 8601 date) | The Caracas date of this closing rate, e.g. `"2026-06-17"` |
| `timestamp` | string (ISO 8601 datetime) | When the closing rate was recorded |
| `bcv` | object | Official BCV rates — same shape as [GET /rates/bcv/](/quantis/v2/rates/bcv/) |
| `markets` | object | Binance USDT rate plus computed reference rates — same shape as [GET /rates/markets/](/quantis/v2/rates/markets/) |
| `banks` | object | Bank buy/sell averages for USD across publishing banks — see below |
| `badges` | object | `{ is_bank_holiday, is_weekend }` flags for that date |

Each entry reuses the labels and structure of the live endpoints, so the history reads with the same vocabulary a client already knows.

#### `bcv`

| Field | Type | Description |
|---|---|---|
| `rates` | object | Map of currency code → rate object. Keys: `USD`, `EUR` |

#### `markets`

| Field | Type | Description |
|---|---|---|
| `usdt` | object | Binance P2P USDT rate (rate object + `market`) |
| `computed.average` | object | Midpoint between the BCV USD and USDT rates |
| `computed.difference` | object | USDT minus BCV USD (value under `amount`) |

#### `banks`

USD buy/sell averages computed across the banks that published rates for the
closing day (with a one-publishing-day grace window). Weekends and bank holidays
carry the previous business day's values forward.

| Field | Type | Description |
|---|---|---|
| `USD.buy_average` | object | Average BUY price across banks — `{ rate, indicator_pct, indicator_amount }` |
| `USD.sell_average` | object | Average SELL price across banks — `{ rate, indicator_pct, indicator_amount }` |
| `USD.bank_names` | string[] | Names of the banks included in the averages |

**Rate object** (entries under `bcv.rates`, `markets.usdt`, and `markets.computed.*`)

| Field | Type | Description |
|---|---|---|
| `rate` | string \| null | VES per 1 unit (`difference` uses `amount` instead) |
| `indicator_pct` | string \| null | Percentage change versus the previous closing rate |
| `indicator_amount` | string \| null | Absolute change versus the previous closing rate |
| `market` | string | Only on `markets.usdt` — always `"Binance"` |

#### `meta`

| Field | Type | Description |
|---|---|---|
| `source` | string | Always `"closing"` |
| `currency_quote` | string | Always `"VES"` — all rates are quoted in Venezuelan Bolivar |
| `count` | number | Number of entries returned (0–30) |
| `window_days` | number | Always `30` — the maximum window served |

---

### Response headers

| Header | Description |
|---|---|
| `X-API-Version` | `2.0` |
| `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 |

---

### Example response

```json
{
  "data": [
    {
      "date": "2026-06-17",
      "timestamp": "2026-06-17T23:59:01.482931+00:00",
      "bcv": {
        "rates": {
          "USD": {
            "rate": "493.37650000",
            "indicator_pct": "0.78066864",
            "indicator_amount": "3.82180000"
          },
          "EUR": {
            "rate": "577.52186207",
            "indicator_pct": "0.57960395",
            "indicator_amount": "3.32804999"
          }
        }
      },
      "markets": {
        "usdt": {
          "rate": "612.10000000",
          "indicator_pct": "0.67320000",
          "indicator_amount": "4.10000000",
          "market": "Binance"
        },
        "computed": {
          "average": {
            "rate": "552.73825000",
            "indicator_pct": "0.71840000",
            "indicator_amount": "3.96090000"
          },
          "difference": {
            "amount": "118.72350000",
            "indicator_pct": "0.23480000",
            "indicator_amount": "0.27820000"
          }
        }
      },
      "banks": {
        "USD": {
          "buy_average": {
            "rate": "612.10000000",
            "indicator_pct": "0.67320000",
            "indicator_amount": "4.10000000"
          },
          "sell_average": {
            "rate": "618.40000000",
            "indicator_pct": "0.71000000",
            "indicator_amount": "4.36000000"
          },
          "bank_names": ["BBVA Provincial", "Banesco", "Mercantil"]
        }
      },
      "badges": {
        "is_bank_holiday": false,
        "is_weekend": false
      }
    }
  ],
  "meta": {
    "source": "closing",
    "currency_quote": "VES",
    "count": 30,
    "window_days": 30
  }
}
```

---

### HTTP status codes

| Code | Meaning |
|---|---|
| `200 OK` | Success. |
| `401 Unauthorized` | Missing or invalid token. |
| `405 Method Not Allowed` | Only GET is supported. |
| `429 Too Many Requests` | Monthly quota exhausted. |
| `500 Internal Server Error` | Server error. Retry after a short delay. |

#### 401 — no Authorization header

```json
{
  "error": {
    "code": "auth_missing",
    "message": "Authentication credentials were not provided"
  }
}
```

#### 401 — invalid token

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

#### 429 response body

```json
{
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota limit exceeded.",
    "details": {
      "reset_at": "2026-06-01T00:00:00Z"
    }
  }
}
```
**Note:** A new closing rate is published once per day at the end of the day (America/Caracas). The history does not change during the day, so this endpoint is cached until the end of the current Caracas day.