Dữ liệu trái phiếu doanh nghiệp bằng Python

Trái phiếu doanh nghiệp là phần thị trường vốn ít được số hoá nhất, và cũng là nơi rủi ro tín dụng nằm. client.bonds trả lời hai câu: có những lô trái phiếu nào, và ai đang nợ bao nhiêu.

6.820 lô trái phiếu của 940 tổ chức phát hành. Đây là ảnh chụp trạng thái hiện tại, không phải chuỗi thời gian dư nợ.

import finlens

client = finlens.client()

con_no = client.bonds.list(outstanding=True)
to_chuc = client.bonds.issuers(has_stock=True)

Vì sao không gộp hai loại tiền vào một cột

Toàn thị trường có 6.796 lô bằng VND và 23 lô bằng USD (một lô không xác định được tiền tệ). Tỷ lệ nhỏ, nên gộp lại nghe có vẻ vô hại — nhưng nó không.

Cùng một con số mệnh giá tồn tại ở cả hai loại tiền. Một cột currency đặt cạnh không ngăn được ai đó viết df["par_value"].mean() rồi cộng đô la với đồng lệch nhau hơn hai vạn lần.

Tách cột thì phép cộng nhầm ấy không viết ra được:

b = client.bonds.list()

b.groupby("currency")[["outstanding_value_mvnd", "outstanding_value_usd"]].sum()

Hệ quả phải sống chung: câu hỏi "tổng dư nợ trái phiếu doanh nghiệp là bao nhiêu" không có một con số duy nhất ở đây. Muốn có, bạn phải tự chọn một tỷ giá — và đó là lựa chọn của bạn, không phải mặc định của thư viện. Nguồn không có bảng tỷ giá nào để thư viện dùng.

list() — danh mục lô trái phiếu

client.bonds.list(
    *,
    codes=None,
    issuer=None,
    symbol=None,
    sector=None,
    currency=None,
    status=None,
    outstanding=None,
    matured=None,
    maturity_from=None,
    maturity_to=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Bỏ trống codes thì cả 6.820 dòng về trong một lần gọi, nên "muốn nhiều hơn mười mã" luôn có đường đi không tốn hạn mức: lấy hết rồi lọc bằng pandas.

Cột trả về

Frame có 30 cột. Nhóm theo việc:

⚠️ coupon_rate_pct mang hậu tố _pct nên nó là thang 0–100: giá trị 9,5 nghĩa là 9,5%/năm. Khác hẳn các cột _ratio ở những trang khác.

issuers() — tổ chức phát hành

client.bonds.issuers(
    *,
    codes=None,
    symbol=None,
    sector=None,
    has_bonds=None,
    has_stock=None,
    refresh=False,
    on_error="warn",
) -> DataFrame

Cột trả về

⚠️ legal_form không phải company_type. Bốn token CT, NH, CK, BH của báo cáo tài chính là một từ vựng đóng khác hẳn; legal_form ở đây là chuỗi tiếng Việt do nguồn quyết định.

Cầu nối sang cổ phiếu chỉ phủ 128/940

Cột symbol là chỗ duy nhất nối dữ liệu trái phiếu với dữ liệu giá cổ phiếu, và nó thưa:

i = client.bonds.issuers()

i["symbol"].notna().sum()   # 128
len(i)                      # 940

Phần còn lại là doanh nghiệp chưa đại chúng hoặc chưa niêm yết. Nên khi ghép, dùng phép ghép trái và kiểm số dòng mất đi trước khi kết luận:

gia = client.eod.stock.ohlcv(
    i["symbol"].dropna().tolist()[:10], start="2026-01-01"
)

Nếu bạn ghép trong rồi thấy dữ liệu teo lại còn một phần bảy, đó là cầu nối thưa chứ không phải lỗi ghép.

Ảnh chụp, không phải chuỗi thời gian

Bảng này trả về trạng thái hiện tại của từng lô. Không có lịch sử dư nợ theo kỳ, và issue_date / maturity_date là thuộc tính của lô trái phiếu chứ không phải nhịp quan sát.

Dựng lịch đáo hạn thì nhóm trên chính ảnh chụp đó:

b = client.bonds.list(outstanding=True)

theo_thang = (
    b.dropna(subset=["maturity_date"])
    .groupby(b["maturity_date"].dt.to_period("M"))["outstanding_value_mvnd"]
    .sum()
)

Vì đây là ảnh chụp, tham số matured so với thời điểm chụp chứ không phải thời điểm bạn gọi. Hai mốc gần nhau khi dữ liệu được thu thập đều đặn, nhưng chúng không đồng nhất.

Một dòng không có tiền tệ

Đúng một trong 6.820 dòng có currency bằng null, và cả sáu cột tiền của dòng đó cũng rỗng. Thư viện không lọc nó đi.

Đó là lựa chọn có chủ đích: một lô trái phiếu biến mất khỏi bảng dư nợ tệ hơn một ô trống có thể nhìn thấy. Nếu bạn cộng theo tiền tệ thì groupby tự bỏ qua nó; nếu bạn đếm số lô thì hãy biết nó có ở đó.

b = client.bonds.list()
b["currency"].isna().sum()   # 1