API 및 MCP 문서

첫 호출 실행하기

API는 HTTPS를 통해 JSON을 제공합니다. 이 호출은 Apple의 최근 5개 연간 손익계산서를 반환합니다. 키는 필요하지 않습니다.

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가 회사에 부여하는 ID

접두사 없는 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는 이후 공시 서류에서 수치가 변경되어 재작성된 경우에만 참이며, 이때 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에 따라 보고하는 공시 서류 제출 기업에는 표준화된 재무제표가 제공됩니다.
• Form 20-F 또는 40-F를 제출하는 다수의 외국 기업 등 IFRS에 따라 보고하는 공시 서류 제출 기업에는 공시 서류가 있지만, 표준화된 재무제표는 아직 없습니다.
• 상장폐지된 기업도 재무제표 및 공시 서류와 함께 디렉터리에 포함되어 있습니다. CIK로 조회하세요. 티커 조회와 가격 데이터는 제공되지 않으므로, 가격 이력은 현재 상장된 기업만 포함합니다.
• 지분 보유 데이터는 July 1, 2026 이후 제출된 공시 서류에서 가져오며, EDGAR 일일 인덱스를 바탕으로 매일 13:00 UTC에 업데이트됩니다. 여기에는 제공 범위 내 기업의 Forms 3, 4 and 5에 기재된 내부자 거래와 모든 Form 13F-HR가 포함되므로, 새 분기의 13F 보고서는 운용사가 제출하는 대로 반영됩니다. 13F 보유 포지션은 Schedule 13D 또는 13G의 표지에 해당 증권이 명시된 경우에만 기업과 연결됩니다. June 30, 2026에 종료된 분기의 경우, 이 방식으로 보고된 가치의 80퍼센트가 연결됩니다. 나머지 포지션은 공시된 발행인 명칭으로 운용사의 포트폴리오에 표시됩니다.
• 컨센서스 추정치와 실적발표 컨퍼런스콜 녹취록은 제공하지 않습니다. 둘 다 라이선스 데이터입니다. 부문별 데이터는 보고된 그대로 제공하며, 뉴스는 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 목록은 다음에 할 일을 안내합니다. 오류 참조 문서에서 각 코드를 설명합니다.