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

# Portfolio: Fund Holdings and Equity Aggregates

> Portfolio entries are normalized holdings rows from fund disclosure reports. Stocks aggregate equity positions across all funds for cross-fund analysis.

Portfolio data in the MKK API gives you access to the investment holdings disclosed in each fund's periodic reports. The API exposes this data at two levels: normalized `portfolio_entries` that represent individual security positions within a document, and `stocks` that aggregate equity holdings across all funds for cross-fund comparison. You can use this data to track what funds hold, how positions change over time, and which securities appear most widely across the MKK fund universe.

## Portfolio entries

A portfolio entry is a single normalized row from a fund's holdings table in a disclosure report. Each entry represents one security position as reported for a specific fund and period.

### Key fields

| Field              | Description                                       |
| ------------------ | ------------------------------------------------- |
| `security`         | Name of the security                              |
| `isin`             | ISIN code identifying the security                |
| `issuer`           | Issuing entity                                    |
| `bank`             | Custodian or counterparty bank (where applicable) |
| `maturity_date`    | Maturity date for fixed-income instruments        |
| `price`            | Price per unit at the reporting date              |
| `market_value`     | Total market value of the position                |
| `nominal_value`    | Face or nominal value                             |
| `currency`         | Currency of the position                          |
| `portfolio_weight` | Position as a percentage of total portfolio       |
| `section`          | Portfolio section this entry belongs to           |

## Portfolio sections

The `section` field on a portfolio entry indicates the type of asset class or portfolio segment the security belongs to — for example, equity, bond, money market, or repo. Sections correspond to how the fund's disclosure report groups its holdings tables.

You can filter portfolio entries by section to focus on a specific asset class:

```bash theme={null}
GET https://mkk-roan.vercel.app/api/portfolio-entries?fund_code=OJB&section=equity
```

<Tip>
  Use the `section` parameter to narrow results when a fund holds many instruments across multiple asset classes. Without it, you'll receive all holdings for the fund across all sections.
</Tip>

## Portfolio entries vs. portfolio rows

The API distinguishes between two representations of portfolio data:

* **`portfolio_entries`** — normalized objects with typed fields (`market_value`, `isin`, `portfolio_weight`, etc.). These are the best choice for structured querying and data analysis.
* **`portfolio_rows`** — raw table rows as parsed from the PDF, each with a `columns` array containing the cell values in their original order. Use `portfolio_rows` when you need to inspect the raw parsed table structure or handle columns that don't map to normalized fields.

`portfolio_rows` are available on individual document responses. `portfolio_entries` are available both on documents and via the dedicated `/portfolio-entries` endpoint.

## Stocks

Stocks are an aggregate view of equity securities across all funds in the MKK API. Each stock record combines holdings data from every fund that reported a position in a given security, giving you a cross-fund picture of that equity.

### Stock fields

| Field                 | Description                                            |
| --------------------- | ------------------------------------------------------ |
| `key`                 | Stable slug identifier for the stock                   |
| `security`            | Security name                                          |
| `isin`                | ISIN code                                              |
| `issuer`              | Issuing entity                                         |
| `sections`            | Portfolio sections where this security has appeared    |
| `entry_count`         | Total number of portfolio entry records                |
| `document_count`      | Number of documents containing this security           |
| `fund_count`          | Number of distinct funds holding this security         |
| `latest_holder_count` | Number of funds holding it in the most recent period   |
| `latest_market_value` | Aggregate market value in the most recent period       |
| `average_weight`      | Average portfolio weight across all holdings           |
| `max_weight`          | Highest portfolio weight recorded                      |
| `latest_period`       | Most recent period in which this security was reported |

## Example requests

<CodeGroup>
  ```bash Get portfolio entries for a fund theme={null}
  curl "https://mkk-roan.vercel.app/api/portfolio-entries?fund_code=OJB"
  ```

  ```bash Filter by section theme={null}
  curl "https://mkk-roan.vercel.app/api/portfolio-entries?fund_code=OJB&section=equity"
  ```

  ```bash List all stocks theme={null}
  curl https://mkk-roan.vercel.app/api/stocks
  ```

  ```bash Get a specific stock theme={null}
  curl https://mkk-roan.vercel.app/api/stocks/akbank-tas
  ```
</CodeGroup>

### Example portfolio entry

```json theme={null}
{
  "security": "AKBANK T.A.Ş.",
  "isin": "TRAKBNK91N6",
  "issuer": "Akbank",
  "bank": null,
  "maturity_date": null,
  "price": 42.50,
  "market_value": 2125000.00,
  "nominal_value": 50000,
  "currency": "TRY",
  "portfolio_weight": 3.82,
  "section": "equity"
}
```

### Example stock record

```json theme={null}
{
  "key": "akbank-tas",
  "security": "AKBANK T.A.Ş.",
  "isin": "TRAKBNK91N6",
  "issuer": "Akbank",
  "sections": ["equity"],
  "entry_count": 284,
  "document_count": 201,
  "fund_count": 22,
  "latest_holder_count": 18,
  "latest_market_value": 48200000.00,
  "average_weight": 2.94,
  "max_weight": 9.12,
  "latest_period": "2023-Q4"
}
```