Vnstock Open API: Tự kết nối Open API bằng khoá của chính bạn

Khi đã đăng ký tài khoản và lấy được mã khoá từ một cổng Open API, việc gửi thử yêu cầu đầu tiên bằng Python thường không quá phức tạp. Chỉ cần vài dòng mã cơ bản, bạn đã có thể nhận về một phản hồi JSON.

Nhưng khoảng cách từ một đoạn mã chạy thử đến một quy trình nghiên cứu vận hành ổn định mỗi ngày lại nằm ở những phần việc lặp đi lặp lại phía sau: cất mã khoá ở đâu để trợ lý AI không vô tình đọc phải, làm mới mã truy cập khi hết hạn, dùng chung phiên đăng nhập giữa nhiều sổ tay lập trình, đọc tiếp khi kết quả chia thành nhiều trang và giữ lại thông tin nguồn gốc để đối chiếu về sau.

Trong kiến trúc của Vnstock thế hệ 6, phần việc kết nối đầu nguồn đó được tách thành một công cụ độc lập mang tên Vnstock Open API (thư viện vnstock-oapi).

Công cụ này thuộc bản Cộng đồng, miễn phí cho cá nhân, học tập và nghiên cứu theo giấy phép riêng của Vnstock. Mã nguồn được công bố tại kho vnstock-open-api trên GitHub để bạn có thể trực tiếp kiểm tra cách chương trình quản lý khoá bí mật, kiểm soát các yêu cầu gửi ra mạng, dùng độc lập cho nhu cầu riêng hoặc kết hợp cùng bộ công cụ Vnstock.

Tóm tắt trong một phút

• Cổng kết nối chạy trên máy của bạn: vnstock-oapi là thư viện Python và công cụ dòng lệnh giúp bạn dùng tài khoản và mã khoá của chính mình (mô hình BYOK) để gọi thẳng tới cổng Open API của nguồn đã chọn.
• Hướng tới các kết nối mở chính thức và ổn định: ở các phiên bản đầu của thế hệ 6, bên cạnh các cổng Open API từ công ty chứng khoán trong nước, công cụ đã hỗ trợ nguồn dữ liệu tài chính quốc tế (FMP) và tiền mã hoá (Binance), đồng thời sẵn sàng mở rộng sang các cổng dữ liệu chính thức khác.
• Minh bạch cách xử lý khoá và yêu cầu mạng: mã nguồn được công bố trên GitHub để bạn tự kiểm chứng cách thư viện đọc khoá từ kho bảo mật của hệ điều hành (keyring), tệp .env hoặc biến môi trường mà không đi qua máy chủ trung chuyển của Vnstock.
• Giữ nguyên phản hồi gốc kèm dấu vết nguồn gốc: mỗi lần truy xuất trả về phản hồi nguyên bản từ nguồn được đóng gói trong cấu trúc Envelope, sẵn sàng lưu ra tệp .jsonl hoặc chuyển sang vnstock thế hệ 6 để chuẩn hoá thành pandas.DataFrame.
• Phạm vi chỉ đọc rõ ràng: thư viện chỉ thực hiện các thao tác đọc dữ liệu thị trường và thông tin tham chiếu được công bố; không truy cập thông tin riêng của tài khoản và không thực hiện các thao tác làm thay đổi trạng thái tài khoản.

Vì sao đặt tên là Open API và tách thành một công cụ độc lập?

Tên gọi Open API thể hiện định hướng kết nối dài hạn

Khi nghe đến kết nối Open API trong bối cảnh thị trường Việt Nam, nhiều người thường nghĩ ngay đến cổng API của các công ty chứng khoán. Thực tế, ở những phiên bản đầu tiên của Vnstock thế hệ 6, nhóm kết nối quen thuộc nhất đối với dữ liệu cổ phiếu và phái sinh trong nước đúng là các cổng Open API do công ty chứng khoán vận hành, đi cùng nguồn dữ liệu tài chính quốc tế (Financial Modeling Prep — FMP) và dữ liệu thị trường tiền mã hoá giao ngay (Binance).

Tuy nhiên, việc đặt tên công cụ là Vnstock Open API (vnstock-oapi) không đồng nghĩa với việc giới hạn phạm vi ở công ty chứng khoán. Chữ Open API ở đây thể hiện tầm nhìn xuyên suốt từ thế hệ 6 trở đi: ưu tiên làm việc với các cổng kết nối mở chính thức, có tài liệu công bố, cơ chế xác thực rõ ràng và vận hành ổn định lâu dài.

Đó có thể là cổng dữ liệu của định chế tài chính trong nước, nguồn dữ liệu tài chính quốc tế, cổng dữ liệu vĩ mô và thống kê mở, hoặc một cổng API nội bộ mà chính bạn tự đăng ký thêm vào công cụ để phục vụ quy trình nghiên cứu của mình.

Tách bạch chặng kết nối đầu nguồn với chặng chuẩn hoá và tính toán

Khi bạn kết nối tới các cổng Open API bằng tài khoản và khoá riêng, quy trình làm việc thực tế gồm hai chặng có vai trò rất khác nhau:

1. Chặng kết nối đầu nguồn: lưu giữ khoá an toàn trên máy, mở và duy trì phiên đăng nhập, gửi yêu cầu theo quy ước của nguồn và nhận về phản hồi nguyên bản.
2. Chặng chuẩn hoá, tổ chức và tính toán: đối chiếu sự khác biệt về tên trường, đơn vị, múi giờ giữa các nguồn để đưa về một quy ước dữ liệu chung, tổ chức lưu trữ trên máy và tính toán các chỉ báo, chỉ số tài chính.

Ở Vnstock thế hệ 6, hai chặng này được tách thành hai lớp công cụ rõ ràng:

Sơ đồ 1: vnstock-oapi đảm nhận chặng kết nối và đóng gói phản hồi gốc thành Envelope; từ điểm nối này, bạn có thể tự xử lý, lưu tệp .jsonl trên máy hoặc đưa sang vnstock thế hệ 6 để chuẩn hoá thành bảng dữ liệu.

Cách tổ chức này mang lại ba lợi ích trực tiếp cho người dùng:

1. Kiểm chứng được cách phần mềm xử lý khoá truy cập của bạn: khi kết nối bằng tài khoản và mã khoá cá nhân, bạn cần biết chắc khoá được đọc từ đâu, lưu ở đâu và chương trình gửi những yêu cầu gì ra mạng. Việc tách gọn lớp kết nối vào một thư viện riêng và công bố mã nguồn trên GitHub giúp bạn có thể kiểm tra trực tiếp từng bước xử lý khoá, xác nhận truy vấn đi thẳng từ máy bạn tới nguồn và chỉ giới hạn ở các thao tác đọc dữ liệu.
2. Tách bạch cổng kết nối thuộc bản Cộng đồng với tầng công cụ năng suất thuộc bản Mở rộng: kết nối tới một cổng Open API bằng quyền truy cập của chính mình là bước khởi đầu cơ bản. Vì vậy, vnstock-oapi được phát hành trong bản Cộng đồng (miễn phí cho cá nhân, học tập và nghiên cứu) để bất kỳ ai cũng có thể thiết lập khoá, kiểm tra nguồn và lấy phản hồi gốc về máy. Khi nhu cầu mở rộng sang việc chuẩn hoá dữ liệu đa nguồn về một lược đồ chung (vnstock), tổ chức lưu trữ theo lịch (vnstock_pipeline), tính toán định lượng minh bạch công thức (vnstock_quant) và sử dụng bộ kỹ năng cho trợ lý AI, bạn mới kết hợp thêm các công cụ trong Gói quyền sử dụng Vnstock.
3. Linh hoạt lưu trữ và tái sử dụng phản hồi gốc mà không cần gọi lại mạng: khi phản hồi nguyên bản đã được đóng gói kèm thông tin nguồn gốc và lưu thành tệp .jsonl trên máy, bạn có thể tự xử lý nếu chỉ làm việc với một nguồn đơn lẻ, hoặc đưa tệp đó qua lớp chuẩn hoá của vnstock thế hệ 6 nhiều lần mà không tốn thêm lượt gọi API.

Bốn phần việc lặp lại được xử lý sẵn ở tầng kết nối

Bốn phần việc kỹ thuật lặp lại được gom về quy trình thống nhất trên máy của bạn

Mỗi đơn vị vận hành Open API thường có quy định riêng về cách xác thực, cách đặt tên tham số và cách chia trang kết quả. vnstock-oapi gom những phần việc kỹ thuật lặp lại đó về một quy trình thống nhất trên máy của bạn:

1. Quản lý phiên đăng nhập và dùng chung giữa nhiều công cụ

Như đã phân tích trong bài Đăng nhập Open API: hiểu API key, token, OAuth và OTP, có nguồn chỉ cần một khoá tĩnh, có nguồn dùng cặp khoá và bí mật để lấy token hoặc ký yêu cầu, có nguồn cần nhập thêm OTP để mở phiên làm việc, và cũng có nguồn cho phép tra cứu dữ liệu công bố mà không cần khoá.

vnstock-oapi xử lý sẵn việc giữ và làm mới phiên theo đúng cơ chế của từng nguồn. Đặc biệt, phiên làm việc đang còn hiệu lực được lưu an toàn và dùng chung giữa các tiến trình trên cùng một máy tính. Khi bạn mở song song một Jupyter Notebook để khám phá dữ liệu và một cửa sổ terminal để chạy kịch bản cập nhật, hai tiến trình có thể dùng lại cùng một phiên thay vì đăng nhập chồng chéo làm mất hiệu lực phiên của nhau.

2. Giữ mã khoá tách biệt khỏi mã nguồn và trợ lý AI

Khi thực hành vibe coding, việc đặt khoá trong mã nguồn hoặc tệp .env dễ khiến coding agent có quyền đọc thư mục dự án vô tình tiếp cận thông tin bí mật (xem bài Lưu API key an toàn: keyring, .env và coding agent).

vnstock-oapi không nhận khoá qua tham số hàm và ưu tiên lưu khoá lâu dài trong kho bảo mật của hệ điều hành (keyring như macOS Keychain, Windows Credential Locker, Linux Secret Service). Trong suốt quá trình chạy, thông tin khoá luôn được che đi khi in ra màn hình hoặc ghi nhật ký, và chỉ được gắn vào yêu cầu ngay tại bước gửi tới nguồn.

3. Giữ nguyên phản hồi gốc trong phong bì dữ liệu

vnstock-oapi không tự ý sửa đổi, đổi tên trường hay làm phẳng dữ liệu của nguồn ở tầng kết nối. Mỗi lần gọi API trả về các bản ghi có cấu trúc thống nhất gọi là Envelope (phong bì dữ liệu).

Bên trong mỗi Envelope là phản hồi gốc nguyên bản, bên ngoài ghi nhận thông tin nguồn gốc để đối chiếu

Bên trong mỗi phong bì là nguyên văn phản hồi mà nguồn trả về, còn bên ngoài ghi nhận ngữ cảnh truy vấn (tên nguồn, thao tác, tham số đã lọc bỏ toàn bộ khoá bí mật, thời điểm nhận) cùng mã băm SHA-256 để kiểm tra tính toàn vẹn. Nhờ vậy, khi thấy một con số cần kiểm tra trên báo cáo phân tích, bạn luôn có thể mở lại đúng bản ghi gốc của thời điểm đó để đối chiếu.

4. Cung cấp nhóm thao tác chung bên cạnh thao tác riêng của từng nguồn

Với những nhu cầu tra cứu phổ biến như dữ liệu nến lịch sử, khớp lệnh, bảng giá, chỉ số, giao dịch khối ngoại, danh sách mã, lịch giao dịch và sự kiện doanh nghiệp, vnstock-oapi cung cấp các hàm có cùng tên gọi giữa các nguồn hỗ trợ. Nếu một nguồn không hỗ trợ thao tác hoặc khung thời gian bạn chọn, thư viện sẽ báo lỗi rõ nguyên nhân thay vì tự ý gộp nến hay trả về kết quả rỗng. Khi cần đến những endpoint đặc thù của riêng một nguồn, bạn vẫn có thể gọi thẳng theo tên thao tác gốc trong tài liệu của nguồn đó.

Bắt đầu nhanh từ dòng lệnh đến mã Python

Nếu chưa cài đặt bộ công cụ thế hệ 6, bạn có thể tạo một môi trường Python riêng (~/.venv_6x, yêu cầu Python 3.10 trở lên) và cài đặt từ kho gói của Vnstock:

python -m venv ~/.venv_6x && source ~/.venv_6x/bin/activate
python -m pip install -U --extra-index-url https://vnstocks.com/api/packages "vnstock>=6.0.0,<7" "vnstock-oapi>=0.1.0,<1"

Danh sách các nguồn được hỗ trợ cùng hướng dẫn lấy khoá của từng nguồn được cập nhật tại trang Giới thiệu vnstock-oapi. Bạn có thể chọn nguồn mình đang có tại thanh Nguồn của bạn ở đầu bài viết (hoặc ô Nguồn ở góc phải mỗi khối mã) để các chỗ trống <nguồn> và <mã> tự động điền theo nguồn tương ứng.

1. Lưu khoá vào keyring và kiểm tra kết nối trên terminal

Sau khi lưu khoá vào keyring của hệ điều hành (chỉ cần thực hiện một lần cho mỗi nguồn), bạn có thể kiểm tra ngay trạng thái khoá và xem trước yêu cầu mà chưa cần viết mã Python:

# Lưu khoá vào keyring của hệ điều hành (ký tự nhập vào được ẩn hoàn toàn; riêng binance không cần khoá)
vnstock-oapi keys set <nguồn>

# Kiểm tra các nguồn đã lưu khoá ở đâu và phiên còn hạn không (không gọi mạng)
vnstock-oapi status

# Gọi thử một thao tác nhẹ để xác nhận kết nối hoạt động tốt
vnstock-oapi check <nguồn>

# Xem trước yêu cầu sẽ gửi đi mà chưa gọi mạng (thông tin xác thực đã được che)
vnstock-oapi ohlc <nguồn> <mã> --preview

Ngoài ra, khi muốn nhờ trợ lý AI viết mã xử lý cho một nguồn mới mà không muốn gửi dữ liệu thật từ tài khoản của mình vào khung chat, bạn có thể chạy lệnh vnstock-oapi dump <nguồn> --symbol <mã>. Lệnh này sinh ra tệp shapes.md chỉ ghi lại tên trường và kiểu dữ liệu của phản hồi mà không chứa bất kỳ con số thật nào, rất an toàn để đính kèm cho coding agent.

2. Truy xuất dữ liệu trong Python và chuẩn hoá thành bảng dữ liệu

Trong Python, bạn có thể dùng trực tiếp vnstock_oapi để lấy và lưu phản hồi gốc dạng Envelope cho bất kỳ nguồn nào được hỗ trợ:

import vnstock_oapi as oapi

# Lấy phản hồi gốc dạng Envelope qua vnstock-oapi và lưu ra tệp JSONL
bars = oapi.source("<nguồn>").ohlc("<mã>", start="2026-10-01", end="2026-10-10", interval="1D")
print(bars.summary())       # tóm tắt nguồn, thao tác, mã HTTP, mã băm SHA-256 và dung lượng
bars.save("ohlc.jsonl")     # lưu phản hồi gốc ra tệp trên máy để đối chiếu hoặc tái sử dụng

Khi kết hợp cùng thư viện vnstock thế hệ 6, bạn có thể chuẩn hoá ngoại tuyến tệp Envelope vừa lưu trên máy thành bảng pandas.DataFrame (không tốn thêm lượt gọi mạng), hoặc gọi thẳng qua lớp Market để nhận bảng dữ liệu đã đồng nhất về tên cột (time, open, high, low, close, volume), đơn vị giá và múi giờ:

from vnstock import Connector, Market

# Cách 1: Chuẩn hoá ngoại tuyến từ tệp Envelope đã lưu trên máy (không gọi lại mạng)
df_offline = Connector("<nguồn>").equity("<mã>").ohlcv("ohlc.jsonl")
print(df_offline.head(3))

# Cách 2: Gọi trực tiếp qua lớp Market (tự động dùng khoá của nguồn trong keyring)
df = Market("<nguồn>").equity("<mã>").ohlcv(start="2026-10-01", end="2026-10-10")
print(df.head(3))

Ranh giới hoạt động: công cụ kết nối làm gì và không làm gì?

Để bạn yên tâm đưa công cụ vào quy trình nghiên cứu lâu dài, phạm vi hoạt động của vnstock-oapi được xác định rõ ngay từ thiết kế:

Phạm vi hoạt động rõ ràng giữa công cụ kết nối của người dùng và các bên cung cấp dữ liệu

Về mặt quyền sử dụng, bạn cần phân biệt hai lớp độc lập:

• Quyền dùng phần mềm: vnstock-oapi được phát hành theo giấy phép riêng của Vnstock, miễn phí cho cá nhân, học tập và nghiên cứu. Hai việc luôn cần thoả thuận riêng bằng văn bản là phân phối lại phần mềm và xây dựng sản phẩm có giá trị chính là giúp bên thứ ba truy xuất dữ liệu (trừ gói mở rộng đáp ứng đầy đủ điều kiện ghi trong giấy phép).
• Quyền đối với dữ liệu: phản hồi bạn truy xuất thông qua tài khoản và khoá của mình tuân theo điều khoản của nguồn tương ứng. Bạn có thể chạy lệnh vnstock-oapi terms <nguồn> bất kỳ lúc nào để xem nhanh bản tóm tắt và mở đường dẫn tới văn bản điều khoản gốc của nguồn.

Khi nào dùng riêng cổng kết nối, khi nào kết hợp cùng Vnstock thế hệ 6?

Trong hệ sinh thái Vnstock thế hệ 6, vnstock-oapi và các thư viện ở tầng năng suất bổ trợ trực tiếp cho nhau. Bạn có thể chọn điểm bắt đầu tuỳ theo bài toán thực tế của mình:

Câu hỏi thường gặp

Cổng kết nối này có phải chỉ dành cho Open API của công ty chứng khoán không?

Không. Ở những phiên bản đầu của thế hệ 6, các cổng Open API từ công ty chứng khoán trong nước là nhóm nguồn phổ biến nhất đối với dữ liệu thị trường Việt Nam, bên cạnh nguồn dữ liệu tài chính quốc tế (FMP) và tiền mã hoá (Binance). Về dài hạn, tên gọi Vnstock Open API thể hiện định hướng kết nối với các cổng dữ liệu mở chính thức, ổn định từ nhiều loại hình đơn vị vận hành khác nhau; ngoài danh sách có sẵn, bạn cũng có thể tự đăng ký thêm nguồn Open API riêng qua cơ chế mở rộng của thư viện.

Mã khoá của nguồn có được gửi về máy chủ của Vnstock không?

Không. Truy vấn xuất phát từ máy của bạn và đi thẳng tới nguồn bạn chọn, hoặc qua proxy do bạn tự cấu hình. Mã khoá của nguồn được lưu trên máy của bạn (trong keyring, .env hoặc biến môi trường) để phục vụ kết nối đó và không được gửi về vnstocks.com. Bạn có thể trực tiếp kiểm tra cơ chế này trong kho mã nguồn vnstock-open-api trên GitHub.

Dùng cổng kết nối này có cần đăng ký Gói quyền sử dụng Vnstock không?

Không bắt buộc nếu bạn chỉ cần kết nối nguồn và làm việc với phản hồi gốc trong Envelope. vnstock-oapi thuộc bản Cộng đồng, miễn phí cho mục đích cá nhân, học tập và nghiên cứu. Bạn chỉ cần Gói quyền sử dụng Vnstock khi muốn sử dụng các công cụ thuộc bản Mở rộng ở tầng sau như chuẩn hoá đa nguồn về DataFrame, tự động hoá quy trình với vnstock_pipeline, tính toán định lượng với vnstock_quant hoặc bộ kỹ năng chuyên sâu cho trợ lý AI.

Mã nguồn trên GitHub được phát hành theo giấy phép nào?

vnstock-oapi không phải là phần mềm mã nguồn mở. Mã nguồn được công bố trên GitHub theo giấy phép riêng của Vnstock để người dùng cá nhân có thể đọc hiểu, kiểm tra tính an toàn khi sử dụng khoá truy cập và phục vụ việc học tập, nghiên cứu cá nhân.

Tài liệu nên đọc tiếp

Điều cần nhớ

Khi làm việc với các cổng Open API chính thức bằng tài khoản của chính mình, phần tốn nhiều công sức nhất thường không nằm ở câu lệnh lấy dữ liệu đầu tiên, mà ở việc giữ khoá an toàn trước các công cụ AI, duy trì phiên đăng nhập ổn định và bảo toàn dấu vết nguồn gốc để kiểm tra lại khi cần.

vnstock-oapi được tách thành một công cụ độc lập thuộc bản Cộng đồng và công bố mã nguồn để giải quyết trọn vẹn phần nền tảng đó: đủ minh bạch để bạn kiểm chứng từng bước xử lý khoá trên máy, đủ rõ ràng về ranh giới chỉ đọc dữ liệu, và đủ linh hoạt để mở rộng sang nhiều cổng kết nối chính thức trong tương lai hoặc nối tiếp vào tầng chuẩn hoá, tính toán của Vnstock thế hệ 6.

Nếu bạn đã lưu sẵn mã khoá trong keyring, hãy thử bắt đầu bằng hai lệnh vnstock-oapi status và vnstock-oapi check <nguồn> ngay trong terminal để kiểm tra kết nối trên máy của mình.

Vnstock là hệ sinh thái tự động hoá cá nhân trong nghiên cứu đầu tư, chạy trên máy của bạn. Vnstock cấp quyền dùng phần mềm, không bán dữ liệu; dữ liệu có sẵn và chính xác tới đâu là do nguồn. Nội dung phục vụ nghiên cứu và tham khảo, không phải khuyến nghị đầu tư.

Tài liệu: vnstocks.com · GitHub: github.com/vnstock-hq