# Korea Filings

> Free English feed of Korean DART corporate disclosures — every filing typed, importance-scored, and linked back to the DART original, no wallet and no signup. Paid AI summaries (0.005 USDC via x402 on Base mainnet) when you need a filing explained rather than listed.

Two tiers, and the free one is usable on its own: browse or watch a company for free, pay only for the paraphrased English summary of a specific filing.

## Quickstart (60 seconds, no wallet needed)

```
# (free) What did Korean listed companies just file?
curl 'https://api.koreafilings.com/v1/disclosures/recent?limit=5'
#   -> corpNameEn, reportNmEn (English filing type), eventType,
#      importanceScore 1-10, numericExpectation HIGH/LOW, sourceUrl

# (free) Watch one company — no payment for the filing list
curl 'https://api.koreafilings.com/v1/disclosures/recent?ticker=005930&limit=5'

# (free) Resolve a Korean company name → ticker
curl 'https://api.koreafilings.com/v1/companies?q=Samsung+Electronics'

# (free) See the exact shape of a paid summary response without paying
# — sourced from a real Base mainnet paid call, identical schema to what
# GET /v1/disclosures/summary?rcptNo=... returns for any real rcptNo.
curl 'https://api.koreafilings.com/v1/disclosures/sample'

# (free) Inspect the 402 challenge for a paid endpoint without paying
curl -i 'https://api.koreafilings.com/v1/disclosures/by-ticker?ticker=005930&limit=3'
#   -> HTTP/2 402 + base64-encoded PaymentRequired payload in the
#      PAYMENT-REQUIRED header. The body has the same payload as JSON
#      so v1 SDK clients can parse it without inspecting headers.
```

## Discovery

- [/.well-known/x402](https://api.koreafilings.com/.well-known/x402): canonical x402 service descriptor — network, asset, recipient wallet, paid endpoint catalog with prices and methods.
- [/.well-known/agent.json](https://api.koreafilings.com/.well-known/agent.json): Agent Web Protocol manifest — same surface in AWP shape for indexers that prefer it.
- [/v1/pricing](https://api.koreafilings.com/v1/pricing): machine-readable pricing + workflow steps + example calls.
- [/openapi.json](https://api.koreafilings.com/openapi.json): full OpenAPI 3 schema.

## Free endpoints

- `GET /v1/companies?q={koreanOrEnglishName}` — trigram fuzzy search across 3,961 KRX-listed companies. Returns ticker, corp_code, market.
- `GET /v1/companies/{ticker}` — direct six-digit ticker lookup.
- `GET /v1/disclosures/recent?limit={n}&since_hours={h}&ticker={ticker}` — the English filing feed. Omit `ticker` for the market-wide view, pass it to watch one company; both are free. Every row carries `corpNameEn` (KRX-registered English company name), `reportNmEn` (English filing-type label), `eventType`, `importanceScore` (1–10), `numericExpectation` (HIGH/LOW — whether this filing class normally contains hard numbers), and `sourceUrl` (the DART original), alongside the Korean `corpName` / `reportNm`. `sectorTags` appears only after a filing's summary has been LLM-generated (the first paid call, globally) — absent means "not classified yet", not "no sector".
- `GET /v1/disclosures/sample` — constant sample of the paid response shape (real body-aware Base mainnet response), for SDK / schema verification without paying.

## Paid endpoints (x402, USDC on Base)

What you pay for is the *explanation* — a paraphrased English summary of what the filing actually says, generated from the filing body itself. Listing filings, watching a company, and ranking them by importance are all free above.

- `GET /v1/disclosures/by-ticker?ticker={ticker}&limit={n}` — 0.005 USDC × n. Returns AI-summarised English filings, newest first. Default limit 5, max 50.
- `GET /v1/disclosures/summary?rcptNo={14-digit}` — 0.005 USDC fixed. Re-fetch a single summary by 14-digit DART receipt number.

## Common agent mistakes

- These endpoints are READ operations. Use **GET**, never POST.
- `rcpt_no` is **not LLM-knowable** — get it from the response of `/v1/disclosures/by-ticker` or the free `/v1/disclosures/recent` feed before calling `/v1/disclosures/summary`.
- Pay via the `PAYMENT-SIGNATURE` header (x402 v2 transport spec). The legacy `X-PAYMENT` header is also accepted for older 0.2.x SDK / MCP releases.
- The TypeScript SDK, Python SDK, and MCP server handle the full 402 → sign → retry flow automatically. Recommended over hand-rolled HTTP.

## Format constraints (validated server-side, mirror these client-side)

- `rcptNo` must match `^\d{14}$` — exactly 14 digits, no separators.
- `ticker` must match `^[0-9A-Z]{6,7}$` — 6 alphanumeric for standard KRX listings, 7 for SPAC tickers ending in `K`.
- `limit` query parameter is clamped to the documented range server-side (1–50 for `by-ticker`, 1–100 for `recent`).
- A malformed `rcptNo` or `ticker` produces HTTP 400 with `{ "error": "validation_failed" }` — no payment is ever charged for a rejected input.

## SDKs and clients

- TypeScript / JavaScript SDK: `npm install koreafilings` — <https://www.npmjs.com/package/koreafilings>
  - Same surface as the Python SDK in idiomatic camelCase.
  - Runs in Node 18+, browsers, Cloudflare Workers, and Deno.
  - Pinned exact `viem 2.21.0` for stable EIP-712 typed-data hashing.
- Python SDK: `pip install koreafilings` — <https://pypi.org/project/koreafilings/>
- MCP server (Claude Desktop / Cursor / Continue): `uv tool install koreafilings-mcp` — <https://pypi.org/project/koreafilings-mcp/>
- Source repository: <https://github.com/OldTemple91/korea-filings-api>
- Reference test client: `testclient/payer.py` in the repo (full 402 → sign → retry flow in ~150 lines of Python).

## What this service is not

- Not a real-time feed; refresh follows the DART portal's cadence (~30 second polling).
- Not a verbatim translation. Summaries are paraphrased English to reduce copyright risk and improve agent consumption. Company names and filing-type labels are English; `corpName` / `reportNm` retain the Korean originals as filed with DART.
- Not a substitute for the original disclosure; every summary links back to the DART original URL.
- Not a Korean retail investor product — there is no UI, no Korean-language frontend, no signup, no API key. Payment IS the authentication.