> ## 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"
```