Cài đặt và khoá nguồn

Cài thư viện

Cần Python 3.10 trở lên, trên Windows, macOS hoặc Linux.

python -m venv ~/.venv_oapi && source ~/.venv_oapi/bin/activate

# Cài trực tiếp từ GitHub:
pip install git+https://github.com/vnstock-hq/vnstock-open-api.git

# Hoặc từ kho gói của hệ sinh thái Vnstock:
pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock-oapi==0.1.0rc1"
vnstock-oapi --version

Trên Windows, kích hoạt môi trường bằng ~\.venv_oapi\Scripts\activate.

Cần dữ liệu trong phiên qua WebSocket thì cài kèm phần stream:

pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock-oapi[stream]==0.1.0rc1"
# hoặc cài kèm stream từ GitHub:
pip install "vnstock-oapi[stream] @ git+https://github.com/vnstock-hq/vnstock-open-api.git"

Chỉ import vnstock_oapi thì thư viện chưa gọi mạng, chưa đọc khoá, chưa ghi tệp nào.

Cất khoá

Đăng ký khoá ở nguồn bạn định dùng (xem bảng nguồn ở Giới thiệu). vnstock-oapi tìm khoá theo thứ tự: biến môi trường, tệp .env ở thư mục đang chạy, rồi keyring của hệ điều hành. Giá trị tìm thấy trước được dùng. Không hàm nào nhận khoá qua tham số.

Chọn nguồn của bạn ở thanh đầu trang, lệnh và tên biến bên dưới sẽ điền theo nguồn đó.

Keyring. Gõ khoá khi được hỏi, ký tự không hiện ra:

vnstock-oapi keys set <nguồn>       # cất vào keyring
vnstock-oapi keys delete <nguồn>    # xoá

Tệp .env trong thư mục bạn chạy lệnh. Tên biến của từng nguồn có ở bảng nguồn.

<NGUỒN>_API_KEY="..."

Nguồn dùng cặp key và secret thì thêm dòng secret:

<NGUỒN>_API_SECRET="..."

chmod 600 .env
echo ".env" >> .gitignore

.env chỉ được đọc ở thư mục đang chạy, không đọc ở thư mục cha. Không commit tệp .env, không dán khoá vào sổ tay chia sẻ hay khung chat với trợ lý AI.

Nhiều tài khoản ở cùng một nguồn. Thêm --profile <hồ_sơ> vào lệnh. Biến môi trường của hồ sơ có thêm tên hồ sơ: <NGUỒN>_<HỒ_SƠ>_API_KEY.

Máy không có keyring

GitHub Codespaces, Docker, máy chủ Linux và WSL thường không có keyring. Trên các máy này, vnstock-oapi keys set dừng với lỗi NoKeyringError và khoá không được cất. Dùng biến môi trường hoặc tệp .env ở trên. Trên GitHub Codespaces, tạo secret đúng tên biến ở GitHub → Settings → Codespaces → Secrets; codespace mới tạo hoặc khởi động lại sẽ có các secret này dưới dạng biến môi trường.

Nguồn mở phiên (có token hoặc OTP) cần chỗ cất phiên. Khi không có keyring, đặt:

export VNSTOCK_OAPI_SESSION_BACKEND=file

Phiên khi đó nằm trong một tệp chỉ tài khoản của bạn đọc được (quyền 600).

Kiểm khoá và mở phiên

vnstock-oapi status             # khoá lấy từ đâu, phiên còn hạn không; không gọi mạng, không in giá trị khoá
vnstock-oapi check <nguồn>      # gọi thử một thao tác nhẹ nhất; bỏ tên nguồn để kiểm mọi nguồn

Nguồn có phiên thì mở phiên trước khi gọi dữ liệu:

vnstock-oapi auth <nguồn>       # mở phiên; hỏi OTP nếu nguồn cần
vnstock-oapi auth <nguồn> --clear

check cho biết nguồn nào đang thiếu khoá hoặc từ chối khoá. Hãy xử lý lỗi này trước khi gọi dữ liệu.

auth chỉ cần cho nguồn có phiên, và luôn cần tên nguồn. Nguồn ký khoá vào từng request thì không có phiên để mở: auth báo "không cần phiên" kể cả khi máy chưa có khoá. Muốn biết khoá dùng được chưa, chạy check <nguồn>.

OTP không bao giờ được lưu: bạn gõ OTP mỗi lần mở phiên. vnstock-oapi không bao giờ hỏi mật khẩu tài khoản chứng khoán của bạn.

Phiên dùng chung cho mọi công cụ trên cùng máy: notebook, tác vụ chạy theo lịch và vnstock 6 không làm phiên của nhau hết hiệu lực.