Metadata-Version: 2.4
Name: ko-edgar
Version: 0.1.0
Summary: Official Python SDK for ko.io — source-traced SEC & market data for AI agents and quants
Project-URL: Homepage, https://ko.io
Project-URL: Documentation, https://ko.io/docs
Project-URL: Repository, https://github.com/SharpLu/ko-mcp
Project-URL: Issues, https://github.com/SharpLu/ko-mcp/issues
Author-email: "ko.io" <admin@ko.io>
License-Expression: MIT
Keywords: 13f,ai-agents,congress-trading,edgar,financial-data,hedge-funds,insider-trading,mcp,sec
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
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 :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx<1,>=0.24
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# ko-edgar

Official Python SDK for [ko.io](https://ko.io) — source-traced SEC & market
data for AI agents and quants. 13F institutional holdings (85M+ rows,
2013→today), insider trades, Congress trading, crypto ETF exposure, macro
indicators, and a white-labeled EDGAR filings gateway.

```bash
pip install ko-edgar
```

## Quickstart

Works out of the box in keyless demo mode — no signup required:

```python
from ko_edgar import KoClient

ko = KoClient()  # demo mode; or KoClient(api_key="ko_live_...")

# Who is Berkshire Hathaway holding right now?
for holding in ko.institutions.holdings("1067983", per_page=10):
    print(holding["ticker"], holding["holding_value"])

# Which institutions hold NVDA?
for holder in ko.stocks.holders("NVDA"):
    print(holder["name"], holder["shares_held"])

# What did Congress trade recently?
for trade in ko.congress.trades(sort="recent", per_page=10):
    print(trade["member_name"], trade["ticker"], trade["transaction_type"])
```

Get a free API key (200 calls/day, no credit card) at
[ko.io/console](https://ko.io/console), then:

```python
ko = KoClient(api_key="ko_live_...")   # or set KO_API_KEY env var
```

## Async

```python
from ko_edgar import AsyncKoClient

async with AsyncKoClient() as ko:
    result = await ko.stocks.activity("NVDA", quarters=8)
```

## Pagination

```python
from ko_edgar import KoClient, paginate

ko = KoClient()
for trade in paginate(ko.congress.trades, ticker="NVDA", per_page=100):
    ...
```

## Results and errors

Every method returns an `ApiResult`: iterate it for rows, or use
`result.data` / `result.meta` for the raw envelope. `result.truncated` tells
you when the plan's row cap trimmed the response.

```python
from ko_edgar import KoClient, PlanRequiredError, RateLimitError

ko = KoClient()
try:
    yields = ko.macro.treasury_yields(days=90)   # requires Pro
except PlanRequiredError:
    print("macro data needs a Pro plan → https://ko.io/pricing")
except RateLimitError as e:
    print(f"quota resets in {e.retry_after}s")
```

## Escape hatch

Any `/api/v1` endpoint not covered by a typed method:

```python
ko.get("/api/v1/exec-compensation", ticker="AAPL", ceo_only=True)
```

## Links

- Docs: <https://ko.io/docs>
- MCP server (same data inside Claude/Cursor/any agent): <https://ko.io/mcp>
- Repository: <https://github.com/SharpLu/ko-mcp>

MIT licensed.
