> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fhsc.com.vn/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> API chính thức để tích hợp dữ liệu thị trường, thông tin tài khoản và lịch sử giao dịch của Finhay Securities.

Finhay Securities Open API cho phép đối tác và developer truy cập dữ liệu
thị trường (giá realtime, lịch sử OHLCV, tin tức, dữ liệu vĩ mô, …) cùng
thông tin tài khoản / danh mục / lệnh của user thông qua HTTP/REST.

## Bắt đầu nhanh

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Gọi request đầu tiên trong 5 phút — không cần signing.
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    2 tier xác thực: API key đơn giản và HMAC signing đầy đủ.
  </Card>

  <Card title="Bootstrap flow" icon="play" href="/bootstrap-flow">
    Lấy `userId` và `subAccountId` để gọi các endpoint tài khoản.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Đặc tả OpenAPI 3.1 đầy đủ kèm form gọi thử endpoint trực tiếp.
  </Card>
</CardGroup>

## Mô hình xác thực

API chia 2 tier theo mức độ nhạy cảm của dữ liệu:

| Tier       | Endpoint                                                                                                                               | Header bắt buộc                                                                                    |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Tier 1** | Dữ liệu thị trường công khai (`GET /market/**`, `GET /trading/market/**`, `GET /trading/securities/**`, `GET /fund-trading/public/**`) | `X-FH-APIKEY`                                                                                      |
| **Tier 2** | Tài khoản, danh mục, lệnh, PnL của user                                                                                                | `X-FH-APIKEY` + `X-FH-TIMESTAMP` + `X-FH-NONCE` + `X-FH-SIGNATURE` (+ `X-FH-BODYHASH` khi có body) |

Chi tiết thuật toán signing: [Authentication](/authentication).

## URL Production

```
https://open-api.fhsc.com.vn
```

## Lấy API key

Đăng nhập tài khoản Finhay rồi truy cập trang
[Quản lý API](https://invest.fhsc.com.vn/quan-ly-api) để tạo cặp
`FINHAY_API_KEY` / `FINHAY_API_SECRET`.

<Warning>
  **Bảo mật API key và Secret key là trách nhiệm của bạn.**

  * **Không** commit key vào git, **không** dán vào client-side code
    (browser / mobile bundle), **không** chia sẻ qua chat / email /
    screenshot.
  * Lưu key trong biến môi trường (`.env` đã gitignore) hoặc secret
    manager (AWS Secrets Manager, Vault, GCP Secret Manager, …).
  * Mọi request đi từ key của bạn được xem là do bạn thực hiện —
    Finhay không chịu trách nhiệm cho thiệt hại phát sinh khi key bị
    rò rỉ do lỗi phía client.
  * Nếu nghi ngờ key đã rò rỉ → vào trang [Quản lý API](https://invest.fhsc.com.vn/quan-ly-api)
    để **revoke ngay** và tạo cặp key mới.
</Warning>

## Tham khảo nhanh

<CardGroup cols={2}>
  <Card title="Error codes" icon="circle-exclamation" href="/errors">
    Bảng tra cứu mã lỗi và HTTP status mapping.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/rate-limits">
    Giới hạn request và chiến lược retry.
  </Card>
</CardGroup>