{"openapi":"3.0.1","info":{"title":"koreafilings API","description":"Commercial API that serves AI-generated English summaries of\nKorean DART (금융감독원 전자공시) corporate disclosures.\n\nEvery paid endpoint settles on-chain in USDC via the\n[x402](https://www.x402.org/) payment protocol. The first\ncall for a disclosure triggers an LLM run; every subsequent\ncall for the same receipt number is served from a shared\ncache for the same price, so the marginal cost to the\noperator approaches zero as adoption grows.\n\n**No API keys. No signup. No monthly fees.** The wallet\nthat signs the `PAYMENT-SIGNATURE` header *is* the identity.\n","contact":{"name":"korea-filings-api","url":"https://github.com/OldTemple91/korea-filings-api","email":"***"},"license":{"name":"MIT","url":"https://github.com/OldTemple91/korea-filings-api/blob/main/LICENSE"},"version":"0.0.1"},"servers":[{"url":"https://api.koreafilings.com","description":"Production"},{"url":"http://localhost:8080","description":"Local development"}],"security":[{"x402Payment":[]}],"tags":[{"name":"Disclosures","description":"DART disclosure intelligence — free metadata browsing and paid AI summaries."},{"name":"Public","description":"Free, unpaid endpoints for service discovery and pricing."},{"name":"Discovery","description":"Well-known discovery documents for x402 indexers."},{"name":"Companies","description":"Free directory of Korean listed companies — search by name or ticker."}],"paths":{"/v1/pricing":{"get":{"tags":["Public"],"summary":"Current pricing and x402 wallet configuration","description":"Machine-readable descriptor of every paid endpoint and\nits USDC price. Also carries the x402 recipient wallet,\nCAIP-2 network id, USDC contract address, the canonical\npayment header convention (PAYMENT-SIGNATURE in, the\nPAYMENT-RESPONSE alongside its legacy alias on the way\nout), and the free→paid workflow steps so a cold-start\nagent can compose calls without reading prose docs.\n\nSafe to call as often as desired — no payment, no rate\nlimiting beyond the standard anti-abuse layer.\n","operationId":"pricing","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/PricingResponse"}}}}},"security":[]}},"/v1/disclosures/summary":{"get":{"tags":["Disclosures"],"summary":"Get an AI-generated English summary of a DART disclosure","description":"Costs **0.005 USDC** on Base, settled via x402. Returns a\nparaphrased English summary, a 1–10 importance score,\nthe canonical event type, and ticker / sector / audience\ntags. The summary is generated once per receipt number\nand served from cache thereafter — the price does not\nchange between cold and warm calls, but the LLM cost is\nonly paid by the first caller globally.\n\nReceipt numbers (`rcptNo`) come from the free\n`/v1/disclosures/recent` feed or `/v1/disclosures/by-ticker`\nresponse. They are not LLM-knowable — agents must always\nlook one up before calling this endpoint.\n","operationId":"getSummary","parameters":[{"name":"rcptNo","in":"query","description":"14-digit DART receipt number, e.g. `20260424900874`. Obtain from `/v1/disclosures/recent` or `/v1/disclosures/by-ticker`.","required":true,"schema":{"pattern":"^[0-9]{14}$","type":"string"},"example":20260424900874}],"responses":{"200":{"description":"Payment accepted; summary returned.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/DisclosureSummaryDto"}}}},"402":{"description":"Payment required — body carries the x402 `accepts` block with wallet, network, amount, and expiry.","content":{"application/json":{}}},"404":{"description":"Unknown receipt number — the DART filing has not been ingested yet."}},"x-payment-info":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x8467Be164C75824246CFd0fCa8E7F7009fB8f720","amount":"5000","amountMode":"fixed","tokenName":"USD Coin","tokenVersion":"2"}}},"/v1/disclosures/recent":{"get":{"tags":["Disclosures"],"summary":"List recent DART filings (metadata only, free)","description":"Returns the most-recent DART filings across every listed\nKorean company in metadata-only form (no AI summary). Useful\nas a discovery feed before deciding which filings warrant a\npaid summary call.\n","operationId":"getRecent","parameters":[{"name":"limit","in":"query","description":"Max filings to return (1-100, default 20).","required":false,"schema":{"maximum":100,"minimum":1,"type":"integer","format":"int32","default":20}},{"name":"since_hours","in":"query","description":"Look back this many hours (1-168, default 24).","required":false,"schema":{"maximum":168,"minimum":1,"type":"integer","format":"int32","default":24}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/RecentFilingsResponse"}}}}},"security":[]}},"/v1/disclosures/by-ticker":{"get":{"tags":["Disclosures"],"summary":"Get AI summaries for the most recent filings of a Korean ticker","description":"Costs **0.005 USDC × limit** on Base, settled via x402.\nDefault limit is 5 → 0.025 USDC. Limit is capped at 50.\nReturns up to {@code limit} summaries, newest first; if\nthe company has fewer recent filings than requested the\nresponse is shorter and the agent has overpaid for the\nmissing slots — pre-filter with {@code /v1/disclosures/recent}\nif budget is tight.\n\nWorkflow: call free `/v1/companies?q=<name>` to resolve a\nKorean company name to its six-digit KRX ticker, then pass\nthat ticker here.\n","operationId":"getByTicker","parameters":[{"name":"ticker","in":"query","description":"Six-digit KRX ticker, e.g. `005930` for Samsung Electronics. Use the free `/v1/companies?q=<name>` endpoint first to resolve a company name.","required":true,"schema":{"pattern":"^[0-9A-Z]{6,7}$","type":"string"},"example":"005930"},{"name":"limit","in":"query","description":"Max filings to return (1-50, default 5). Each costs 0.005 USDC.","required":false,"schema":{"maximum":50,"minimum":1,"type":"integer","format":"int32","default":5}}],"responses":{"200":{"description":"Payment accepted; up to `limit` summaries returned, newest first.","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ByTickerResponse"}}}},"402":{"description":"Payment required — body carries the x402 `accepts` block with the limit-scaled amount.","content":{"application/json":{}}}},"x-payment-info":{"scheme":"exact","network":"eip155:8453","asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","payTo":"0x8467Be164C75824246CFd0fCa8E7F7009fB8f720","amount":"5000","amountMode":"perResult","countParam":"limit","defaultCount":5,"maxCount":50,"tokenName":"USD Coin","tokenVersion":"2"}}},"/v1/companies":{"get":{"tags":["Companies"],"summary":"Search Korean listed companies by name or ticker","description":"Searches the KRX listed-company directory by Korean name,\nEnglish name, or six-digit ticker. Trigram fuzzy match —\nthe closest hits come first. Use this as the first step\nbefore calling the paid {@code by-ticker} endpoint when\nyou only have a company name.\n","operationId":"search","parameters":[{"name":"q","in":"query","description":"Free-text query: company name (Korean or English) or six-digit ticker.","required":true,"schema":{"maxLength":200,"minLength":0,"type":"string"},"example":"Samsung Electronics"},{"name":"limit","in":"query","description":"Max matches to return (1-50, default 20).","required":false,"schema":{"maximum":50,"minimum":1,"type":"integer","format":"int32","default":20}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompanyDto"}}}}},"security":[]}},"/v1/companies/{ticker}":{"get":{"tags":["Companies"],"summary":"Get a Korean listed company by ticker","description":"Looks up a company by its six-digit KRX ticker. Returns\n{@code 404} for tickers we have no record of (delisted,\nnot yet synced, or simply invalid). Useful as a\nconfirmation step after a fuzzy search.\n","operationId":"getByTicker_1","parameters":[{"name":"ticker","in":"path","description":"Six-digit KRX ticker, e.g. \"005930\" for Samsung Electronics.","required":true,"schema":{"pattern":"^[0-9A-Z]{6,7}$","type":"string"},"example":"005930"}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/CompanyDto"}}}}},"security":[]}},"/.well-known/x402":{"get":{"tags":["Discovery"],"summary":"x402 service discovery document","description":"Lists every paid endpoint this service exposes, plus the\nmerchant wallet and the USDC asset address. Used by\nx402 ecosystem indexers (x402scan, etc.) to register\nthe service without probing each endpoint.\n","operationId":"discoveryDocument","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}}},"security":[]}},"/.well-known/agent.json":{"get":{"tags":["Discovery"],"summary":"Agent Web Protocol (AWP) manifest","description":"AWP-shaped sibling to {@code /.well-known/x402}. Lists\nevery public action (free + paid) with method, endpoint,\nparameters, and a per-action pointer to the x402\npayment descriptor for paid actions. Targeted at the\nOpen402 directory crawler and other AWP-aware indexers\nthat probe this path.\n","operationId":"agentJsonDocument","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"object"}}}}}},"security":[]}}},"components":{"schemas":{"PaidEndpoint":{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"},"priceUsdc":{"type":"string"},"pricingMode":{"type":"string"},"description":{"type":"string"},"requiredParams":{"type":"array","items":{"$ref":"#/components/schemas/RequiredParam"}},"exampleCall":{"type":"string"}}},"PaymentHeaders":{"type":"object","properties":{"preferred":{"type":"string"},"accepted":{"type":"array","items":{"type":"string"}},"challenge":{"type":"string"},"settlement":{"type":"string"},"settlementAliases":{"type":"array","items":{"type":"string"}},"spec":{"type":"string"}}},"PricingResponse":{"type":"object","properties":{"x402Network":{"type":"string"},"x402Asset":{"type":"string"},"x402Recipient":{"type":"string"},"paymentHeaders":{"$ref":"#/components/schemas/PaymentHeaders"},"workflow":{"$ref":"#/components/schemas/Workflow"},"endpoints":{"type":"array","items":{"$ref":"#/components/schemas/PaidEndpoint"}}}},"RequiredParam":{"type":"object","properties":{"name":{"type":"string"},"in":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"},"description":{"type":"string"},"example":{"type":"string"}}},"Workflow":{"type":"object","properties":{"steps":{"type":"array","items":{"type":"string"}},"freeEndpoints":{"type":"object","additionalProperties":{"type":"string"}}}},"DisclosureSummaryDto":{"type":"object","properties":{"rcptNo":{"type":"string"},"summaryEn":{"type":"string"},"importanceScore":{"type":"integer","format":"int32"},"eventType":{"type":"string"},"sectorTags":{"type":"array","items":{"type":"string"}},"tickerTags":{"type":"array","items":{"type":"string"}},"actionableFor":{"type":"array","items":{"type":"string"}},"generatedAt":{"type":"string","format":"date-time"}},"description":"AI summaries, newest first. Length equals `delivered`."},"RecentFilingDto":{"type":"object","properties":{"rcptNo":{"type":"string"},"ticker":{"type":"string"},"corpName":{"type":"string"},"reportNm":{"type":"string"},"rceptDt":{"type":"string","format":"date"}},"description":"Recent DART filings, newest first."},"RecentFilingsResponse":{"type":"object","properties":{"filings":{"type":"array","description":"Recent DART filings, newest first.","items":{"$ref":"#/components/schemas/RecentFilingDto"}}}},"ByTickerResponse":{"type":"object","properties":{"ticker":{"type":"string","description":"Echoed back from the request.","example":"005930"},"count":{"type":"integer","description":"Alias of `delivered`, kept for v0.2.x SDK shape compatibility. Use `delivered` and `chargedFor` for the unambiguous accounting.","format":"int32"},"chargedFor":{"type":"integer","description":"The `limit` query parameter the agent paid for. Equal to the multiplier the 402 challenge's `accepts[0].amount` was scaled by.","format":"int32"},"delivered":{"type":"integer","description":"How many summaries were actually returned. May be less than `chargedFor` when the ticker has fewer recent filings than `limit`, or when one of those filings does not yet have a cached summary.","format":"int32"},"summaries":{"type":"array","description":"AI summaries, newest first. Length equals `delivered`.","items":{"$ref":"#/components/schemas/DisclosureSummaryDto"}}}},"CompanyDto":{"type":"object","properties":{"ticker":{"type":"string"},"corpCode":{"type":"string"},"nameKr":{"type":"string"},"nameEn":{"type":"string"},"market":{"type":"string"},"isExactMatch":{"type":"boolean"}}}},"securitySchemes":{"x402Payment":{"type":"apiKey","description":"Base64-encoded signed x402 payment payload (v2 transport\nspec). When this header is absent the server replies\nwith HTTP 402: the `PAYMENT-REQUIRED` response header\ncarries the base64-encoded `PaymentRequired` payload,\nand a JSON-encoded copy of the same payload is in the\nbody for v1-era clients. Sign an EIP-3009\nTransferWithAuthorization for the declared amount and\nre-send the same request with this header set.\n\nOn a successful 2xx response, the server attaches a\n`PAYMENT-RESPONSE` header carrying the base64-encoded\nsettlement proof (transaction hash, network, payer).\n\nSee https://github.com/coinbase/x402/blob/main/specs/transports-v2/http.md\nfor the canonical spec and\nhttps://github.com/OldTemple91/korea-filings-api for\nthe reference Python SDK.\n","name":"PAYMENT-SIGNATURE","in":"header"},"x402PaymentLegacy":{"type":"apiKey","description":"Legacy v1 transport header. Accepted for backward\ncompatibility with `koreafilings` 0.2.x SDK and\n`koreafilings-mcp` 0.2.x clients that send the v1\nheader name. New integrations should use\n`PAYMENT-SIGNATURE` instead. Either header is\nacceptable; do not send both.\n","name":"X-PAYMENT","in":"header"}}}}