> ## 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.

# Quickstart

> Gọi request đầu tiên trong 5 phút — không cần HMAC signing.

Hướng dẫn nhanh cách gọi endpoint Tier 1 đầu tiên — chỉ cần 1 header
`X-FH-APIKEY`. Sau khi quen, bạn có thể chuyển sang Tier 2 với HMAC
signing đầy đủ ở [Authentication](/authentication).

<Steps>
  <Step title="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` và `FINHAY_API_SECRET`. API key Tier 1 không cần
    secret — chỉ dùng để gọi các endpoint dữ liệu thị trường.

    Lưu key vào biến môi trường:

    ```bash theme={null}
    export FINHAY_API_KEY="<key của bạn>"
    ```
  </Step>

  <Step title="Gọi request đầu tiên">
    Lấy giá realtime của cổ phiếu VNM:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -H "X-FH-APIKEY: $FINHAY_API_KEY" \
        "https://open-api.fhsc.com.vn/market/stock-realtime?symbol=VNM"
      ```

      ```typescript TypeScript theme={null}
      const res = await fetch(
        "https://open-api.fhsc.com.vn/market/stock-realtime?symbol=VNM",
        { headers: { "X-FH-APIKEY": process.env.FINHAY_API_KEY! } }
      );
      const json = await res.json();
      console.log(json.result);
      ```

      ```python Python theme={null}
      import os, requests

      res = requests.get(
          "https://open-api.fhsc.com.vn/market/stock-realtime",
          params={"symbol": "VNM"},
          headers={"X-FH-APIKEY": os.environ["FINHAY_API_KEY"]},
      )
      print(res.json()["result"])
      ```
    </CodeGroup>
  </Step>

  <Step title="Đọc response">
    Response trả về theo envelope chuẩn `{ error_code, message, result }`:

    ```json theme={null}
    {
      "error_code": "0",
      "message": "success",
      "result": {
        "symbol": "VNM",
        "price": 72500,
        "change": 500,
        "changePercent": 0.69,
        "ceiling": 77500,
        "floor": 67500,
        "exchange": "HOSE",
        "marketCap": 150000000000000
      }
    }
    ```

    `error_code: "0"` nghĩa là thành công. Mọi mã khác `"0"` là lỗi —
    xem [Errors](/errors).
  </Step>

  <Step title="Khám phá thêm">
    <CardGroup cols={2}>
      <Card title="Thêm endpoint Tier 1" icon="chart-line" href="/api-reference">
        Lịch sử OHLCV, tin tức, vĩ mô, vàng/bạc/crypto, lịch sự kiện kinh tế.
      </Card>

      <Card title="Truy cập tài khoản" icon="key" href="/authentication">
        Tier 2 với HMAC signing — đọc số dư, danh mục, sổ lệnh.
      </Card>
    </CardGroup>
  </Step>
</Steps>

## Bước tiếp

* Nếu chỉ dùng dữ liệu thị trường công khai → tiếp tục với các endpoint
  trong [API Reference](/api-reference) thuộc các tag *Dữ liệu giao dịch*,
  *Hàng hoá*, *Kinh tế vĩ mô*, *Phân tích cơ bản*.
* Nếu cần truy cập tài khoản user → đọc [Authentication](/authentication)
  để setup HMAC signing, sau đó chạy [Bootstrap flow](/bootstrap-flow) để
  lấy `userId` + `subAccountId`.