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

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'}