> ## Documentation Index
> Fetch the complete documentation index at: https://tradewatch.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Fundamentals & SEC Data

> Financial statements, company facts, SEC filings, and insider trades sourced from SEC EDGAR.

Fundamental data is sourced from SEC EDGAR — the SEC's public disclosure system for US-listed companies. This includes structured financial statements parsed from 10-K and 10-Q filings, company registration facts, a full filing index, and insider trading activity from Form 4 submissions.

## Endpoints

| Endpoint | Summary | Key use case |
| - | - | - |
| `GET /stocks/income-statements` | Income statements | Revenue, profit, EPS by period |
| `GET /stocks/balance-sheets` | Balance sheets | Assets, liabilities, equity by period |
| `GET /stocks/cash-flow-statements` | Cash flow statements | Operating, investing, and financing cash flows |
| `GET /stocks/company-facts` | Company facts | SEC CIK, SIC code, fiscal year end |
| `GET /stocks/filings` | SEC filings | Index of 10-K, 10-Q, 8-K, and other filings |
| `GET /stocks/insider-trades` | Insider trades | Form 4 transactions by insiders |

## Financial Statements

**Endpoints:** `GET /stocks/income-statements` · `GET /stocks/balance-sheets` · `GET /stocks/cash-flow-statements`

All three statement endpoints share the same filtering interface: `ticker` (required), `period` (`annual` for 10-K, `quarterly` for 10-Q), `limit`, and a set of `report_date` range filters (`report_date_gte`, `report_date_lte`, `report_date_gt`, `report_date_lt`). Results are ordered by `report_date` descending.

### Income Statement

Revenue, profitability, and per-share metrics for each reporting period.

**Key fields**

| Field | What it means |
| - | - |
| `revenue` | Total revenue (USD) |
| `cost_of_revenue` | Cost of goods sold |
| `gross_profit` | Revenue minus cost of revenue |
| `operating_expenses` | Total operating expenses excluding cost of revenue |
| `operating_income` | Gross profit minus operating expenses |
| `net_income` | Net income attributable to the company |
| `eps` | Basic earnings per share |
| `eps_diluted` | Diluted EPS — accounts for stock options and convertibles |

### Balance Sheet

Financial position at the end of each reporting period.

**Key fields**

| Field | What it means |
| - | - |
| `total_assets` | Sum of all assets |
| `current_assets` | Assets expected to be converted to cash within one year |
| `cash_and_equivalents` | Cash and short-term liquid investments |
| `total_liabilities` | Sum of all liabilities |
| `current_liabilities` | Obligations due within one year |
| `total_equity` | `total_assets` minus `total_liabilities` |
| `long_term_debt` | Debt obligations due beyond one year |
| `retained_earnings` | Cumulative net income retained after dividend payments |

### Cash Flow Statement

Cash movements across operating, investing, and financing activities.

**Key fields**

| Field | What it means |
| - | - |
| `operating_cash_flow` | Cash generated from core business operations |
| `capital_expenditures` | Cash spent on property, plant, and equipment — typically stored as a negative number |
| `free_cash_flow` | `operating_cash_flow + capital_expenditures` (computed field) |
| `investing_cash_flow` | Net cash from investments and acquisitions |
| `financing_cash_flow` | Net cash from debt and equity transactions |
| `dividends_paid` | Cash dividends paid to shareholders — typically negative |
| `share_repurchases` | Cash used to buy back shares — typically negative |
| `net_change_in_cash` | Net increase or decrease in cash for the period |

**Interpretation:** `free_cash_flow` is a computed field. Because `capital_expenditures` is stored as a negative number (a cash outflow), the formula is addition: `operating_cash_flow + capital_expenditures`. A negative `free_cash_flow` is not unusual for companies in heavy investment phases.

**When to use**

* Screening stocks by revenue growth or profit margin across quarters
* Computing year-over-year changes in financial health metrics
* Verifying that a company generates sufficient cash to sustain operations or pay dividends

**Example**

```bash theme={null}
# Last 4 quarterly income statements for AAPL
curl "https://api.tradewatch.io/stocks/income-statements?ticker=AAPL&period=quarterly&limit=4" \
  -H "api-key: YOUR_API_KEY"

# Annual balance sheets for MSFT since 2020
curl "https://api.tradewatch.io/stocks/balance-sheets?ticker=MSFT&period=annual&report_date_gte=2020-01-01" \
  -H "api-key: YOUR_API_KEY"
```

## Company Facts

**Endpoint:** `GET /stocks/company-facts`

Returns static company registration information sourced from EDGAR. Useful as a lookup to resolve a ticker to its SEC identifiers or to understand the company's industry classification.

**Key fields**

| Field | What it means |
| - | - |
| `cik` | SEC Central Index Key — unique EDGAR identifier |
| `company_name` | Legal name as registered with the SEC |
| `sic_code` | Standard Industrial Classification code |
| `sic_description` | Human-readable industry description |
| `state_of_incorporation` | US state (or country) of legal incorporation |
| `fiscal_year_end` | Month-day of fiscal year end in `MM-DD` format (e.g. `12-31`) |

**When to use**

* Resolving a ticker to its SEC CIK for direct EDGAR lookups or cross-referencing with other SEC data sources
* Grouping companies by SIC industry in a screener
* Understanding whether a company's fiscal year aligns with the calendar year when interpreting `report_date` values

**Example**

```bash theme={null}
curl "https://api.tradewatch.io/stocks/company-facts?ticker=AAPL" \
  -H "api-key: YOUR_API_KEY"
```

## SEC Filings

**Endpoint:** `GET /stocks/filings`

Returns an index of SEC EDGAR filings for a company. Includes 10-K (annual report), 10-Q (quarterly report), 8-K (current events/material news), and other filing types. Each record contains the accession number, dates, and a direct link to the document on EDGAR.

**Key fields**

| Field | What it means |
| - | - |
| `accession_number` | Unique EDGAR filing identifier (e.g. `0000320193-23-000077`) |
| `filing_type` | SEC filing type: `10-K`, `10-Q`, `8-K`, etc. |
| `filing_date` | Date the document was submitted to the SEC |
| `report_date` | End date of the period covered by the filing |
| `file_url` | Direct URL to the filing document on SEC EDGAR |

**When to use**

* Linking to source documents from a financial analysis UI
* Filtering for 8-K filings to track material events such as earnings releases or acquisitions
* Auditing the completeness of structured statement data against the original source filing

**Example**

```bash theme={null}
# All 10-K filings for AAPL
curl "https://api.tradewatch.io/stocks/filings?ticker=AAPL&filing_type=10-K" \
  -H "api-key: YOUR_API_KEY"
```

## Insider Trades

**Endpoint:** `GET /stocks/insider-trades`

Returns insider trading activity sourced from SEC Form 4 filings. Form 4 must be filed within two business days of a transaction by company officers, directors, and beneficial owners of more than 10% of a stock class. Results are ordered by `filing_date` descending.

**Key fields**

| Field | What it means |
| - | - |
| `insider_name` | Name of the reporting insider |
| `transaction_date` | Date the trade occurred |
| `filing_date` | Date Form 4 was filed with the SEC |
| `transaction_type` | Type code: `P` (purchase), `S` (sale), `G` (gift), `A` (conversion), `F` (exercise price payment) |
| `shares_transaction` | Number of shares involved in the transaction |
| `price_per_share` | Price per share at time of transaction (USD) |
| `transaction_value` | Total value — computed as `shares_transaction × price_per_share` |
| `securities_owned` | Total shares held by the insider after the transaction |

**Interpretation:** Insider purchases (`P`) are generally viewed as a bullish signal — insiders are buying with personal capital. Insider sales (`S`) are more ambiguous; they are often pre-planned under 10b5-1 plans and may reflect personal liquidity needs rather than a negative outlook. Filter by `transaction_type=P` to isolate open-market purchases.

**When to use**

* Screening for unusual insider buying activity
* Alerting users when an executive makes a large open-market purchase
* Cross-referencing insider transactions with earnings announcement dates

**Example**

```bash theme={null}
# Open-market purchases for AAPL in 2025
curl "https://api.tradewatch.io/stocks/insider-trades?ticker=AAPL&transaction_type=P&filing_date_gte=2025-01-01&filing_date_lte=2025-12-31" \
  -H "api-key: YOUR_API_KEY"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.