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

# Quy ước API

> Quy ước về yêu cầu, phản hồi, phân trang, thời gian và lỗi

<div style={{ width: '100%', height: 240, marginBottom: 32, borderRadius: 16, overflow: 'hidden', position: 'relative' }}>
  <video style={{ width: '100%', height: '100%', objectFit: 'cover', filter: 'sepia(0.3) saturate(1.5) hue-rotate(-14deg) brightness(0.72) contrast(1.12)' }} autoPlay loop muted playsInline>
    <source src="https://mintcdn.com/vero-fa5575b5/G_sL_RHXpWEXOwUp/images/bg_video.mp4?fit=max&auto=format&n=G_sL_RHXpWEXOwUp&q=85&s=f731a6a676fb99a2368193fbaf3281ee" type="video/mp4" data-path="images/bg_video.mp4" />
  </video>
</div>

<div style={{ width: '100%', height: 4, marginBottom: 24, borderRadius: 2, background: 'rgba(0,0,0,0.08)' }}>
  <div style={{ width: '37.5%', height: '100%', borderRadius: 2, background: 'linear-gradient(90deg, var(--accent-primary) 0%, var(--accent-light) 50%, var(--accent-dark) 100%)' }} />
</div>

## Base URL và xác thực

Dùng base URL công khai và gửi API key trong header được cung cấp khi cấp quyền truy cập.

```bash theme={null}
curl --request GET   --url "https://api-gw.verolabs.co/v1/instruments?limit=5"   --header "X-API-KEY: $API_KEY"
```

## Cấu trúc phản hồi

Các endpoint dạng danh sách trả đối tượng có `data`. Endpoint hỗ trợ phân trang bằng cursor có thể trả thêm `next_cursor`.

```json theme={null}
{
  "data": [
    { "symbol": "BTCUSDT" }
  ],
  "next_cursor": "..."
}
```

Endpoint chi tiết trả một đối tượng tài nguyên.

## Phân trang

| Param    | Ý nghĩa                                       |
| -------- | --------------------------------------------- |
| `limit`  | Số item tối đa trả về trong một yêu cầu       |
| `cursor` | Token lấy từ `next_cursor` của phản hồi trước |

<Info>
  Cursor là token không nên tự diễn giải. Client không nên giải mã hoặc tự tạo cursor.
</Info>

## Tham số thời gian

`from` và `to` phải dùng ISO 8601 UTC.

| Hợp lệ                     | Không hợp lệ                |
| -------------------------- | --------------------------- |
| `2026-05-15T00:00:00Z`     | `2026-05-15 00:00:00`       |
| `2026-05-15T00:00:00.123Z` | `2026-05-15T07:00:00+07:00` |

## Định dạng lỗi

Lỗi được trả theo định dạng JSON problem.

```json theme={null}
{
  "type": "invalid-param",
  "title": "Invalid query parameter",
  "status": 400,
  "detail": "param 'from' is required"
}
```

| Status | Ý nghĩa                                        |
| ------ | ---------------------------------------------- |
| `400`  | Thiếu hoặc sai tham số yêu cầu                 |
| `401`  | Thiếu hoặc sai thông tin xác thực              |
| `404`  | Tài nguyên không tồn tại                       |
| `422`  | Đúng định dạng nhưng giá trị không được hỗ trợ |
| `429`  | Vượt giới hạn yêu cầu của tài khoản            |
| `503`  | API tạm thời không sẵn sàng                    |