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

# 个人持仓

> 读取你在 Dashboard Profile 保存的持仓，让 Agent 带着你的组合上下文回答。

<Note icon="sparkles">
  **可作为 MCP tool 调用**：`personal_holdings` —— 可直接在 Claude / Cursor / 任意 MCP 客户端中调用。接入方式见 [MCP Server](/zh-CN/integration/mcp-server)。
</Note>

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="gray" size="sm">免费 · 0 credits</Badge>

## 它为 Agent 做什么

`personal_holdings` 返回你在 **Dashboard → Profile** 保存的持仓。Agent 需要你的组合上下文时调用它，比如集中度检查、"我持有什么"、按资产类别过滤，或基于你的持仓做研究。

这个工具只读。它不会下单，不会连接券商账户，也不会读取实时账户余额。返回值是你在 Profile 保存的值；如果答案需要当前市场数据，请再调用行情工具。

只返回你自己账号的 Profile 数据。

## 返回值

<ResponseField name="data" type="object" required>
  当前调用者自己账号的已保存持仓信封。

  <Expandable title="data fields">
    <ResponseField name="total_count" type="number" required>
      按过滤条件和 `limit` 返回的持仓数量。
    </ResponseField>

    <ResponseField name="holdings" type="PersonalHolding[]" required>
      Profile 中保存的持仓，最近保存的行排在前面。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.holdings[]" type="PersonalHolding" required>
  <Expandable title="PersonalHolding fields">
    <ResponseField name="symbol" type="string" nullable>保存的 ticker 或 symbol。</ResponseField>
    <ResponseField name="name" type="string" nullable>保存的展示名称。</ResponseField>

    <ResponseField name="asset_class" type="string" required>
      取值为 `equity`、`etf`、`crypto`、`cash`、`fund`、`bond` 或 `other`。
    </ResponseField>

    <ResponseField name="quantity" type="number" nullable>保存的持仓数量。</ResponseField>
    <ResponseField name="market_value" type="number" nullable>保存的市值。</ResponseField>

    <ResponseField name="cost_basis" type="number" nullable>
      保存的该持仓总成本。若 `cost_basis` 和 `quantity` 都存在，Agent 可用 `cost_basis / quantity` 推导平均成本。
    </ResponseField>

    <ResponseField name="currency" type="string" required>币种代码，通常为 `USD`。</ResponseField>
    <ResponseField name="as_of_date" type="string" nullable>这条保存值对应的日期（`YYYY-MM-DD`）。</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">始终为 `0` —— 这次读取免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账号剩余 credits。</ResponseField>

```json title="200 OK · personal_holdings" expandable theme={null}
{
  "data": {
    "total_count": 2,
    "holdings": [
      {
        "symbol": "AAPL",
        "name": "Apple Inc.",
        "asset_class": "equity",
        "quantity": 10,
        "market_value": 2120.5,
        "cost_basis": 1800,
        "currency": "USD",
        "as_of_date": "2026-06-21"
      },
      {
        "symbol": "BTC",
        "name": "Bitcoin",
        "asset_class": "crypto",
        "quantity": 0.25,
        "market_value": 25000,
        "cost_basis": null,
        "currency": "USD",
        "as_of_date": "2026-06-21"
      }
    ]
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

```json title="200 OK · 空持仓" expandable theme={null}
{
  "data": { "total_count": 0, "holdings": [] },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## 说明

<Tip>
  用户问和自己组合相关的问题时，先调用 `personal_holdings`，再只针对相关 ticker 调行情或申报文件工具。这样 Agent 的注意力会留在用户已保存的持仓上。
</Tip>

<Warning>
  你账号下任何仍有效的 API key 或 Remote MCP URL 都可以读取这些已保存的 Profile 数据，直到你删除已保存的行或吊销对应凭证。
</Warning>

<Warning>
  返回值是用户保存的 Profile 值，不是实时行情，也不是券商账户余额。需要当前市场数据时，请调用行情工具。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "personal_holdings",
        "arguments": { "asset_class": "equity", "limit": 10 }
      }
    }
    ```

    ```python Python (HTTP) theme={null}
    import os, requests

    resp = requests.get(
        "https://api.llmquantdata.com/api/personal/holdings",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"asset_class": "equity", "limit": 10},
    ).json()
    print(resp["data"]["total_count"], resp["data"]["holdings"])
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/personal/holdings?asset_class=equity&limit=10" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="全部请求参数" icon="sliders">
  <ParamField query="asset_class" type="string">
    可选过滤条件。取值为 `equity`、`etf`、`crypto`、`cash`、`fund`、`bond` 或 `other`。
  </ParamField>

  <ParamField query="limit" type="number" default={30}>
    最多返回的持仓数量。范围 `1-50`；超过 `50` 会按 `50` 处理。
  </ParamField>
</Accordion>

## 相关接口

<Columns cols={2}>
  <Card title="个人 Profile" icon="user" href="/zh-CN/api/personal/profile">
    读取已保存的风险偏好、投资期限、基准币种和备注。
  </Card>

  <Card title="MCP Server 接入" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒接入 Claude / Cursor / 任意 agent harness。
  </Card>
</Columns>