koreafilings 0.1.0__tar.gz

koreafilings-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.egg-info/
+*.pyc
+.pytest_cache/
+dist/
+build/

koreafilings-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 korea-filings-api
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

koreafilings-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: koreafilings
+Version: 0.1.0
+Summary: Python SDK for koreafilings.com — AI-summarized Korean DART disclosures, paid per call in USDC via x402.
+Project-URL: Homepage, https://koreafilings.com
+Project-URL: Documentation, https://koreafilings.com
+Project-URL: Source, https://github.com/OldTemple91/korea-filings-api
+Project-URL: Issues, https://github.com/OldTemple91/korea-filings-api/issues
+Author: korea-filings-api
+License: MIT
+License-File: LICENSE
+Keywords: dart,disclosures,fintech,korea,llm,usdc,x402
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: eth-account<0.14,>=0.13
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: pydantic<3.0,>=2.6
+Description-Content-Type: text/markdown
+
+# koreafilings
+
+Python SDK for [koreafilings.com](https://koreafilings.com) — AI-summarized
+Korean DART (금융감독원 전자공시) corporate disclosures, paid per call in USDC
+on Base via the [x402](https://www.x402.org/) payment protocol.
+
+**No API keys. No monthly fee. No signup.** The wallet that signs the
+payment *is* the identity. First call for a disclosure triggers an LLM
+run; every call after costs the same flat fee from the server-side cache.
+
+## Install
+
+```bash
+pip install koreafilings
+```
+
+## Quickstart
+
+```python
+from koreafilings import Client
+
+with Client(private_key="0x...", network="base-sepolia") as client:
+    summary = client.get_summary("20260424900874")
+
+    print(f"[{summary.importance_score}/10] {summary.event_type}")
+    print(summary.summary_en)
+    print("tickers:", summary.ticker_tags)
+    print("paid:", client.last_settlement.tx_hash)
+```
+
+Example output:
+
+```
+[7/10] SINGLE_STOCK_TRADING_SUSPENSION
+Global SM's common stock was suspended from trading by the Korea Exchange
+following irregular trading patterns observed on April 23, 2026...
+tickers: ['001680.KS']
+paid: 0x1dbf9885194261e1ad64be8205897ef9c5335ad254921b337c343c23d34b0a72
+```
+
+## What you get
+
+Every response is a structured `Summary` with:
+
+| field              | type                  | description                                       |
+|--------------------|-----------------------|---------------------------------------------------|
+| `rcpt_no`          | `str`                 | DART receipt number                               |
+| `summary_en`       | `str`                 | Paraphrased English summary (never verbatim)      |
+| `importance_score` | `int` (1–10)          | 10 = M&A / insolvency, 1 = routine admin          |
+| `event_type`       | `str`                 | Canonical event taxonomy                          |
+| `sector_tags`      | `list[str]`           | GICS-style sector labels                          |
+| `ticker_tags`      | `list[str]`           | Affected KRX tickers (`.KS` / `.KQ`)              |
+| `actionable_for`   | `list[str]`           | Audience hints (`QUANT`, `M&A`, …)                |
+| `generated_at`     | `datetime`            | When the summary was produced                     |
+
+## Pricing
+
+`0.005` USDC per summary call, settled on Base. Call `client.get_pricing()`
+for the live machine-readable pricing descriptor including the current
+recipient wallet and USDC contract address.
+
+## Getting a wallet and USDC
+
+For testing on Base Sepolia (no real money):
+
+1. Create a test wallet (MetaMask → new account → export private key).
+2. Get free Base Sepolia ETH from a faucet.
+3. Get free test USDC from the [Circle faucet](https://faucet.circle.com/).
+4. Pass the 0x-prefixed private key to `Client(private_key=...)`.
+
+For production use on Base mainnet, fund a wallet with real USDC and
+pass `network="base"` instead.
+
+## How payment works
+
+Under the hood, each paid call:
+
+1. GET the endpoint without payment → server returns **402** with a
+   [x402 `accepts`](https://www.x402.org/) block describing exact
+   amount, USDC contract, network, recipient, and expiry.
+2. SDK signs an
+   [EIP-3009 `TransferWithAuthorization`](https://eips.ethereum.org/EIPS/eip-3009)
+   message locally (your private key never leaves the process).
+3. SDK base64-encodes the signed payload into `X-PAYMENT` and retries
+   the GET.
+4. Server verifies the signature via the x402 facilitator, submits it
+   on-chain, streams the JSON body back to you, and attaches the
+   settlement proof as `X-PAYMENT-RESPONSE`.
+
+The SDK exposes the proof as `client.last_settlement` so you can log
+transaction hashes for your accounting system.
+
+## Error handling
+
+```python
+from koreafilings import Client, ApiError, PaymentError, ConfigurationError
+
+try:
+    summary = client.get_summary("20260424900874")
+except PaymentError as e:
+    # Facilitator rejected the signed payment (bad sig, low balance,
+    # expired auth, network mismatch).
+    print("payment failed:", e.reason, e.detail)
+except ApiError as e:
+    # Non-payment HTTP failure: 404 unknown rcpt_no, 429 rate limit,
+    # 5xx upstream outage.
+    print("api error:", e.status_code, e.body)
+except ConfigurationError as e:
+    # Bad private_key format or unknown network alias.
+    print("config:", e)
+```
+
+## Security notes
+
+- **The private key signs real-money authorizations.** Do not ship it
+  in client-side code, do not put it in a `.env` checked into git, do
+  not paste it in chat. Prefer a dedicated burner wallet funded with
+  only the USDC you plan to spend.
+- The SDK signs locally; the key is never transmitted to koreafilings.com
+  or to the facilitator.
+- Every payment carries an `EIP-3009` nonce. The facilitator refuses
+  replays.
+- For Base Sepolia testing only, a fresh wallet with faucet funds is
+  the safest pattern — nothing on that wallet has production value.
+
+## Source & feedback
+
+- Repo: <https://github.com/OldTemple91/korea-filings-api>
+- Issues: <https://github.com/OldTemple91/korea-filings-api/issues>
+- Landing: <https://koreafilings.com>
+
+MIT-licensed.

koreafilings-0.1.0/README.md

@@ -0,0 +1,132 @@
+# koreafilings
+
+Python SDK for [koreafilings.com](https://koreafilings.com) — AI-summarized
+Korean DART (금융감독원 전자공시) corporate disclosures, paid per call in USDC
+on Base via the [x402](https://www.x402.org/) payment protocol.
+
+**No API keys. No monthly fee. No signup.** The wallet that signs the
+payment *is* the identity. First call for a disclosure triggers an LLM
+run; every call after costs the same flat fee from the server-side cache.
+
+## Install
+
+```bash
+pip install koreafilings
+```
+
+## Quickstart
+
+```python
+from koreafilings import Client
+
+with Client(private_key="0x...", network="base-sepolia") as client:
+    summary = client.get_summary("20260424900874")
+
+    print(f"[{summary.importance_score}/10] {summary.event_type}")
+    print(summary.summary_en)
+    print("tickers:", summary.ticker_tags)
+    print("paid:", client.last_settlement.tx_hash)
+```
+
+Example output:
+
+```
+[7/10] SINGLE_STOCK_TRADING_SUSPENSION
+Global SM's common stock was suspended from trading by the Korea Exchange
+following irregular trading patterns observed on April 23, 2026...
+tickers: ['001680.KS']
+paid: 0x1dbf9885194261e1ad64be8205897ef9c5335ad254921b337c343c23d34b0a72
+```
+
+## What you get
+
+Every response is a structured `Summary` with:
+
+| field              | type                  | description                                       |
+|--------------------|-----------------------|---------------------------------------------------|
+| `rcpt_no`          | `str`                 | DART receipt number                               |
+| `summary_en`       | `str`                 | Paraphrased English summary (never verbatim)      |
+| `importance_score` | `int` (1–10)          | 10 = M&A / insolvency, 1 = routine admin          |
+| `event_type`       | `str`                 | Canonical event taxonomy                          |
+| `sector_tags`      | `list[str]`           | GICS-style sector labels                          |
+| `ticker_tags`      | `list[str]`           | Affected KRX tickers (`.KS` / `.KQ`)              |
+| `actionable_for`   | `list[str]`           | Audience hints (`QUANT`, `M&A`, …)                |
+| `generated_at`     | `datetime`            | When the summary was produced                     |
+
+## Pricing
+
+`0.005` USDC per summary call, settled on Base. Call `client.get_pricing()`
+for the live machine-readable pricing descriptor including the current
+recipient wallet and USDC contract address.
+
+## Getting a wallet and USDC
+
+For testing on Base Sepolia (no real money):
+
+1. Create a test wallet (MetaMask → new account → export private key).
+2. Get free Base Sepolia ETH from a faucet.
+3. Get free test USDC from the [Circle faucet](https://faucet.circle.com/).
+4. Pass the 0x-prefixed private key to `Client(private_key=...)`.
+
+For production use on Base mainnet, fund a wallet with real USDC and
+pass `network="base"` instead.
+
+## How payment works
+
+Under the hood, each paid call:
+
+1. GET the endpoint without payment → server returns **402** with a
+   [x402 `accepts`](https://www.x402.org/) block describing exact
+   amount, USDC contract, network, recipient, and expiry.
+2. SDK signs an
+   [EIP-3009 `TransferWithAuthorization`](https://eips.ethereum.org/EIPS/eip-3009)
+   message locally (your private key never leaves the process).
+3. SDK base64-encodes the signed payload into `X-PAYMENT` and retries
+   the GET.
+4. Server verifies the signature via the x402 facilitator, submits it
+   on-chain, streams the JSON body back to you, and attaches the
+   settlement proof as `X-PAYMENT-RESPONSE`.
+
+The SDK exposes the proof as `client.last_settlement` so you can log
+transaction hashes for your accounting system.
+
+## Error handling
+
+```python
+from koreafilings import Client, ApiError, PaymentError, ConfigurationError
+
+try:
+    summary = client.get_summary("20260424900874")
+except PaymentError as e:
+    # Facilitator rejected the signed payment (bad sig, low balance,
+    # expired auth, network mismatch).
+    print("payment failed:", e.reason, e.detail)
+except ApiError as e:
+    # Non-payment HTTP failure: 404 unknown rcpt_no, 429 rate limit,
+    # 5xx upstream outage.
+    print("api error:", e.status_code, e.body)
+except ConfigurationError as e:
+    # Bad private_key format or unknown network alias.
+    print("config:", e)
+```
+
+## Security notes
+
+- **The private key signs real-money authorizations.** Do not ship it
+  in client-side code, do not put it in a `.env` checked into git, do
+  not paste it in chat. Prefer a dedicated burner wallet funded with
+  only the USDC you plan to spend.
+- The SDK signs locally; the key is never transmitted to koreafilings.com
+  or to the facilitator.
+- Every payment carries an `EIP-3009` nonce. The facilitator refuses
+  replays.
+- For Base Sepolia testing only, a fresh wallet with faucet funds is
+  the safest pattern — nothing on that wallet has production value.
+
+## Source & feedback
+
+- Repo: <https://github.com/OldTemple91/korea-filings-api>
+- Issues: <https://github.com/OldTemple91/korea-filings-api/issues>
+- Landing: <https://koreafilings.com>
+
+MIT-licensed.

koreafilings-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "koreafilings"
+version = "0.1.0"
+description = "Python SDK for koreafilings.com — AI-summarized Korean DART disclosures, paid per call in USDC via x402."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "korea-filings-api" }]
+keywords = ["dart", "korea", "disclosures", "x402", "llm", "fintech", "usdc"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27,<1.0",
+    "pydantic>=2.6,<3.0",
+    "eth-account>=0.13,<0.14",
+]
+
+[project.urls]
+Homepage = "https://koreafilings.com"
+Documentation = "https://koreafilings.com"
+Source = "https://github.com/OldTemple91/korea-filings-api"
+Issues = "https://github.com/OldTemple91/korea-filings-api/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/koreafilings"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/README.md", "/LICENSE", "/pyproject.toml"]

koreafilings-0.1.0/src/koreafilings/__init__.py

@@ -0,0 +1,29 @@
+"""koreafilings — Python SDK for AI-summarized Korean DART disclosures.
+
+Minimal usage:
+
+    from koreafilings import Client
+
+    with Client(private_key="0x...", network="base-sepolia") as client:
+        summary = client.get_summary("20260424900874")
+        print(summary.importance_score, summary.summary_en)
+        print("paid tx:", client.last_settlement.tx_hash)
+"""
+
+from .client import Client
+from .errors import ApiError, ConfigurationError, KoreaFilingsError, PaymentError
+from .models import Pricing, PricingEndpoint, SettlementProof, Summary
+
+__all__ = [
+    "Client",
+    "Summary",
+    "SettlementProof",
+    "Pricing",
+    "PricingEndpoint",
+    "KoreaFilingsError",
+    "ApiError",
+    "PaymentError",
+    "ConfigurationError",
+]
+
+__version__ = "0.1.0"

koreafilings-0.1.0/src/koreafilings/_payment.py

@@ -0,0 +1,141 @@
+"""x402 payment internals.
+
+This module is intentionally underscore-prefixed. It is not part of the
+public SDK surface — callers should reach it only via the public
+``Client`` class.
+
+What lives here:
+
+- parsing the 402 "accepts" block the API returns,
+- building the EIP-3009 TransferWithAuthorization message,
+- signing it with the caller's private key (EIP-712),
+- serialising the signed ``PaymentPayload`` as the base64 ``X-PAYMENT``
+  header the x402 protocol expects.
+
+We deliberately do not talk to the facilitator from the client. The
+server's interceptor submits the signed payment to the facilitator,
+which keeps the SDK small and avoids leaking facilitator URL choices
+into user code.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import secrets
+import time
+from typing import Any, Mapping
+
+from eth_account import Account
+from eth_account.messages import encode_typed_data
+
+from .errors import PaymentError
+
+
+X402_VERSION = 2
+
+
+def select_requirement(accepts: list[Mapping[str, Any]]) -> Mapping[str, Any]:
+    """Pick the first payment requirement the server offers.
+
+    The 402 body carries a list of acceptable payment schemes. Today the
+    server only ever offers one (USDC on whatever network it's configured
+    for), so we take index 0. If the server starts offering multiple
+    schemes, this is the place to prefer the cheaper one.
+    """
+    if not accepts:
+        raise PaymentError(reason="empty_accepts", detail="server returned 402 with no payment options")
+    return accepts[0]
+
+
+def build_authorization(payer_address: str, requirement: Mapping[str, Any]) -> dict:
+    """Assemble the EIP-3009 authorization fields.
+
+    ``validAfter`` gets a 10-second backfill so a payer clock that is
+    slightly behind the facilitator's doesn't cause a rejection.
+    ``validBefore`` uses the ``maxTimeoutSeconds`` the server advertised.
+    ``nonce`` is random 32 bytes — the facilitator rejects replays.
+    """
+    now = int(time.time())
+    return {
+        "from": payer_address,
+        "to": requirement["payTo"],
+        "value": requirement["amount"],
+        "validAfter": str(max(0, now - 10)),
+        "validBefore": str(now + int(requirement["maxTimeoutSeconds"])),
+        "nonce": "0x" + secrets.token_hex(32),
+    }
+
+
+def sign_eip3009(account: Account, requirement: Mapping[str, Any], authorization: Mapping[str, Any]) -> str:
+    """Produce the 65-byte EIP-712 signature over the authorization."""
+    chain_id = int(requirement["network"].split(":")[1])
+    extra = requirement.get("extra") or {}
+    typed = {
+        "types": {
+            "EIP712Domain": [
+                {"name": "name", "type": "string"},
+                {"name": "version", "type": "string"},
+                {"name": "chainId", "type": "uint256"},
+                {"name": "verifyingContract", "type": "address"},
+            ],
+            "TransferWithAuthorization": [
+                {"name": "from", "type": "address"},
+                {"name": "to", "type": "address"},
+                {"name": "value", "type": "uint256"},
+                {"name": "validAfter", "type": "uint256"},
+                {"name": "validBefore", "type": "uint256"},
+                {"name": "nonce", "type": "bytes32"},
+            ],
+        },
+        "primaryType": "TransferWithAuthorization",
+        "domain": {
+            "name": extra.get("name", "USDC"),
+            "version": extra.get("version", "2"),
+            "chainId": chain_id,
+            "verifyingContract": requirement["asset"],
+        },
+        "message": {
+            "from": authorization["from"],
+            "to": authorization["to"],
+            "value": int(authorization["value"]),
+            "validAfter": int(authorization["validAfter"]),
+            "validBefore": int(authorization["validBefore"]),
+            "nonce": authorization["nonce"],
+        },
+    }
+    signable = encode_typed_data(full_message=typed)
+    signed = account.sign_message(signable)
+    hex_sig = signed.signature.hex()
+    return hex_sig if hex_sig.startswith("0x") else f"0x{hex_sig}"
+
+
+def build_x_payment_header(
+    resource_url: str,
+    requirement: Mapping[str, Any],
+    authorization: Mapping[str, Any],
+    signature: str,
+) -> str:
+    """Base64-encode the signed payload into the ``X-PAYMENT`` header value."""
+    payload = {
+        "x402Version": X402_VERSION,
+        "resource": {
+            "url": resource_url,
+            "description": requirement.get("description", ""),
+            "mimeType": "application/json",
+        },
+        "accepted": requirement,
+        "payload": {"signature": signature, "authorization": authorization},
+    }
+    raw = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+    return base64.b64encode(raw).decode("ascii")
+
+
+def decode_settlement_header(value: str | None) -> dict | None:
+    """Decode the ``X-PAYMENT-RESPONSE`` settlement proof, or return None."""
+    if not value:
+        return None
+    try:
+        return json.loads(base64.b64decode(value))
+    except Exception:  # noqa: BLE001 — any decode failure returns None
+        return None

koreafilings-0.1.0/src/koreafilings/client.py

@@ -0,0 +1,183 @@
+"""Public client for koreafilings.com.
+
+The only class callers need:
+
+    from koreafilings import Client
+
+    client = Client(private_key="0x...", network="base-sepolia")
+    summary = client.get_summary("20260424900874")
+
+The client hides the full x402 flow: it issues the GET, detects the
+402 payment prompt, signs an EIP-3009 ``TransferWithAuthorization``,
+resubmits the request with the ``X-PAYMENT`` header, and parses the
+200 body. Settlement proofs from ``X-PAYMENT-RESPONSE`` are attached to
+the returned model via the ``last_settlement`` property.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+from eth_account import Account
+
+from . import _payment
+from .errors import ApiError, ConfigurationError, PaymentError
+from .models import Pricing, SettlementProof, Summary
+
+
+DEFAULT_BASE_URL = "https://api.koreafilings.com"
+DEFAULT_TIMEOUT = 60.0
+
+# Maps the short network aliases callers are allowed to pass into the
+# constructor to the CAIP-2 identifiers the server uses in its 402
+# responses. We only use this for up-front validation — the actual
+# network is always whatever the server's 402 body says, so that callers
+# never accidentally sign for a different chain than the server expects.
+_NETWORK_ALIASES = {
+    "base-sepolia": "eip155:84532",
+    "base": "eip155:8453",
+    "base-mainnet": "eip155:8453",
+}
+
+
+class Client:
+    """Blocking HTTP client for the koreafilings paid API.
+
+    Parameters
+    ----------
+    private_key:
+        A 0x-prefixed 32-byte hex string. This key signs the EIP-3009
+        authorizations that move USDC from your wallet to the API's
+        recipient wallet. **Keep this secret.** The SDK never transmits
+        it — signing happens locally, and only the signature goes on the
+        wire.
+    network:
+        Short alias (``"base-sepolia"`` or ``"base"``) used only for
+        sanity checks. The authoritative network comes from the 402
+        response the server sends; if it disagrees with ``network``,
+        ``get_summary`` raises :class:`PaymentError` before signing.
+    base_url:
+        Override for self-hosted deployments or local development.
+        Defaults to ``https://api.koreafilings.com``.
+    timeout:
+        Per-request timeout in seconds. The paid summary call can take
+        up to ~10s on a cold disclosure (LLM latency), so the default
+        is generous.
+    """
+
+    def __init__(
+        self,
+        private_key: str,
+        network: str = "base-sepolia",
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+    ):
+        if not private_key.startswith("0x") or len(private_key) != 66:
+            raise ConfigurationError("private_key must be a 0x-prefixed 32-byte hex string (66 chars)")
+        if network not in _NETWORK_ALIASES:
+            raise ConfigurationError(
+                f"unknown network '{network}'; expected one of {sorted(_NETWORK_ALIASES)}"
+            )
+        self._account = Account.from_key(private_key)
+        self._expected_chain = _NETWORK_ALIASES[network]
+        self._base_url = base_url.rstrip("/")
+        self._http = httpx.Client(timeout=timeout)
+        self._last_settlement: Optional[SettlementProof] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def address(self) -> str:
+        """Payer wallet address derived from the configured private key."""
+        return self._account.address
+
+    @property
+    def last_settlement(self) -> Optional[SettlementProof]:
+        """Settlement proof from the most recent successful paid call, if any."""
+        return self._last_settlement
+
+    def get_pricing(self) -> Pricing:
+        """Fetch the public pricing descriptor. No payment required."""
+        resp = self._http.get(f"{self._base_url}/v1/pricing")
+        if resp.status_code != 200:
+            raise ApiError(resp.status_code, _safe_json(resp))
+        return Pricing.model_validate(resp.json())
+
+    def get_summary(self, rcpt_no: str) -> Summary:
+        """Fetch the AI summary for a DART receipt number, paying if required.
+
+        The first call for a given ``rcpt_no`` triggers an LLM run on
+        the server and costs USDC (0.005 as of v0.1). Every subsequent
+        call for the same disclosure is served from the server-side
+        cache and still costs the same fee — the cache improves server
+        margins, not caller price. Errors map to:
+
+        - :class:`ApiError` for HTTP failures that aren't payment prompts,
+        - :class:`PaymentError` if signing/settlement is rejected.
+        """
+        url = f"{self._base_url}/v1/disclosures/{rcpt_no}/summary"
+
+        unpaid = self._http.get(url)
+        if unpaid.status_code == 200:
+            # Free/cached response path (the server currently always charges,
+            # but a future free-tier could land here without breaking callers).
+            self._last_settlement = None
+            return Summary.model_validate(unpaid.json())
+        if unpaid.status_code != 402:
+            raise ApiError(unpaid.status_code, _safe_json(unpaid))
+
+        body = _safe_json(unpaid) or {}
+        requirement = _payment.select_requirement(body.get("accepts") or [])
+
+        advertised = requirement.get("network")
+        if advertised != self._expected_chain:
+            raise PaymentError(
+                reason="network_mismatch",
+                detail=f"server advertises {advertised}, client configured for {self._expected_chain}",
+            )
+
+        authorization = _payment.build_authorization(self._account.address, requirement)
+        signature = _payment.sign_eip3009(self._account, requirement, authorization)
+        header_value = _payment.build_x_payment_header(url, requirement, authorization, signature)
+
+        paid = self._http.get(url, headers={"X-PAYMENT": header_value})
+        if paid.status_code == 402:
+            # Facilitator rejected after we signed — bubble up its reason.
+            rejection = _safe_json(paid) or {}
+            raise PaymentError(
+                reason=rejection.get("error") or "payment_rejected",
+                detail=rejection,
+            )
+        if paid.status_code != 200:
+            raise ApiError(paid.status_code, _safe_json(paid))
+
+        settlement_raw = _payment.decode_settlement_header(paid.headers.get("X-PAYMENT-RESPONSE"))
+        self._last_settlement = (
+            SettlementProof.model_validate(settlement_raw) if settlement_raw else None
+        )
+        return Summary.model_validate(paid.json())
+
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._http.close()
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()
+
+
+def _safe_json(resp: httpx.Response) -> Optional[dict]:
+    """Best-effort JSON parse; returns None on any failure."""
+    try:
+        return resp.json()
+    except Exception:  # noqa: BLE001
+        return None

koreafilings-0.1.0/src/koreafilings/errors.py

@@ -0,0 +1,55 @@
+"""Exception hierarchy for the koreafilings SDK.
+
+Callers catch ``KoreaFilingsError`` to handle any SDK-level failure, or
+a more specific subclass when they care to distinguish payment issues
+from transport issues.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+class KoreaFilingsError(Exception):
+    """Base class for every error this SDK raises."""
+
+
+class ApiError(KoreaFilingsError):
+    """The API returned a non-2xx response that is not a 402 payment prompt.
+
+    Typical causes: 404 (unknown rcpt_no), 429 (rate limit), 5xx (upstream
+    DART or LLM transient failure). ``status_code`` is the HTTP status;
+    ``body`` is the raw JSON body if the server supplied one, else ``None``.
+    """
+
+    def __init__(self, status_code: int, body: Any | None, message: str | None = None):
+        self.status_code = status_code
+        self.body = body
+        suffix = f": {message}" if message else ""
+        super().__init__(f"API returned {status_code}{suffix}")
+
+
+class PaymentError(KoreaFilingsError):
+    """The facilitator or the API rejected the x402 payment attempt.
+
+    Raised when a signed payment is rejected by the facilitator (bad
+    signature, insufficient balance, expired authorization) or when the
+    API replies 402 a second time after we submitted a payment header.
+    ``reason`` is the short code returned by the facilitator when one
+    is available.
+    """
+
+    def __init__(self, reason: str | None, detail: Mapping[str, Any] | str | None = None):
+        self.reason = reason
+        self.detail = detail
+        parts = [p for p in (reason, str(detail) if detail else None) if p]
+        super().__init__(" — ".join(parts) if parts else "payment rejected")
+
+
+class ConfigurationError(KoreaFilingsError):
+    """The SDK was constructed with invalid arguments.
+
+    Raised eagerly at construction time so bad configs never reach the
+    first HTTP call. Examples: malformed private key, unknown network
+    alias.
+    """

koreafilings-0.1.0/src/koreafilings/models.py

@@ -0,0 +1,78 @@
+"""Response models.
+
+Every model uses Pydantic v2 so callers get runtime validation, static
+type-checker hints, and ``.model_dump_json()`` for free. Field names
+stay in the API's camelCase form because that's what the wire returns —
+we do not re-camelcase on the way in.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Summary(BaseModel):
+    """AI-generated English summary of a single DART disclosure.
+
+    This is the payload the paid endpoint returns after a successful
+    x402 settlement. ``importance_score`` is 1–10, where 10 is an event
+    like M&A or insolvency and 1 is a routine administrative filing.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, frozen=True)
+
+    rcpt_no: str = Field(alias="rcptNo")
+    summary_en: str = Field(alias="summaryEn")
+    importance_score: int = Field(alias="importanceScore", ge=1, le=10)
+    event_type: str = Field(alias="eventType")
+    sector_tags: List[str] = Field(alias="sectorTags", default_factory=list)
+    ticker_tags: List[str] = Field(alias="tickerTags", default_factory=list)
+    actionable_for: List[str] = Field(alias="actionableFor", default_factory=list)
+    generated_at: datetime = Field(alias="generatedAt")
+
+
+class SettlementProof(BaseModel):
+    """On-chain settlement proof the API returns via ``X-PAYMENT-RESPONSE``.
+
+    ``tx_hash`` is the Base transaction hash you can look up on
+    basescan.org. ``network`` is the CAIP-2 network identifier (e.g.
+    ``eip155:84532`` for Base Sepolia, ``eip155:8453`` for Base mainnet).
+    ``error_reason`` is populated only when ``success`` is ``False`` —
+    the facilitator normally only reaches this path on partial
+    settlements, since hard rejects surface as ``PaymentError`` before
+    a proof is emitted.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, frozen=True)
+
+    success: bool
+    tx_hash: Optional[str] = Field(alias="transaction", default=None)
+    network: Optional[str] = None
+    payer: Optional[str] = None
+    error_reason: Optional[str] = Field(alias="errorReason", default=None)
+
+
+class Pricing(BaseModel):
+    """Machine-readable pricing descriptor from ``GET /v1/pricing``."""
+
+    model_config = ConfigDict(populate_by_name=True, frozen=True)
+
+    x402_network: str = Field(alias="x402Network")
+    x402_asset: str = Field(alias="x402Asset")
+    x402_recipient: str = Field(alias="x402Recipient")
+    endpoints: List["PricingEndpoint"]
+
+
+class PricingEndpoint(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, frozen=True)
+
+    method: str
+    path: str
+    price_usdc: str = Field(alias="priceUsdc")
+    description: str
+
+
+Pricing.model_rebuild()