Tài liệu API và MCP
FinancialMD cung cấp các báo cáo tài chính được xây dựng từ hồ sơ nộp SEC. Mọi con số đều liên kết đến hồ sơ nộp SEC mà nó xuất phát từ đó, và mọi con số đều có thể được đọc theo đúng thông tin đã được biết vào bất kỳ ngày nào. Không cần tài khoản.
Thực hiện lệnh gọi đầu tiên
API trả về JSON qua HTTPS. Lệnh gọi này trả về năm báo cáo kết quả kinh doanh hàng năm gần nhất của Apple. Không cần khóa.
curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"Báo cáo là một trong income_statement, balance_sheet, cash_flow hoặc supplemental. Loại kỳ là một trong annual, quarterly, ltm hoặc ytd.
Đặt tên một công ty
Mỗi route công ty đều nhận tham số company.
ticker:AAPL, hayticker:AAPL.XNASđể đặt tên cho sàn giao dịchcik:320193, số công ty của SECfmd_<id>, id FinancialMD gán cho công ty
AAPL đứng riêng được hiểu là ticker, còn các chữ số đứng riêng được hiểu là CIK. Phản hồi cho biết mục nào khớp trong meta.company.matched_by.
Đọc một giá trị
Một phản hồi thành công có dạng { data, meta }. Một con số trong data không bao giờ đứng riêng. Nó là một đối tượng giá trị:
{
"value": 391035000000,
"unit": "USD",
"currency": "USD",
"decimals": -6,
"period": { "start": "2023-10-01", "end": "2024-09-28", "type": "annual", "fiscal_year": 2024, "fiscal_period": "FY" },
"known": { "from": "YYYY-MM-DDThh:mm:ssZ", "to": null },
"restated": false,
"method": "as_filed",
"calc_type": "as_filed",
"proof": { "id": "p_...", "accession": "0000320193-24-000123", "form": "10-K", "filed": "2024-11-01", "taxonomy": "us-gaap", "tag": "...", "source_url": "https://www.sec.gov/..." }
}known là khoảng thời gian mà đây là số liệu được nộp mới nhất. restated chỉ là true khi một hồ sơ nộp SEC sau đó đã thay đổi số liệu; restatement_kind khi đó cho biết thay đổi theo cách nào. proof.id được phân giải tại GET /proof/{id} tới hồ sơ nộp SEC và các dữ kiện thô đằng sau giá trị.
Đọc lại quá khứ theo thông tin đã được biết
as_of=2024-06-30trên bất kỳ route đọc nào đều trả về thông tin đã được biết tại thời điểm đó.original=truetrả về phiên bản được báo cáo đầu tiên của mỗi kỳ.history=truetrả về mọi phiên bản của từng kỳ, cũ nhất trước.GET /v1/changes?since=<timestamp>liệt kê các dữ kiện được ghi nhận kể từ thời điểm đó.
Các route
| Route | Nội dung trả về |
|---|---|
GET /v1/companies | Thư mục công ty với bộ lọc và phân trang |
GET /v1/company/profile | Hồ sơ, danh sách và các bộ dữ liệu có sẵn |
GET /v1/company/metrics | Các hàng khái niệm trong mẫu của công ty |
GET /v1/company/financials/{statement}/standardized | Một báo cáo chuẩn hóa |
GET /v1/company/financials/{statement}/as_reported | Các khoản mục riêng của đơn vị nộp hồ sơ, kèm thẻ |
GET /v1/company/ratios | Các tỷ lệ được tính từ các báo cáo, kèm bằng chứng về đầu vào của chúng |
GET /v1/company/ratios/daily/{ratio_id} | Một tỷ lệ dưới dạng chuỗi theo các kỳ |
GET /v1/company/filings | Chỉ mục hồ sơ nộp SEC của một công ty |
GET /v1/filing/{accession} | Một hồ sơ nộp SEC |
GET /v1/filing/{accession}/facts | Mọi dữ kiện đã ánh xạ mà một hồ sơ nộp SEC đã gắn thẻ |
GET /v1/filing/{accession}/document | Liên kết đến các trang của một hồ sơ nộp SEC trên EDGAR, hoặc tài liệu chính của hồ sơ đó dưới dạng HTML, PDF hoặc ảnh trang |
GET /v1/company/ownership/insiders | Giao dịch nội bộ từ Form 3, Form 4 và Form 5 |
GET /v1/company/ownership/institutional | Các chủ sở hữu theo Form 13F của một công ty, theo quý |
GET /v1/ownership/institutional/holders | Các nhà quản lý 13F |
GET /v1/ownership/institutional/holdings | Danh mục 13F của một nhà quản lý trong một quý |
GET /v1/company/splits | Các đợt chia tách cổ phiếu như đã nộp, và liệu giá có xác nhận chúng hay không |
GET /v1/company/dividends | Cổ tức trên mỗi cổ phiếu được công bố hoặc chi trả trong từng kỳ, như đã nộp |
GET /v1/events_calendar | Thông cáo kết quả kinh doanh (đã nộp theo 8-K Item 2.02) và các ngày dự kiến theo mô hình |
GET /v1/company/events | Các mục 8-K: nguồn cấp sự kiện dựa trên hồ sơ nộp SEC |
GET /v1/news | Các hồ sơ nộp 8-K của mọi công ty được theo dõi, mới nhất trước, kèm loại sự kiện và mức độ quan trọng |
GET /v1/news/feed | Nguồn cấp sự kiện riêng của FinancialMD từ mọi biểu mẫu SEC có sự kiện, với tiêu đề tạo theo quy tắc, mức độ quan trọng và các số liệu chính. Không phải tin tức dòng tin |
GET /v1/news/issuer_releases | Các thông cáo mà tổ chức phát hành tự công bố về mình: phụ lục SEC, cùng tiêu đề và liên kết từ nguồn cấp riêng của tổ chức phát hành |
GET /v1/company/call_materials | Tài liệu cuộc gọi kết quả kinh doanh mà tổ chức phát hành đã nộp cho SEC: thông cáo, phát biểu soạn sẵn, thư, bài thuyết trình và bản ghi khi có nộp |
GET /v1/call_material/{id} | Một tài liệu do tổ chức phát hành nộp, dưới dạng các đoạn có phần mục, lượt người nói và thẻ chủ đề |
GET /v1/calls_calendar | Các cuộc gọi kết quả kinh doanh như tổ chức phát hành công bố trong hồ sơ nộp SEC, kèm liên kết đến trang webcast riêng của tổ chức phát hành |
GET /v1/search/filings | Tìm kiếm toàn văn các tài liệu EDGAR từ năm 2001 (tìm kiếm toàn văn SEC EDGAR) |
GET /v1/coverage | Mỗi bộ dữ liệu với trạng thái: đang phục vụ, không bao phủ (được cấp phép) hoặc chưa xây dựng, và nên dùng gì thay thế |
GET /v1/company/estimates | Các ước tính cơ sở dựa trên mô hình do FinancialMD tự xây dựng với các khoảng và thành tích theo dõi tại một thời điểm (point-in-time), hướng dẫn của công ty như được nêu trong các hồ sơ nộp SEC, và các tín hiệu mô tả. Không phải đồng thuận, không phải ước tính của nhà phân tích. Xem phương pháp |
GET /v1/company/estimates/consensus | Không bao phủ: ước tính đồng thuận được cấp phép. Trả về 404 not_covered cùng các lựa chọn thay thế |
GET /v1/company/analyst_ratings | Không bao phủ: xếp hạng của nhà phân tích được cấp phép. Trả về 404 not_covered |
GET /v1/company/transcripts | Không bao phủ: bản ghi cuộc gọi được cấp phép. Trả về 404 not_covered |
GET /v1/company/stock_prices/intraday | Không bao gồm: giá theo thời gian thực và trong ngày là dữ liệu được cấp phép. Trả về 404 not_covered |
GET /v1/company/logo | Logo để nhận diện công ty: một tệp được cấp phép công khai với ghi nguồn, hoặc một ô được tạo ra. JSON, SVG hoặc PNG |
GET /v1/politician_trades | Các giao dịch của thành viên Hạ viện Hoa Kỳ được báo cáo trong các báo cáo giao dịch định kỳ, đúng như đã nộp, kèm báo cáo chính thức. Không có giá. Việc sử dụng bị giới hạn bởi 5 U.S.C. 13107(c)(1): đọc data.notice |
GET /v1/company/segments | Các số liệu phân khúc theo báo cáo gốc (kinh doanh, địa lý, sản phẩm) |
GET /v1/company/ownership/insider_holders | Những gì mỗi insider sở hữu sau Form 4 hoặc 5 gần nhất của họ |
GET /v1/company/ownership/funds | Các quỹ nắm giữ công ty trong Form N-PORT gần nhất của họ |
GET /v1/funds | Các quỹ Form N-PORT kèm báo cáo gần nhất của họ |
GET /v1/fund/holdings | Các khoản nắm giữ Form N-PORT của một quỹ |
GET /v1/company/kpis | Các chỉ số điều chỉnh và hoạt động do công ty báo cáo, mỗi chỉ số đều có trích dẫn |
GET /v1/company/dividend_events | Cổ tức tiền mặt kèm ngày tháng đúng như đã nộp |
GET /v1/company/ownership/insider_holdings | Các dòng nắm giữ của Form 3, Form 4 và Form 5 |
GET /v1/fund/profile | Loại quỹ từ N-CEN và phí các loại cổ phiếu của nó |
GET /v1/fund/nav | Tài sản ròng của quỹ theo tháng báo cáo, lợi nhuận hàng tháng được báo cáo của từng lớp cổ phần cùng chỉ số lợi nhuận của chúng tôi, và NAV trên mỗi cổ phần của quỹ đóng, từ hồ sơ nộp SEC. Không cung cấp NAV hàng ngày |
GET /v1/identifiers/xref | Từ một định danh, trả về công ty hoặc quỹ mà định danh đó chỉ tới và các định danh mở khác, mỗi định danh kèm nguồn |
GET /v1/identifiers/master | Các định danh mở của mọi công ty, có phân trang |
GET /v1/company/stock_prices/returns | Lợi nhuận giá, tổng lợi nhuận và mức sụt giảm tối đa trên các khung thời gian tiêu chuẩn, được tính từ các thanh giá cuối ngày và các đợt chia tách cùng cổ tức đã nộp SEC |
GET /v1/company/identifiers | LEI và FIGI với bằng chứng của họ |
GET /v1/company/stock_prices | Các thanh giá hàng ngày được xây dựng chỉ từ giao dịch trên IEX. Không phải consolidated tape. Mặc định là giá trị thô; adjust=splits hoặc adjust=total_return thêm các giá trị đã điều chỉnh |
GET /v1/screen | Sàng lọc mọi công ty được bao phủ theo các chỉ số của kỳ gần nhất |
POST /v1/verify | Kiểm tra một con số với giá trị đã nộp |
GET /v1/changes | Các dữ kiện bắt đầu được biết đến kể từ một thời điểm |
POST /v1/request-data | Hãy cho chúng tôi biết dữ liệu bạn cần nhưng không tìm thấy. Không cần key, không bao giờ bị tính phí, được xem xét hàng tuần. Xem cách yêu cầu |
GET /v1/request-data | Phần thân của POST /v1/request-data nhận |
GET /v1/request-data/{id} | Trạng thái của một yêu cầu: mới, đã phân loại, đã lên kế hoạch, đã xong hoặc wontfix |
GET /v1/requested | Đã yêu cầu và đã giao: các yêu cầu đã được xem xét kèm số lượng, không có thông tin người gửi |
GET /proof/{id} | Bằng chứng cho một giá trị được cung cấp |
GET /v1/company/line_items | Một dòng được báo cáo theo nhãn và kỳ: các dòng chi tiết theo báo cáo gốc, số liệu phân khúc, chỉ số công ty và hướng dẫn |
GET /v1/screen/nl | Một bộ lọc ngôn ngữ tự nhiên: câu hỏi được phân tích thành các bộ lọc sàng lọc (bởi mô hình AI hoặc theo quy tắc cố định, có gắn nhãn) và chạy dưới dạng GET /v1/screen |
GET /v1/ask | Một câu trả lời do AI viết về một công ty dựa trên các giá trị mà chính công ty đã nộp, với mọi con số đều được kiểm tra đối chiếu với các dữ kiện được trích dẫn |
GET /v1/news/summary | Bản tóm tắt do AI viết về tin tức trong một ngày dựa trên hồ sơ nộp SEC, hoặc về các sự kiện gần đây của một công ty, từ luồng sự kiện riêng của FinancialMD; mỗi gạch đầu dòng đều trích dẫn các hồ sơ nộp SEC của nó và mọi con số đều được đối chiếu với chúng |
GET /v1/company/ratios/forward | Các tỷ lệ định giá dự phóng dựa trên ước tính theo mô hình của chúng tôi (đầu ra mô hình có gắn nhãn, không bao giờ là đồng thuận), kèm ước tính, khoảng giá trị và lịch sử theo dõi |
GET /v1/company/technicals | Các chỉ báo kỹ thuật (đường trung bình động, RSI, MACD, dải Bollinger, ATR, close range) được tính từ các thanh giá hàng ngày của một sàn duy nhất và các đợt chia tách đã nộp SEC |
GET /v1/pre_ipo | Các công ty đã nộp hồ sơ để lên sàn: các đơn vị đăng ký có S-1 hoặc F-1 được nộp trước bất kỳ báo cáo định kỳ nào, kèm trạng thái, mã cổ phiếu dự kiến và ngày tháng |
GET /v1/pre_ipo/{cik} | Một đơn vị đăng ký pre-IPO: trạng thái và quy tắc áp dụng, các hồ sơ đăng ký, các số liệu tài chính được gắn thẻ và các điều khoản chào bán được đọc từ bản cáo bạch |
GET /v1/fx_rates | Tỷ giá tham chiếu hàng ngày từ các tệp công khai của Ngân hàng Trung ương Châu Âu, giữa bất kỳ đồng tiền nào được cung cấp với bất kỳ đồng tiền nào khác thông qua euro; là tỷ giá tham chiếu, không phải báo giá có thể giao dịch |
GET /v1/research | Các báo cáo nghiên cứu độc lập được cấp phép CC BY 4.0, cũng có thể đọc không mất phí trên trang của nhà xuất bản: tìm kiếm theo công ty, bộ sưu tập, ngôn ngữ, từ khóa và ngày tháng, mỗi báo cáo đều có một bản tóm tắt bằng chính lời của báo cáo |
GET /v1/research/{id} | Một báo cáo nghiên cứu đầy đủ dưới dạng Markdown có cấu trúc: các mục, mã chứng khoán, ngày tháng, nguồn, giấy phép và phần ghi công cần giữ lại khi trích dẫn |
POST /v1/feedback | Hãy cho chúng tôi biết điều gì hiệu quả và điều gì không: một ghi chú, một đánh giá hoặc các lý do. Không cần key, không bao giờ bị tính phí. GET /v1/feedback mô tả nội dung body |
POST /v1/data-errors | Báo cáo một con số mà bạn cho là sai. Nó được đối chiếu ngay với dữ liệu chúng tôi cung cấp và được đối chiếu hằng ngày với hồ sơ nộp SEC. Sau đó dùng GET /v1/data-errors/{id} |
Tài liệu OpenAPI có mọi tham số và schema phản hồi. llms.txt, llms-full.txt và tệp kỹ năng cũng nêu điều tương tự cho agent; https://api.financial.md/docs là tài liệu tham chiếu tương tác và https://api.financial.md/changelog liệt kê các thay đổi.
Kiểm tra một con số
curl -X POST "https://api.financial.md/v1/verify" -H "content-type: application/json" \
-d '{"company":"ticker:AAPL","concept":"income_statement_total_revenues","period":"FY2024","value":391035000000}'Câu trả lời có verdict là matches, differs hoặc unknown, giá trị đã nộp kèm bằng chứng, phần chênh lệch, và scale_hint khi số của bạn sai lệch một bậc thập phân.
Giới hạn
Các lệnh gọi không có key bị giới hạn theo địa chỉ IP, mỗi ngày.
- 10 lệnh gọi có tính phí theo mức dùng: tỷ lệ, sàng lọc, xác minh và mọi route có giá, như báo cáo tài chính chuẩn hóa, phân khúc và KPI
- 1,000 lượt đọc lớp hồ sơ nộp SEC: dữ kiện theo báo cáo gốc, hồ sơ nộp SEC, sở hữu và giá
- 1,000 lượt đọc siêu dữ liệu: thư mục, hồ sơ, chỉ số, bằng chứng và thay đổi
Mỗi phản hồi mang RateLimit-Limit, RateLimit-Remaining và RateLimit-Reset. Một 429 mang Retry-After.
Các lệnh gọi trên api.financial.md không có key không bao giờ bị tính phí. API key đi kèm các gói Terminal + Agent; xem API keys. Agent cũng có thể trả tiền theo mỗi lệnh gọi trên agent.financial.md. Xem Bảng giá.
Phạm vi bao phủ
Phạm vi bao phủ là các công ty nộp hồ sơ với SEC và hiện được niêm yết trên một sàn giao dịch của Mỹ.
- Có các báo cáo tài chính chuẩn hóa cho những đơn vị nộp báo cáo theo US GAAP.
- Những đơn vị nộp báo cáo theo IFRS, như nhiều công ty nước ngoài nộp 20-F hoặc 40-F, có hồ sơ nộp SEC nhưng chưa có báo cáo tài chính chuẩn hóa.
- Các công ty đã bị hủy niêm yết vẫn có trong danh mục cùng với báo cáo tài chính và hồ sơ nộp SEC của họ. Hãy tra cứu theo CIK: họ không có tra cứu theo mã chứng khoán và không có giá, nên lịch sử giá chỉ bao gồm các công ty hiện còn niêm yết.
- Dữ liệu sở hữu đến từ các hồ sơ được nộp kể từ ngày 1 tháng 7 năm 2026, và được cập nhật hằng ngày lúc 13:00 UTC từ chỉ mục hằng ngày của EDGAR: các giao dịch nội bộ từ Form 3, Form 4 và Form 5 của các công ty trong phạm vi bao phủ, cùng mọi Form 13F-HR, nên báo cáo 13F của quý mới sẽ xuất hiện khi các nhà quản lý nộp. Một vị thế 13F chỉ được gắn với một công ty khi một Schedule 13D hoặc 13G cover nêu tên chứng khoán của công ty đó. Với quý kết thúc ngày 30 tháng 6 năm 2026, cách này gắn được 80 percent giá trị được báo cáo; các vị thế còn lại xuất hiện trong danh mục của nhà quản lý dưới tên tổ chức phát hành như đã nộp.
- Các ước tính đồng thuận và bản chép lời cuộc gọi thu nhập không được cung cấp: cả hai đều là dữ liệu được cấp phép. Các phân khúc được cung cấp như đã báo cáo, và tin tức là luồng hồ sơ nộp 8-K.
Khi đã biết công ty nhưng thiếu một bộ dữ liệu, API trả về not_covered và liệt kê các bộ dữ liệu mà công ty đó có.
Máy chủ MCP
Máy chủ MCP bao bọc cùng một API trong 57 công cụ chỉ đọc. Nó dùng MCP Streamable HTTP và không cần tài khoản.
https://mcp.financial.md/mcpHướng dẫn MCP liệt kê các công cụ. Thẻ máy chủ dành cho các sổ đăng ký.
Lỗi
Lỗi có dạng { "error": { code, message, docs, request_id, remedies } }. Danh sách remedies cho biết cần làm gì tiếp theo. Tài liệu tham chiếu lỗi giải thích từng mã.