API 與 MCP 文件

第一次呼叫

API 透過 HTTPS 傳回 JSON。這次呼叫會傳回 Apple 最近五個年度的損益表，不需要金鑰。

curl "https://api.financial.md/v1/company/financials/income_statement/standardized?company=ticker:AAPL&period_type=annual&limit=5"

報表可以是 income_statement、balance_sheet、cash_flow 或 supplemental。期間類型可以是 annual、quarterly、ltm 或 ytd。

指定公司

每個公司路由都接受 company 參數。

• ticker:AAPL，或用 ticker:AAPL.XNAS 指明交易所
• cik:320193，即 SEC 的公司編號
• fmd_<id>，即 FinancialMD 指派給公司的識別碼

只寫 AAPL 會被視為股票代號，只寫數字會被視為 CIK。回應會在 meta.company.matched_by 中說明比對方式。

讀取數值

成功的回應是 { data, meta }。data 裡的數字從不單獨出現，而是數值物件：

{
  "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 是這個數字作為最新申報數字的時間區間。只有當後續申報文件變更了這個數字時，restated 才為 true，此時 restatement_kind 會說明變更方式。proof.id 可透過 GET /proof/{id} 查到對應的申報文件及該數值背後的原始事實。

依當時已知的資訊讀取過去

• 在任何讀取路由加上 as_of=2024-06-30，會傳回那一刻已知的內容。
• original=true 會傳回每個期間首次申報的版本。
• history=true 會傳回每個期間的所有版本，由舊到新排列。
• GET /v1/changes?since=<timestamp> 會列出此後新得知的事實。

路由

OpenAPI 文件列出了全部參數和回應結構。llms.txt、llms-full.txt 和技能檔案向代理程式說明相同內容；https://api.financial.md/docs 是互動式參考文件，而 https://api.financial.md/changelog 列出了變更。

核對一個數字

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}'

回傳內容包括值為 matches、differs 或 unknown 的 verdict、附證據的申報值、差額，以及當你的數字相差 10 的整數次方倍時給出的 scale_hint。

限額

不帶金鑰的呼叫按 IP 位址、按日設限。

• 25 次計量呼叫：比率、篩選和核驗
• 1,000 次申報層讀取：報表、原始申報事實、申報文件、持股和價格
• 1,000 次中繼資料讀取：目錄、公司資料、指標、證據和變更

每個回應都帶有 RateLimit-Limit、RateLimit-Remaining 和 RateLimit-Reset。429 回應帶有 Retry-After。

更高限額的 API 金鑰尚未發放。請見 API 金鑰。api.financial.md 上的呼叫免費。代理可在 agent.financial.md 上按次付費。請見價格。

涵蓋範圍

涵蓋向 SEC 申報、且目前在美國交易所上市的公司。

• 按 US GAAP 申報的公司有標準化報表。
• 按 IFRS 申報的公司，例如許多提交 Form 20-F 或 40-F 的外國公司，有申報文件，但暫時沒有標準化報表。
• 已下市的公司列於公司目錄中，並附有報表和申報文件。請用 CIK 查詢：這些公司無法按股票代碼查找，也沒有價格，因此歷史價格僅涵蓋目前上市的公司。
• 持股資料來自 July 1, 2026 以來提交的申報文件，每天於 13:00 UTC 從 EDGAR 每日索引更新：涵蓋公司的 Form 3、Form 4 和 Form 5 內部人交易，以及所有 Form 13F-HR，因此新季度的 13F 報告會隨管理人提交而陸續收錄。只有當某份 Schedule 13D 或 13G 封面載明該證券時，13F 持倉才會歸屬至對應公司。在截至 June 30, 2026 的季度，按申報價值計，已歸屬的部分占 80 percent；其餘持倉在管理人的投資組合中按申報的發行人名稱列出。
• 不提供市場共識預估和法說會逐字稿：兩者都屬於授權資料。部門資料按申報原樣提供，新聞則是 8-K 申報文件的資訊流。

如果公司已收錄但缺少某個資料集，API 會回傳 not_covered，並列出已有的資料集。

MCP 伺服器

MCP 伺服器將同一套 API 封裝成 50 個唯讀工具。它使用 MCP Streamable HTTP，無需帳號。

https://mcp.financial.md/mcp

MCP 指南列出了這些工具。伺服器卡片供登錄目錄使用。

錯誤

錯誤的格式是 { "error": { code, message, docs, request_id, remedies } }。remedies 清單說明下一步該怎麼做。錯誤說明解釋每個錯誤碼。