edgartools
edgartools is a Python library that retrieves and structures SEC EDGAR filings dating back to 1994, enabling extraction of financial statements, XBRL data, and company information. Use it when analyzing 10-K/10-Q annual and quarterly reports, Form 4 insider trades, 13F institutional holdings, 8-K current events, DEF 14A proxy statements, or screening companies by ticker, CIK identifier, or industry classification.
git clone --depth 1 https://github.com/foryourhealth111-pixel/Vibe-Skills /tmp/edgartools && cp -r /tmp/edgartools/bundled/skills/edgartools ~/.claude/skills/edgartoolsSKILL.md
# edgartools — SEC EDGAR Data
Python library for accessing all SEC filings since 1994 with structured data extraction.
## Authentication (Required)
The SEC requires identification for API access. Always set identity before any operations:
```python
from edgar import set_identity
set_identity("Your Name your.email@example.com")
```
Set via environment variable to avoid hardcoding: `EDGAR_IDENTITY="Your Name your@email.com"`.
## Installation
```bash
uv pip install edgartools
# For AI/MCP features:
uv pip install "edgartools[ai]"
```
## Core Workflow
### Find a Company
```python
from edgar import Company, find
company = Company("AAPL") # by ticker
company = Company(320193) # by CIK (fastest)
results = find("Apple") # by name search
```
### Get Filings
```python
# Company filings
filings = company.get_filings(form="10-K")
filing = filings.latest()
# Global search across all filings
from edgar import get_filings
filings = get_filings(2024, 1, form="10-K")
# By accession number
from edgar import get_by_accession_number
filing = get_by_accession_number("0000320193-23-000106")
```
### Extract Structured Data
```python
# Form-specific object (most common approach)
tenk = filing.obj() # Returns TenK, EightK, Form4, ThirteenF, etc.
# Financial statements (10-K/10-Q)
financials = company.get_financials() # annual
financials = company.get_quarterly_financials() # quarterly
income = financials.income_statement()
balance = financials.balance_sheet()
cashflow = financials.cashflow_statement()
# XBRL data
xbrl = filing.xbrl()
income = xbrl.statements.income_statement()
```
### Access Filing Content
```python
text = filing.text() # plain text
html = filing.html() # HTML
md = filing.markdown() # markdown (good for LLM processing)
filing.open() # open in browser
```
## Key Company Properties
```python
company.name # "Apple Inc."
company.cik # 320193
company.ticker # "AAPL"
company.industry # "ELECTRONIC COMPUTERS"
company.sic # "3571"
company.shares_outstanding # 15115785000.0
company.public_float # 2899948348000.0
company.fiscal_year_end # "0930"
company.exchange # "Nasdaq"
```
## Form → Object Mapping
| Form | Object | Key Properties |
|------|--------|----------------|
| 10-K | TenK | `financials`, `income_statement`, `balance_sheet` |
| 10-Q | TenQ | `financials`, `income_statement`, `balance_sheet` |
| 8-K | EightK | `items`, `press_releases` |
| Form 4 | Form4 | `reporting_owner`, `transactions` |
| 13F-HR | ThirteenF | `infotable`, `total_value` |
| DEF 14A | ProxyStatement | `executive_compensation`, `proposals` |
| SC 13D/G | Schedule13 | `total_shares`, `items` |
| Form D | FormD | `offering`, `recipients` |
**Important:** `filing.financials` does NOT exist. Use `filing.obj().financials`.
## Common Pitfalls
- `filing.financials` → AttributeError; use `filing.obj().financials`
- `get_filings()` has no `limit` param; use `.head(n)` or `.latest(n)`
- Prefer `amendments=False` for multi-period analysis (amended filings may be incomplete)
- Always check for `None` before accessing optional data
## Reference Files
Load these when you need detailed information:
- **[companies.md](references/companies.md)** — Finding companies, screening, batch lookups, Company API
- **[filings.md](references/filings.md)** — Working with filings, attachments, exhibits, Filings collection API
- **[financial-data.md](references/financial-data.md)** — Financial statements, convenience methods, DataFrame export, multi-period analysis
- **[xbrl.md](references/xbrl.md)** — XBRL parsing, fact querying, multi-period stitching, standardization
- **[data-objects.md](references/data-objects.md)** — All supported form types and their structured objects
- **[entity-facts.md](references/entity-facts.md)** — EntityFacts API, FactQuery, FinancialStatement, FinancialFact
- **[ai-integration.md](references/ai-integration.md)** — MCP server setup, Skills installation, `.docs` and `.to_context()` propertiesCloud laboratory platform for automated protein testing and validation. Use when designing proteins and needing experimental validation including binding assays, expression testing, thermostability measurements, enzyme activity assays, or protein sequence optimization. Also use for submitting experiments via API, tracking experiment status, downloading results, optimizing protein sequences for better expression using computational tools (NetSolP, SoluProt, SolubleMPNN, ESM), or managing protein design workflows with wet-lab validation.
This skill should be used for time series machine learning tasks including classification, regression, clustering, forecasting, anomaly detection, segmentation, and similarity search. Use when working with temporal data, sequential patterns, or time-indexed observations requiring specialized algorithms beyond standard ML approaches. Particularly suited for univariate and multivariate time series analysis with scikit-learn compatible APIs.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.
Access real-time and historical stock market data, forex rates, cryptocurrency prices, commodities, economic indicators, and 50+ technical indicators via the Alpha Vantage API. Use when fetching stock prices (OHLCV), company fundamentals (income statement, balance sheet, cash flow), earnings, options data, market news/sentiment, insider transactions, GDP, CPI, treasury yields, gold/silver/oil prices, Bitcoin/crypto prices, forex exchange rates, or calculating technical indicators (SMA, EMA, MACD, RSI, Bollinger Bands). Requires a free API key from alphavantage.co.
Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability.
Comprehensive Python library for astronomy and astrophysics. This skill should be used when working with astronomical data including celestial coordinates, physical units, FITS files, cosmological calculations, time systems, tables, world coordinate systems (WCS), and astronomical data analysis. Use when tasks involve coordinate transformations, unit conversions, FITS file manipulation, cosmological distance calculations, time scale conversions, or astronomical data processing.
Full-stack software development agent for design, implementation, testing, and deployment. Use when the user explicitly asks for end-to-end project creation, feature development, bug fixing, or code refactoring.
Unified biological database evidence owner. Use for gene annotation, variant clinical significance, cancer mutation evidence, GWAS trait associations, pathway mapping, target-disease evidence, protein structures, protein interaction networks, reference single-cell census queries, and cross-database biological ID mapping. Do not use for full single-cell analysis, bulk RNA-seq differential expression, BAM/VCF processing, protein embedding models, metabolic flux modeling, genomic interval ML, or flow-cytometry file parsing.