Koreafilings Mcp

Korea Filings

一个 HTTP API，可将韩国企业公告（DART · 전자공시）转换为机器可用的英文内容。公告信息流免费——浏览市场或关注单个股票代码，即可获取英文公司名称、英文公告类型、重要性评分和 DART 原文链接，无需钱包、API 密钥或注册。付费调用用于获取解读：通过 x402 在 Base 上支付 0.005 USDC，即可获得对特定公告内容的 AI 摘要。专为需要多样化数据源、偏好按次付费而非订阅的自主 AI Agent 和独立 Agent 开发者打造。

韩国金融数据是我们目前提供的服务内容，但推动用户采用的价值主张是按次付费而非月度合同，以及使用标准 x402 而非定制身份验证——同样的模式也适用于其他公共记录 API。无需 API 密钥，无需注册，也无需采购流程。

在线服务：https://koreafilings.com · API：https://api.koreafilings.com · 交互式文档：/swagger-ui。

功能介绍

DART 原始数据免费，但内容为韩文，结构面向人工公告处理人员，而非大模型。Korea Filings 会将每份公告转换为结构化、经过缓存并附有英文摘要的 JSON 负载——Agent 可免费按名称查询韩国公司，然后通过一次付费 x402 调用，批量获取该股票代码对应的摘要。摘要根据公告正文生成（而非仅依据标题），因此量化事件会提取韩文原文中的实际金额、稀释比例、交易对手名称和生效日期。以下为两个示例——一个简单的公司治理事件和一个量化融资事件：

{
  "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"
}

一个量化事件——三星电子分红决议，内容原样返回自一次 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"
}

缓存是我们的护城河——首个请求某份公告的 Agent 支付大模型成本；此后，其他 Agent 查询相同 rcpt_no 时，只需进行几乎零成本的数据库查找，仍按每份摘要固定支付 0.005 USDC。按股票代码批量调用会逐条命中相同的缓存行，因此，包含五份摘要的调用只需一次转入 USDC 的付款，却会进行五次缓存查询。随着采用率提升，利润率也会持续增长。

使用方法

选择最适合你技术栈的接口。三种接口在底层都使用相同的 x402 流程；对 PAYMENT-SIGNATURE 标头进行签名的钱包就是调用者身份。无需 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"
      }
    }
  }
}

可使用五种工具——三种免费工具用于发现，两种付费工具：

• find_company(query) — 免费；按韩文名称、英文名称或股票代码，对 3,961 家在 KRX 上市的公司进行三元模糊搜索。
• list_recent_filings(limit) — 免费；全市场最新 DART 动态（仅元数据——由 Agent 决定为哪些内容付费）。
• get_pricing() — 免费；实时钱包、网络、USDC 合约及各端点价格。
• get_recent_filings(ticker, limit) — 付费，每条 0.005 × limit USDC；获取某一股票代码的批量 AI 摘要，并返回链上结算交易哈希。
• get_disclosure_summary(rcpt_no) — 付费 0.005 USDC；根据已知的收件编号获取单条 AI 摘要。

自然的 Agent 工作流是 find_company → get_recent_filings：先免费调用一次，将名称解析为股票代码；再付费调用一次，获取该股票代码的摘要。

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.

面向已有 14 位收件编号的调用方，固定收费 0.005 USDC 的 /v1/disclosures/summary?rcptNo=… 端点仍然可用——采用相同的 x402 流程，只需设置 amount = 5000，并使用单条摘要请求体。

定价

每次调用均以 USDC 在 Base 上计价。免费端点（/v1/companies、/v1/companies/{ticker}、/v1/disclosures/recent）不会发起付款质询，因此 Agent 可以先浏览，再决定是否付费。动态也支持条件 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

按条计价的规则会在 402 质询中动态声明：对于 limit=N，服务会将 0.005 × N USDC 签入 accepts[0].amount，让调用方在授权钱包前看到确切费用。单条摘要端点仍采用 0.005 USDC 的固定价格，适合已从其他来源获得 14 位收件编号的调用方。

完整的机器可读定价说明（当前钱包、网络、USDC 合约及所有付费端点）位于 /v1/pricing；Agent 可通过 /.well-known/x402 发现服务。 同一付费操作接口也提供 Agent Web Protocol （AWP）格式，位于 /.well-known/agent.json； 面向 AI Agent 的通俗概览位于 /llms.txt。

通过 Coinbase CDP facilitator 在 Base 主网上实时运行。每次付费调用都会通过单跳在链上结算一笔真实的 transferWithAuthorization；商户钱包、网络和 USDC 合约地址均可通过 /v1/pricing 和 /.well-known/x402 自行查询，因此 Agent 可以在签名前验证收款地址。

架构

三个逻辑子系统共用一个 Spring Boot 应用：

1. 数据采集 — 每隔 30 秒轮询一次 DART Open API，按 rcpt_no 去重，将原始元数据持久化到 Postgres， 并将摘要任务加入队列。
2. 摘要生成 — 消费摘要任务，判断复杂度，将任务路由至 Gemini 2.5 Flash-Lite（搭配 Resilience4j 限流、熔断和重试），并将英文摘要、股票代码 / 行业标签和审计记录持久化到 llm_audit。
3. 付费 API — Spring MVC 控制器由 X402PaywallInterceptor 保护。 每次请求都会读取 PAYMENT-SIGNATURE（或兼容 0.2.x 客户端的旧版 X-PAYMENT 别名），通过 facilitator 验证签名，检查 Redis 中是否存在重放请求，在 200 响应时结算，并通过 ResponseBodyAdvice 附加包含链上交易哈希的 PAYMENT-RESPONSE。如果 /settle 抛出异常或拒绝结算，响应正文会被改写为 x402 v2 结算失败格式（HTTP 402，PAYMENT-RESPONSE 中包含经 base64 编码的失败 SettlementResponse，且正文为空），以防 facilitator 故障导致付费数据未付款就泄露。如果处理器方法未标注 @X402Paywall，拦截器会直接放行，因此 /v1/pricing、/.well-known/x402 和 OpenAPI 文档无需身份验证。

402 挑战遵循 x402 v2 传输规范： PAYMENT-REQUIRED 标头携带经 base64 编码的 PaymentRequired 负载（其中 bazaar 扩展声明输入 / 输出架构，以便 AI Agent 发现），而正文保留一份兼容 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 主网 USDC），然后运行 python testclient/payer.py。若要在本地开发时使用公开的 测试网 facilitator，请将 X402_FACILITATOR_URL 指向 https://www.x402.org/facilitator，并在 .env 中使用 Base Sepolia 参数。

状态

已在 Base 主网上线，链上结算已验证。 MVP 功能集：

• DART 实时数据采集（每隔 30 秒轮询）
• Gemini 2.5 Flash-Lite 摘要生成，包含重要性评分和行业 / 股票代码标注
• 支持 bazaar 扩展的 x402 v2 付费墙，可供 Agent 发现和调用
• 通过 /.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），让 Agent 可在付款前浏览
• 按结果计费的付费批量接口（/v1/disclosures/by-ticker?ticker=…&limit=N），402 中动态声明价格为 0.005 × N USDC
• 已被 x402scan 收录
• 通过 Cloudflare Tunnel 部署到 Linux VPS 生产环境
• Coinbase CDP facilitator（Ed25519 JWT 身份验证）用于主网结算

正在推进的路线图事项：

• POST /v1/disclosures/filter（行业 + 事件类型查询）
• SSE /v1/disclosures/stream（实时推送）
• 韩语落地页
• 结算 Slack / 邮件提醒

完整计划请参阅 docs/ROADMAP.md。

贡献

欢迎提交 Issue 和 PR，尤其是以下方面：

• 将 Python SDK 移植到其他语言（TypeScript、Go、Rust）
• 添加更多分析端点（价格反应、可比申报文件，……）
• 与非 x402 Agent 框架集成
• 将落地页翻译成其他语言

对于重大更改，请先提交 Issue，说明计划方向，以便我们在你开始开发前确认是否合适。

许可证

MIT。