Bỏ qua nội dung

FinancialMD cho AI agent

FinancialMD là terminal tài chính được xây dựng cho AI agent. Nó 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 đi kèm bằng chứng truy ngược về hồ sơ nộp SEC, và mọi lượt đọc đều có thể thực hiện tại một ngày trong quá khứ, để agent có thể trích dẫn điều mình nói và backtest mà không bị look-ahead.

Bước 1. Kết nối máy chủ MCP

Máy chủ MCP ở https://mcp.financial.md/mcp (Streamable HTTP, không trạng thái). Nó có 57 công cụ chỉ đọc. Đăng nhập là tùy chọn: không có token, nó trả lời trong giới hạn hằng ngày không cần key.

Claude Code:

claude mcp add --transport http financial-md https://mcp.financial.md/mcp

Các ứng dụng khách đọc cấu hình JSON (Cursor, VS Code, Windsurf và các ứng dụng khác):

{
  "mcpServers": {
    "financial-md": { "type": "http", "url": "https://mcp.financial.md/mcp" }
  }
}

Trong Claude hoặc ChatGPT, thêm cùng URL đó làm connector tùy chỉnh. Thẻ máy chủ ở mcp.financial.md/.well-known/mcp.json và metadata OAuth ở mcp.financial.md/.well-known/oauth-protected-resource.

Bắt đầu với company_lookup, sau đó snapshot_as_of (cả ba báo cáo tài chính và các tỷ lệ như được biết tại một ngày, trong một lệnh gọi) hoặc financials_standardized. Dùng verify_value để kiểm tra một con số bạn tìm thấy ở nơi khác.

Bước 2. Thực hiện cuộc gọi API không cần chìa khóa

HTTP API không cần tài khoản và không cần chìa khóa. Cuộc gọi này trả về năm báo cáo lưu chuyển tiền tệ hàng năm gần nhất của Apple, bao gồm cả dòng tiền tự do:

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

Mỗi con số là một value object với proof.accession, proof.form, proof.filed và proof.source_url (hồ sơ nộp SEC trên sec.gov). Thêm as_of=2024-06-30 để đọc những gì được biết vào ngày đó. Đối chiếu một con số với hồ sơ nộp SEC:

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

Không có key, mỗi địa chỉ IP có 10 lượt gọi theo hạn mức mỗi ngày (ratios, screen, verify), 1,000 lượt đọc ở lớp hồ sơ nộp SEC và 1,000 lượt đọc metadata. Mọi phản hồi đều có header RateLimit-*; phản hồi 429 có Retry-After, và mọi nội dung lỗi đều liệt kê cách khắc phục.

Bước 3. Trả tiền theo lượt gọi

agent.financial.md phục vụ các route tương tự cho agent trả tiền theo lượt gọi bằng x402 (USDC trên Base), không cần tài khoản. Một route có giá ở đó sẽ trả về 402 với giá trong header PAYMENT-REQUIRED; ký thanh toán và gửi lại lượt gọi với header PAYMENT-SIGNATURE. Nội dung của phản hồi 402 cũng nêu host không cần key, nơi cùng route đó không bao giờ bị tính phí trong giới hạn hằng ngày.

Giá của mỗi route được ghi trong pricing.json và trong trường x-price của tài liệu OpenAPI. Giá trong phản hồi 402 là giá áp dụng. Lượt gọi thất bại sẽ không bị tính phí.

Tệp cho agent

TệpMô tả
openapi.jsonOpenAPI 3.1. Mỗi operation đều có mô tả và một yêu cầu ví dụ với mã chứng khoán thực tế
llms.txtHướng dẫn ngắn: host, id công ty, value object, lượt đọc tại một thời điểm (point-in-time), giới hạn
llms-full.txtTất cả trong một tệp văn bản: mọi route, công thức tỷ số và cách làm
skill.mdAgent Skill với các cách làm chỉ cần một lượt gọi
skills.zipCác Agent Skill (SKILL.md) gọi công cụ MCP, gộp trong một tệp zip
pricing.jsonGiá theo lượt gọi, giới hạn hằng ngày và trạng thái thanh toán
mcp.jsonThẻ máy chủ MCP: công cụ, xác thực và tài liệu
server.jsonMục trong MCP Registry
agent.jsonMột chỉ mục của mọi endpoint và tài liệu ở trên

Những gì agent có thể dựa vào

  • Mọi con số đều có nguồn: accession number của hồ sơ nộp SEC, form, ngày nộp hồ sơ, thẻ XBRL và một liên kết tới tài liệu trên sec.gov. GET /proof/{id} hiển thị các dữ kiện thô đằng sau nó.
  • Tại một thời điểm: known.from và known.to cho biết khi nào mỗi giá trị là số liệu được nộp mới nhất. as_of, original=true và history=true đọc dữ liệu quá khứ mà không nhìn trước và hiển thị các số liệu trình bày lại.
  • Câu trả lời ngắn: một lượt gọi báo cáo chỉ trả về các kỳ được yêu cầu; kết quả công cụ MCP bắt đầu bằng bản tóm tắt một dòng trước dữ liệu có cấu trúc.
  • Mã chứng khoán, CIK hoặc tên: company=ticker:AAPL, company=cik:320193, hoặc GET /v1/companies?q=Apple.
  • Phạm vi bao phủ: các đơn vị nộp hồ sơ SEC hiện được niêm yết trên một sàn giao dịch ở US; báo cáo chuẩn hóa cho các đơn vị nộp theo US GAAP. Chỉ cung cấp thông tin, không phải tư vấn đầu tư.