Koreafilings Mcp

Korea Filings

韓国企業の開示情報（DART · 전자공시）を機械処理可能な英語に変換する HTTP API です。開示情報フィードは無料です。市場を閲覧したり、特定の銘柄をウォッチしたりして、英語の企業名、英語の開示種別、重要度スコア、DART 原文へのリンクを取得できます。ウォレットも API キーも登録も不要です。有料の呼び出しで説明を取得できます。特定の開示内容を要約する AI サマリーを、x402 経由で Base 上、0.005 USDC で利用できます。多様なデータソースを必要とし、サブスクリプションより従量課金を好む自律型 AI エージェントと個人のエージェント開発者向けに構築されています。

現在提供している韓国の金融データは表面的な一例にすぎませんが、導入を促進する価値提案は、月額契約ではなく従量課金、独自の認証方式ではなく標準的な x402 です。同じ形は、ほかのあらゆる公開記録 API にも適用できます。API キーも登録も調達プロセスも不要です。

ライブ：https://koreafilings.com · API は https://api.koreafilings.com · インタラクティブなドキュメントは /swagger-ui で確認できます。

機能

DART の生データは無料ですが、韓国語で記載され、人間の開示担当者向けに構造化されており、LLM 向けではありません。Korea Filings はすべての開示情報を、構造化され、キャッシュされた英語の要約付き JSON ペイロードに変換します。エージェントは韓国企業を名前で無料検索し、その銘柄のサマリーをまとめて取得する際に、有料の x402 呼び出しを 1 回行います。サマリーは開示本文そのもの（タイトルだけではありません）を基に生成されるため、定量的なイベントでは、韓国語の原文から抽出された実際の金額、希薄化率、取引相手名、発効日が返されます。軽微なガバナンス関連のイベントと、定量的な資金調達の例を 2 つ示します。

{
  "rcptNo": "20260424900874",
  "summaryEn": "Global SM's stock trading was suspended at 09:00 KST on April 24, 2026, pending an updated electronic registration tied to a planned 1-for-2 stock consolidation. The suspension follows a board resolution dated April 21; trading resumes April 26 once the registration completes. Existing shareholders' record positions are unaffected.",
  "importanceScore": 8,
  "eventType": "TRADING_SUSPENSION",
  "sectorTags": ["Capital Goods"],
  "tickerTags": ["095440"],
  "actionableFor": ["traders"],
  "generatedAt": "2026-04-24T08:47:51Z"
}

定量的なイベント — Samsung Electronics の配当決定。Base メインネットでの有料呼び出しからライブでそのまま返された結果です（オンチェーンで決済済み）。

{
  "rcptNo": "20260430800106",
  "summaryEn": "Samsung Electronics decided on a quarterly cash dividend of KRW 372 per common share and KRW 372 per preferred share, totaling KRW 2,453,315,636,604. The dividend yield is 0.2% for common shares and 0.3% for preferred shares. The record date is March 31, 2026, with payment scheduled for May 29, 2026.",
  "importanceScore": 7,
  "eventType": "DIVIDEND_DECISION",
  "sectorTags": ["Technology Hardware & Equipment"],
  "tickerTags": ["005930"],
  "actionableFor": ["traders", "long_term_investors"],
  "generatedAt": "2026-05-06T07:29:45.911215Z"
}

キャッシュが競争優位の源です。開示情報を最初にリクエストしたエージェントが LLM のコストを負担し、同じ rcpt_no をリクエストする後続のエージェントは、ほぼコストゼロの DB 検索を利用しながら、サマリーごとに同じ一律 0.005 USDC を支払います。銘柄ごとの一括呼び出しでも同じキャッシュ行が利用されるため、サマリー 5 件の呼び出しは、転送される USDC 1 件に対して 5 回のキャッシュ検索で済みます。導入が進むほど利益率が積み上がります。

使い方

利用環境に合った方法を選んでください。3 つとも内部では同じ x402 フローを使用します。PAYMENT-SIGNATURE ヘッダーに署名するウォレットが、利用者の ID になります。API キーは不要です。登録も不要です。

TypeScript SDK

npm install koreafilings

import { KoreaFilings } from 'koreafilings';

const client = new KoreaFilings({
  privateKey: process.env.PAYER_PRIVATE_KEY as `0x${string}`,
  network: 'base',
});

// 1. Free — Korean / English company name → six-digit KRX ticker
const matches = await client.findCompany('Samsung Electronics');
const ticker = matches[0]!.ticker; // "005930"

// 2. Paid — 0.005 × limit USDC, settled via x402 in one round-trip
const filings = await client.getRecentFilings(ticker, 5);
for (const f of filings) {
  console.log(`[${f.importanceScore}/10] ${f.eventType}: ${f.summaryEn}`);
}
console.log('paid:', client.lastSettlement?.transaction);

TypeScript ／ JavaScript の呼び出し元向けのソースです。Node 18 以降、ブラウザー、Cloudflare Workers、Vercel Functions で動作します。SDK の完全なドキュメントは sdk/typescript/README.md をご覧ください。

Python SDK

pip install koreafilings

from koreafilings import Client

with Client(private_key="0x...", network="base") as client:
    # 1. Free name → ticker resolution
    matches = client.find_company("Samsung Electronics")
    ticker = matches[0].ticker  # "005930"

    # 2. Paid batch summary fetch (0.005 × limit USDC)
    filings = client.get_recent_filings(ticker, limit=5)
    for f in filings:
        print(f"[{f.importance_score}/10] {f.event_type}: {f.summary_en}")
    print("paid:", client.last_settlement.tx_hash)

MCP サーバー（Claude Desktop、Cursor、Continue、…）

uv tool install koreafilings-mcp

MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "koreafilings": {
      "command": "uv",
      "args": ["tool", "run", "koreafilings-mcp"],
      "env": {
        "KOREAFILINGS_PRIVATE_KEY": "0x...",
        "KOREAFILINGS_NETWORK": "base"
      }
    }
  }
}

5 つのツールを利用できます。うち 3 つは検索用の無料ツール、2 つは有料ツールです。

• find_company(query) — 無料。韓国語名、英語名、またはティッカーを使って、KRX 上場企業 3,961 社をトライグラムであいまい検索します。
• list_recent_filings(limit) — 無料。市場全体の DART 最新情報フィードです（メタデータのみ。有料情報を取得するかどうかはエージェントが判断できます）。
• get_pricing() — 無料。ウォレット、ネットワーク、USDC コントラクト、エンドポイントごとの価格をリアルタイムで取得します。
• get_recent_filings(ticker, limit) — 0.005 × limit USDC の有料ツール。指定したティッカーの AI 要約をまとめて取得します。オンチェーン決済のトランザクションハッシュも含まれます。
• get_disclosure_summary(rcpt_no) — 0.005 USDC の有料ツール。既知の受付番号に対する AI 要約を 1 件取得します。

エージェントの自然な処理の流れは find_company → get_recent_filings です。1 回の無料呼び出しで名前をティッカーに変換し、1 回の有料呼び出しでそのティッカーの要約を取得します。

curl / 直接 HTTP

# 1) Resolve a company name to a ticker. Free, no wallet needed.
curl 'https://api.koreafilings.com/v1/companies?q=Samsung+Electronics&limit=1'
#   HTTP/2 200
#   { "matches": [{ "ticker": "005930", "nameKr": "삼성전자",
#                   "nameEn": "SAMSUNG ELECTRONICS CO.,LTD.",
#                   "market": "KOSPI", ... }] }

# 2) Probe the paid endpoint without payment — server tells you the
#    exact USDC amount it wants for `limit=N` summaries.
curl -i 'https://api.koreafilings.com/v1/disclosures/by-ticker?ticker=005930&limit=3'
#   HTTP/2 402
#   payment-required: <base64 PaymentRequired payload, amount = 15000>
#   { "x402Version": 2, "accepts": [{ "scheme": "exact",
#       "amount": "15000", "asset": "USDC", "payTo": "0x8467…",
#       ... }], ... }

# 3) Sign an EIP-3009 TransferWithAuthorization for one of the entries
#    in `accepts`, base64-encode the signed PaymentPayload, and resend
#    with the PAYMENT-SIGNATURE header (x402 v2 transport spec).
#    See testclient/payer.py for a ~150-line reference implementation.
curl -H "PAYMENT-SIGNATURE: $SIGNED" \
     'https://api.koreafilings.com/v1/disclosures/by-ticker?ticker=005930&limit=3'
#   HTTP/2 200
#   payment-response: <base64 SettlementResponse with tx hash>
#   {
#     "ticker":     "005930",
#     "chargedFor": 3,         # what the agent paid for (`limit`)
#     "delivered":  3,         # how many summaries were actually returned
#     "count":      3,         # alias of `delivered` for older clients
#     "summaries":  [ { "rcptNo": "...", "summaryEn": "...", ... }, … ]
#   }
# `chargedFor` and `delivered` diverge when a ticker has fewer recent
# filings than `limit` or when one of those filings does not yet have
# an AI summary in cache.

固定価格 0.005 USDC の /v1/disclosures/summary?rcptNo=… エンドポイントも引き続き利用できます。すでに 14 桁の受付番号を持っている呼び出し元向けで、x402 フローは同じですが、amount = 5000 で要約を 1 件取得します。

価格

Base 上の USDC での呼び出しごとの価格です。無料エンドポイント（/v1/companies、/v1/companies/{ticker}、/v1/disclosures/recent）では支払いチャレンジが発生しないため、エージェントは支払い前に情報を閲覧できます。また、フィードは条件付き GET（ETag / If-None-Match → 304）にも対応しているため、ループでポーリングしても双方の負荷を抑えられます。

エンドポイント	メソッド	価格（USDC）
/v1/disclosures/by-ticker?ticker=…&limit=N	GET	0.005 × N
/v1/disclosures/summary?rcptNo=…	GET	0.005

by-ticker エンドポイントの結果ごとの価格は、402 チャレンジで動的に宣言されます。limit=N の場合、サーバーは 0.005 × N USDC を accepts[0].amount に署名して設定するため、呼び出し元はウォレットの承認前に正確な請求額を確認できます。固定価格の要約取得エンドポイントは 0.005 USDC のままで、別の場所で 14 桁の受付番号をすでに取得している呼び出し元に適しています。

機械可読な価格情報の完全な記述（現在のウォレット、ネットワーク、USDC コントラクト、有料エンドポイントの一覧）は /v1/pricing にあります。エージェントによる検出情報は /.well-known/x402 で提供しています。同じ有料アクションのインターフェースは、Agent Web Protocol（AWP）形式でも /.well-known/agent.json に公開されています。また、AI エージェント向けの平易な英語での概要は /llms.txt にあります。

Coinbase CDP ファシリテーター経由で Base mainnet 上で稼働しています。有料呼び出しはすべて、オンチェーンでの実際の transferWithAuthorization を 1 回のホップで決済します。販売者のウォレット、ネットワーク、USDC コントラクトアドレスは /v1/pricing と /.well-known/x402 から確認できるため、エージェントは署名する前に送信先を検証できます。

アーキテクチャ

3つの論理サブシステムが、1つのSpring Bootアプリケーションを共有しています。

1. 取り込み — DART Open APIを30秒間隔でポーリングし、rcpt_noで重複を排除し、未加工のメタデータをPostgresに保存して、要約ジョブをキューに登録します。
2. 要約 — 要約ジョブを処理し、複雑さを分類して、Gemini 2.5 Flash-Liteにルーティングします（Resilience4jによるレート制限、サーキットブレーカー、リトライを適用）。英語の要約、ティッカー／セクタータグ、監査レコードをllm_auditに保存します。
3. 有料API — X402PaywallInterceptorの背後にあるSpring MVCコントローラーです。 各リクエストで、PAYMENT-SIGNATURE（または0.2.xクライアント向けの旧式のX-PAYMENTエイリアス）を読み取り、ファシリテーターで署名を検証し、Redisでリプレイを確認し、200レスポンス時に決済を確定し、ResponseBodyAdviceを介してオンチェーントランザクションハッシュを含むPAYMENT-RESPONSEを付与します。/settleが例外をスローするか拒否した場合、本文はx402 v2の決済失敗形式に書き換えられます（HTTP 402と、失敗したSettlementResponseをBase64エンコードして格納したPAYMENT-RESPONSEを返し、本文は空にします）。これにより、ファシリテーターの停止中に有料データが未払いで漏れることを防ぎます。@X402Paywallのないハンドラーメソッドではインターセプターが処理を短絡するため、/v1/pricing、/.well-known/x402、OpenAPIドキュメントは認証不要のままです。

402チャレンジは x402 v2トランスポート仕様に準拠しています。 PAYMENT-REQUIREDヘッダーには、Base64エンコードされた PaymentRequiredペイロードが格納されます（bazaar 拡張では、AIエージェントが検出できるよう入出力スキーマを宣言します）。一方、本文にはv1互換のJSONコピーが含まれるため、古いクライアントも引き続き動作します。

スタック：Java 21、Spring Boot 3.4、PostgreSQL 16、Redis 7、Docker Compose、Cloudflare Tunnel、Cloudflare Workers。詳細については docs/ARCHITECTURE.mdを参照してください。

リポジトリ構成

.
├── src/                  # Spring Boot application source
├── sdk/python/           # `koreafilings` Python SDK (PyPI)
├── sdk/typescript/       # `koreafilings` TypeScript SDK (npm)
├── mcp/                  # `koreafilings-mcp` MCP server (PyPI)
├── landing/              # Marketing landing page (Cloudflare Workers)
├── testclient/           # Reference Python x402 client (testnet payer)
├── docs/
│   ├── ARCHITECTURE.md   # System design
│   ├── PRD.md            # Product requirements
│   ├── ROADMAP.md        # Six-week launch plan
│   └── STATUS.md         # Operator handoff notes
├── Dockerfile            # Multi-stage prod build (eclipse-temurin:21)
├── docker-compose.yml    # postgres + redis + app + cloudflared
└── build.gradle.kts      # Gradle (Kotlin DSL)

ローカル開発

git clone https://github.com/OldTemple91/korea-filings-api.git
cd korea-filings-api

cp .env.example .env
# Fill in:
#   POSTGRES_PASSWORD     (any strong password)
#   DART_API_KEY          (free, register at https://opendart.fss.or.kr/)
#   GEMINI_API_KEY        (free tier, https://aistudio.google.com/apikey)
#   X402_RECIPIENT_ADDRESS (your receiving wallet — only the address)

docker compose up -d postgres redis
./gradlew bootRun

ローカルインスタンスに対して実際のx402決済を試すには、 testclient/.env.testclient.exampleをtestclient/.env.testclientにコピーし、 ウォレットの秘密鍵を入力してから（Base mainnet USDCを1〜2ドル分入金した新しい使い捨てウォレットを使うのが安全です）、python testclient/payer.pyを実行してください。公開テストネットのファシリテーターを使ってローカル開発する場合は、 X402_FACILITATOR_URLを https://www.x402.org/facilitatorに設定し、.envでBase Sepoliaのパラメーターを使用してください。

ステータス

Base mainnetで稼働中。オンチェーン決済の検証済みです。 MVPの機能：

• DARTのリアルタイム取り込み（30秒間隔でポーリング）
• 重要度スコアリングとセクター／ティッカータグ付けを備えたGemini 2.5 Flash-Liteによる要約
• エージェントが呼び出しを検出できるbazaar拡張付きx402 v2ペイウォール
• /.well-known/x402による検出
• OpenAPI 3仕様は/v3/api-docsで提供。インタラクティブなSwagger UIも利用可能
• PyPIで公開中のPython SDK（koreafilings 0.3.4）およびMCPサーバー（koreafilings-mcp 0.3.1）
• 無料の名称→ティッカー解決（find_company）と無料の最近のフィード（list_recent_filings）により、エージェントは支払い前に閲覧可能
• 結果ごとに課金されるバッチエンドポイント（/v1/disclosures/by-ticker?ticker=…&limit=N）。402で0.005 × N USDCを動的に宣言
• x402scanに登録済み
• Cloudflare Tunnel経由でLinux VPSに本番環境をデプロイ
• Coinbase CDPファシリテーター（Ed25519 JWT認証）によるmainnet決済

現在進行中のロードマップ項目：

• POST /v1/disclosures/filter（セクター＋イベント種別でのクエリ）
• SSE /v1/disclosures/stream（リアルタイムプッシュ）
• 韓国語のランディングページ
• 決済時のSlack／メール通知

計画の全容についてはdocs/ROADMAP.mdを参照してください。

コントリビューション

Issue と PR は歓迎します。特に、次のものをお待ちしています。

• Python SDK の他の言語への移植（TypeScript、Go、Rust）
• 分析エンドポイントの追加（価格反応、類似する提出書類など）
• x402 以外のエージェントフレームワークとの連携
• ランディングページの他言語への翻訳

大規模な変更を行う場合は、着手前に適合性を確認できるよう、まず方向性を説明する Issue を作成してください。

ライセンス

MIT。