# Korea Filings

> Pay-per-call API for AI-summarised Korean DART corporate disclosures. Free company directory + recent feed for discovery; paid summaries for content via x402 (USDC on Base mainnet).

The intended agent flow is two calls: a free name → ticker resolution, then a paid `get_recent_filings(ticker, limit)`. Direct receipt-number lookup is also supported for callers that already have a 14-digit DART rcpt_no.

## Quickstart (60 seconds, no wallet for the free path)

```
# (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}` — market-wide metadata feed of the most recent DART filings.
- `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)

- `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.
- 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.