Bỏ qua nội dung

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, hay ticker:AAPL.XNAS để đặt tên cho sàn giao dịch
  • cik:320193, số công ty của SEC
  • fmd_<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-30 trên bất kỳ route đọc nào đều trả về thông tin đã được biết tại thời điểm đó.
  • original=true trả về phiên bản được báo cáo đầu tiên của mỗi kỳ.
  • history=true trả 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

RouteNội dung trả về
GET /v1/companiesThư mục công ty với bộ lọc và phân trang
GET /v1/company/profileHồ sơ, danh sách và các bộ dữ liệu có sẵn
GET /v1/company/metricsCác hàng khái niệm trong mẫu của công ty
GET /v1/company/financials/{statement}/standardizedMột báo cáo chuẩn hóa
GET /v1/company/financials/{statement}/as_reportedCác khoản mục riêng của đơn vị nộp hồ sơ, kèm thẻ
GET /v1/company/ratiosCá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/filingsChỉ 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}/factsMọi dữ kiện đã ánh xạ mà một hồ sơ nộp SEC đã gắn thẻ
GET /v1/filing/{accession}/documentLiê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/insidersGiao dịch nội bộ từ Form 3, Form 4 và Form 5
GET /v1/company/ownership/institutionalCác chủ sở hữu theo Form 13F của một công ty, theo quý
GET /v1/ownership/institutional/holdersCác nhà quản lý 13F
GET /v1/ownership/institutional/holdingsDanh mục 13F của một nhà quản lý trong một quý
GET /v1/company/splitsCá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/dividendsCổ 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_calendarThô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/eventsCác mục 8-K: nguồn cấp sự kiện dựa trên hồ sơ nộp SEC
GET /v1/newsCá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/feedNguồ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_releasesCá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_materialsTà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_calendarCá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/filingsTì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/coverageMỗ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/estimatesCá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/consensusKhô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_ratingsKhô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/transcriptsKhô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/intradayKhô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/logoLogo để 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_tradesCá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/segmentsCá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_holdersNhữ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/fundsCác quỹ nắm giữ công ty trong Form N-PORT gần nhất của họ
GET /v1/fundsCác quỹ Form N-PORT kèm báo cáo gần nhất của họ
GET /v1/fund/holdingsCác khoản nắm giữ Form N-PORT của một quỹ
GET /v1/company/kpisCá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_eventsCổ tức tiền mặt kèm ngày tháng đúng như đã nộp
GET /v1/company/ownership/insider_holdingsCác dòng nắm giữ của Form 3, Form 4 và Form 5
GET /v1/fund/profileLoại quỹ từ N-CEN và phí các loại cổ phiếu của nó
GET /v1/fund/navTà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/xrefTừ 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/masterCác định danh mở của mọi công ty, có phân trang
GET /v1/company/stock_prices/returnsLợ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/identifiersLEI và FIGI với bằng chứng của họ
GET /v1/company/stock_pricesCá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/screenSà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/verifyKiểm tra một con số với giá trị đã nộp
GET /v1/changesCác dữ kiện bắt đầu được biết đến kể từ một thời điểm
POST /v1/request-dataHã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-dataPhầ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_itemsMộ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/nlMộ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/askMộ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/summaryBả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/forwardCá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/technicalsCá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_ipoCá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_ratesTỷ 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/researchCá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/feedbackHã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-errorsBá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/mcp

Hướ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ã.