Cài đặt thư viện Python finlens và lấy khoá API

Trang này đi từ máy chưa có gì tới lúc bạn cầm trong tay một DataFrame giá cổ phiếu: cài gói, lấy khoá API, chạy truy vấn đầu tiên, và kiểm chứng rằng mình đã cài đúng bản.

Cài đặt

python --version

pip install finlens

# Linux / macOS
export FINLENS_API_KEY="flk_..."

# Windows PowerShell
$env:FINLENS_API_KEY = "flk_..."

import finlens

client = finlens.client()        # đọc FINLENS_API_KEY
df = client.eod.stock.ohlcv("HPG", start="2026-01-01", end="2026-01-05")
print(df)

  symbol       date   open   high    low  close      volume
0    HPG 2026-01-05  23.57  23.70  22.94  23.17  59427911.0

Hai cách tạo khoá API

Trong extension VS Code (khuyến nghị)

Mở FinLens trên Activity Bar; ở Trang chủ, mục môi trường có nút API key → hộp thoại Tạo API key mới? → Thu hồi và tạo mới.

Cách này được khuyến nghị vì khoá lưu thẳng vào VS Code SecretStorage — không nằm trong file hay trong code, không hiện ở cell notebook nào. Để finlens.client() ở notebook và terminal đọc được khoá này tự động, chạy lệnh FinLens: Ghi API key ra file cấu hình (cho notebook và terminal ngoài): extension ghi khoá vào finlens.toml, và SDK đọc nó ở tầng thứ ba của Ba cách đưa khoá vào client — bạn không phải đặt biến môi trường bằng tay.

Chi tiết extension ở FinLens cho VS Code.

Trên finlens.vn

Đăng nhập finlens.vn → Cài đặt tài khoản → mục API key → Tạo API key mới. Sao chép khoá flk_... rồi đưa vào FINLENS_API_KEY hoặc finlens.toml như phần cấu hình bên dưới.

ta-lib là phụ thuộc bắt buộc

Từ bản 1.2.0, pip install finlens kéo thêm ta-lib — nó là nền của chỉ báo kỹ thuật. Đây là phụ thuộc bắt buộc, không phải một extra tuỳ chọn: df.finlens.rsi(14) có mặt trên mọi máy cài được finlens, nên bạn không phải học thuộc tính năng nào cần cài thêm gì.

Bạn không cần tự dựng thư viện C của TA-Lib. ta-lib phát hành wheel dựng sẵn cho mọi nền finlens hỗ trợ, và pip chọn đúng cái khớp máy bạn.

Nếu phần native của TA-Lib không nạp được — thường là sau khi copy một môi trường ảo sang máy khác — mọi lời gọi chỉ báo ném finlens.IndicatorError với mã FL_TA_UNAVAILABLE, và thông báo kèm sẵn lệnh chữa:

pip install --force-reinstall ta-lib

Đây là lỗi của riêng phần chỉ báo. Mọi lời gọi dữ liệu — client.eod.*, client.intraday.*, client.financials.* — vẫn chạy bình thường.

Ba cách đưa khoá vào client

Cấu hình được ghép từ nhiều tầng, ưu tiên từ cao xuống thấp: tham số truyền vào → biến môi trường FINLENS_* → file finlens.toml → mặc định.

import finlens

# 1. Truyền thẳng — tiện khi thử nhanh, đừng commit
client = finlens.client(api_key="flk_...")

# 2. Biến môi trường FINLENS_API_KEY — khuyến nghị
client = finlens.client()

# 3. File cấu hình, khi bạn có nhiều môi trường
client = finlens.client(profile="staging")

File cấu hình được tìm ở ./finlens.toml trước, rồi tới thư mục cấu hình của người dùng (%APPDATA%\finlens\config.toml trên Windows, ~/.config/finlens/config.toml trên Linux và macOS):

[default]
api_key = "flk_..."

[profile.staging]
api_key = "flk_..."

Tên profile cũng đọc được từ biến môi trường FINLENS_PROFILE.

Giữ khoá API an toàn

Đừng viết thẳng khoá vào mã nguồn rồi đẩy lên Git. Nếu buộc phải đọc khoá trong code, hãy đọc từ môi trường:

import os
import finlens

client = finlens.client(api_key=os.environ["FINLENS_API_KEY"])

Trong notebook dùng chung, finlens.client() không tham số là an toàn nhất: khoá không xuất hiện ở bất kỳ cell nào, nên nó cũng không nằm trong file .ipynb bạn gửi đi.

Nếu dùng file finlens.toml trong thư mục dự án, thêm nó vào .gitignore.

Kiểm tra cài đặt thành công

Bốn dòng dưới đây trả lời bốn câu hỏi khác nhau. Chạy hết chúng trước khi kết luận là "cài xong".

import finlens

finlens.__version__          # '1.1.1' — phải bắt đầu bằng số 1
client = finlens.client()    # khoá có đúng định dạng không (không chạm mạng)
client.status()              # service có sống không
client.whoami()              # khoá có thật sự dùng được không

client.whoami() là lời gọi đầu tiên thật sự đi ra mạng. Nó trả về gói dịch vụ, tình trạng khoá và hạn mức:

client.whoami()["account"]["tier"]        # 'pro'
client.limits()["requests_remaining"]     # 4783
client.limits()["max_symbols_per_request"]

client.status() không cần khoá hợp lệ — nó vẫn trả lời khi khoá sai hoặc đã hết hạn, nên đây là cách phân biệt "service đang có vấn đề" với "khoá của tôi có vấn đề".

Tạo client không chạm mạng

finlens.client() chỉ kiểm định dạng khoá tại chỗ; việc xác thực thật xảy ra ở lời gọi dữ liệu đầu tiên. Nhờ vậy đặt nó ở cell đầu notebook hay trong __init__ của một lớp không bao giờ hỏng vì một trục trặc mạng.

Muốn phát hiện khoá sai ngay lúc khởi động ứng dụng thì gọi connect() — nó chủ động chạy handshake:

client = finlens.client()
client.connect()             # ném lỗi ngay tại đây nếu khoá hỏng

Đóng client đúng cách

Client giữ một pool kết nối và một event loop chạy nền. Cả hai được đóng tự động lúc thoát interpreter, nên phần lớn script không phải làm gì. Khi muốn giải phóng sớm, dùng context manager:

import finlens

with finlens.client() as client:
    df = client.eod.stock.ohlcv(["HPG", "VCB"], start="2026-01-01")

# Đã đóng, không cần gọi client.close()

Bản bất đồng bộ bắt buộc dùng async with (hoặc await client.connect() trước lời gọi đầu tiên), vì engine phải được tạo trên chính event loop của bạn:

import finlens

async def main():
    async with finlens.AsyncClient() as client:
        df = await client.eod.stock.ohlcv("HPG")

Tuỳ chỉnh client

Mọi tham số đều bỏ trống được, và mỗi cái đều có biến môi trường tương ứng.

max_concurrency bị kẹp xuống theo giới hạn của gói dịch vụ sau lần handshake đầu tiên: sự thật của server thắng phỏng đoán của client.

deadline tồn tại vì một lý do rất cụ thể — không có nó, 50 mã × 3 lần thử × backoff có thể treo hàng chục phút trong một cell notebook.

Khi có gì đó không chạy

Không có tuỳ chọn tắt xác thực TLS, và đó là chủ ý: tắt nó để sửa một lỗi cấu hình là đổi một phút phiền phức lấy một lỗ hổng vĩnh viễn — trong khi chính khoá API của bạn đi qua đúng kết nối đó.

Danh sách đầy đủ các lớp ngoại lệ và mã lỗi FL_* nằm ở Xử lý lỗi.

Tiếp theo

Khi báo lỗi, gửi kèm kết quả của finlens.build_info() — phần lớn thư viện được biên dịch, nên số phiên bản một mình không đủ để dựng lại đúng bản build bạn đang chạy.

>>> finlens.build_info()
{'version': '1.1.1', 'commit': 'a1b2c3d', 'built_at': '...', 'cython': '3.2.9',
 'python': '3.12', 'platform': 'windows-amd64'}

Đã có khoá, giờ làm gì

Xem 17 notebook ví dụ thực chiến — chạy trên dữ liệu thật, đi từ lời gọi API đầu tiên tới dashboard thị trường, screener định giá, screener tín hiệu kỹ thuật và backtest tránh look-ahead.