opendart-client

English | 한국어

한국 OpenDART(금융감독원 전자공시시스템)의 공시 데이터를 읽어옵니다.

기업개황과 기간별 공시 목록, 재무제표와 주요 재무지표, 배당·증자·감자, 최대주주·소액주주· 임원·직원 현황과 임원 보수, 합병·분할·영업양수도·자기주식 취득 같은 주요 결정, 지분공시(5%룰), 증권신고서까지 다룹니다.

1. 설치

pip install opendart-client

무료 API 키(40자리)는 https://opendart.fss.or.kr 에서 발급받으실 수 있습니다. 키는 OpenDart(api_key=...), 환경변수 OPENDART_API_KEY, config 파일 순으로 찾습니다.

config 파일 (모든 OS 공통, 권장) — ~/.config/opendart-client/credentials.json 파일을 만들고 아래를 넣으세요.

{ "OPENDART_API_KEY": "..." }

0.3.0부터 config 파일의 키 이름이 api_key → OPENDART_API_KEY로 바뀌었습니다(환경변수와 동일). 예전 파일을 쓰고 계시면 필드 이름만 바꿔 주세요.

환경변수 — 셸에 따라 다릅니다. macOS·Linux(bash/zsh):

export OPENDART_API_KEY=...

Windows PowerShell은 setx OPENDART_API_KEY "..."(영구) 또는 $env:OPENDART_API_KEY = "..."(현재 세션)를 씁니다.

2. 빠른 시작

from opendart_client import OpenDart

dart = OpenDart(api_key="...")          # 또는 환경변수 OPENDART_API_KEY

# 이름 / 티커 / 초성 / 오타 -> corp_code
code = dart.resolver().resolve("삼성전자")          # "00126380"

# 기간 내 공시 목록
rows = dart.disclosure.search(
    corp_code=code, begin_date="20260101", end_date="20260131",
)

# 재무제표, 그리고 모든 주요사항(이벤트)
dart.finance.single_accounts(code, fiscal_year=2025)
dart.event.paid_in_capital_increase(
    corp_code=code, begin_date="20260101", end_date="20260131",
)

회사코드(corp_code)는 정식 이름·티커·초성(ㅅㅅㅈㅈ)·오타 어느 것으로도 찾을 수 있습니다 (dart.resolver().resolve(...)). 해당 자료가 없는 조회는 빈 결과로 옵니다.

반환은 list[dict]이라 pandas·polars 표(DataFrame)로 바로 만들 수 있습니다.

# pandas
import pandas as pd
pd.DataFrame(rows)

# polars
import polars as pl
pl.DataFrame(rows)

3. API

최상위 도우미 — 회사코드를 찾거나 전체 목록을 받습니다.

report_code — 정기보고서·재무정보 메서드가 공통으로 받는 기간 코드(기본값 11011).

disclosure — 공시정보

report — 정기보고서 주요정보

모두 (corp_code, *, fiscal_year, report_code="11011").

finance — 재무정보

ownership — 지분공시

event — 주요사항보고서

모두 (corp_code, *, begin_date, end_date).

registration — 증권신고서

모두 (corp_code, *, begin_date, end_date).

4. 터미널

설치하면 opendart 명령이 등록됩니다(python -m opendart_client로도 실행). 키는 위 세 곳(인자·환경변수·config 파일) 중 하나에서 읽습니다.

opendart resolve 삼성전자                    # 이름·티커·초성·오타 -> 회사코드 (+후보)
opendart search  삼성전자 --begin 20260101   # 기간 내 공시 목록
opendart company 삼성전자                    # 기업개황
opendart finance 삼성전자 --year 2024        # 주요계정 요약 (매출·영업이익·순이익·자산/부채/자본)

주요 옵션:

<회사> 자리엔 이름·티커·초성·오타·8자리 회사코드 아무거나 넣으면 내부에서 회사코드로 바꿔 조회합니다. 각 명령은 기본이 읽기 좋은 요약이고, --json은 전체 결과를 냅니다. 전체 옵션은 --help로 확인하세요.

resolve는 회사코드·티커·이름 순으로 정렬해 보여주며, 비상장사는 티커 자리가 ------입니다.

$ opendart resolve 삼성전자
00126380  005930  삼성전자
00252074  ------  삼성전자판매
00366997  ------  삼성전자로지텍

finance는 회사명·보고서와 함께 주요계정을 정렬해 보여줍니다(--separate로 별도재무제표).

$ opendart finance 삼성전자 --year 2024
삼성전자 (00126380)  2024 사업보고서  (CFS 연결)
매출액       300,870,903,000,000
영업이익      32,725,961,000,000
당기순이익    34,451,351,000,000
자산총계     514,531,948,000,000
부채총계     112,339,878,000,000
자본총계     402,192,070,000,000

5. AI 코딩 에이전트에서 사용

이 저장소는 Claude Code·Codex용 플러그인 마켓플레이스도 겸합니다 — resolve·search· company·finance를 opendart 명령을 호출하는 스킬로 제공합니다. 먼저 위에서 패키지를 설치하고 API 키를 설정하세요.

5.1. Claude Code

Claude Code 채팅창에서 마켓플레이스를 추가하고 설치합니다:

/plugin marketplace add seokhoonj/opendart-client
/plugin install opendart@opendart-client

그런 다음 평범하게 물어보거나("삼성전자 회사코드 찾아줘", "삼성전자 최근 공시 보여줘"), 스킬을 직접 호출하세요 — /opendart:resolve 삼성전자, /opendart:finance 삼성전자 --year 2024.

5.2. Codex

터미널에서 마켓플레이스를 추가하고 설치합니다:

codex plugin marketplace add seokhoonj/opendart-client
codex plugin add opendart@opendart-client

resolve·search·company·finance 스킬은 회사 이름·티커에 반응하며, opendart <명령> <회사>로 직접 실행해도 됩니다.

플러그인으로 설치하지 않고 쓰려면, 스킬을 스킬 디렉터리에 symlink한 뒤 접두사(opendart:) 없이 /resolve처럼 부르면 됩니다:

ln -s "$PWD/plugins/opendart/skills/resolve" ~/.claude/skills/resolve   # Claude Code → /resolve
ln -s "$PWD/plugins/opendart/skills/resolve" ~/.codex/skills/resolve    # Codex → $opendart:resolve

Claude Code는 바로 인식하고, Codex는 재시작해야 로딩됩니다.

6. 라이선스

MIT