# ETF Holdings
Source: https://docs.llmquantdata.com/en/api/etf/holdings

Latest/as-of regulatory holdings for one US-listed ETF — full position list, normalized, sorted by weight descending.

<Note icon="sparkles">
  **Available as MCP tool**: `etf_holdings` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit (0 if unsupported)</Badge>

## What it does for your agent

`etf_holdings` returns the **latest or as-of regulatory disclosure holdings** for a single US-listed ETF — full position list (subject to `limit`), each row normalized to a common `EtfHolding` shape with `ticker` / `cusip` / `isin` / `sedol` identifiers, `weight`, `market_value`, `shares`, and `sector` / `country` / `asset_type`. Rows are sorted by `weight` descending.

Use it when the agent needs the **actual position table** — to compute concentration (Top-10 weight, HHI), overlap between two ETFs (call twice and diff by CUSIP / ISIN), or to build a thematic basket from an ETF's underlying. For ETF basic info, top-N summary, and exposure breakdowns, prefer the lighter [`etf_lookup`](/en/api/etf/lookup) which is free.

This endpoint has one documented exception to the platform's "the action runs, you pay" billing rule: an `unsupported` ticker is treated as a free **coverage check**, not a holdings retrieval. Covered tickers return rows and cost 1 credit; tickers outside coverage return `200 OK` with `coverage_status="unsupported"`, empty `holdings`, and **0 credits**. This is a specific sanctioned carve-out for ETF Holdings — it is not a general "no data = free" rule elsewhere on the platform. Pass `as_of=YYYY-MM-DD` for the latest snapshot with `as_of_date <= as_of`; cross-ETF overlap is still computed client-side.

## Response

<ResponseField name="data" type="EtfHoldingsResult">
  <Expandable title="EtfHoldingsResult fields">
    <ResponseField name="ticker" type="string">
      ETF ticker (uppercased).
    </ResponseField>

    <ResponseField name="fund_name" type="string">
      Fund display name. `null` when `coverage_status="unsupported"`.
    </ResponseField>

    <ResponseField name="issuer" type="string">
      Issuer / sponsor.
    </ResponseField>

    <ResponseField name="holdings" type="EtfHolding[]">
      Position rows sorted by `weight` descending. Empty array when `coverage_status="unsupported"`.

      <Expandable title="EtfHolding fields">
        <ResponseField name="holding_name" type="string">Holding name as filed.</ResponseField>

        <ResponseField name="ticker" type="string">
          Underlying ticker. **Often `null` for bonds, cash, derivatives, and crypto trusts** — use `cusip` / `isin` to identify these rows.
        </ResponseField>

        <ResponseField name="cusip" type="string">CUSIP. Preferred join key for overlap computation.</ResponseField>
        <ResponseField name="isin" type="string">ISIN. Secondary join key.</ResponseField>
        <ResponseField name="sedol" type="string">SEDOL, when present in the filing.</ResponseField>

        <ResponseField name="asset_type" type="string">
          `equity` / `fixed_income` / `cash` / `derivative` / `crypto` / `other`.
        </ResponseField>

        <ResponseField name="sector" type="string">Sector classification; may be `null`.</ResponseField>
        <ResponseField name="country" type="string">Country of risk; may be `null`.</ResponseField>
        <ResponseField name="shares" type="number">Number of shares / units held.</ResponseField>
        <ResponseField name="market_value" type="number">Market value in USD.</ResponseField>

        <ResponseField name="weight" type="number">
          Portfolio weight as a decimal (e.g. `0.071` for 7.1%).
        </ResponseField>

        <ResponseField name="notional_value" type="number">
          Notional for derivatives and special instruments; may be `null`.
        </ResponseField>

        <ResponseField name="source" type="string">Per-row identifier of the originating SEC disclosure dataset.</ResponseField>
        <ResponseField name="source_url" type="string">Link to the related SEC disclosure dataset, for citation.</ResponseField>
        <ResponseField name="as_of_date" type="string">Regulatory disclosure report date this row reflects.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="source" type="string">Top-level identifier of the originating SEC disclosure dataset.</ResponseField>
    <ResponseField name="source_url" type="string">Top-level link to the related SEC disclosure dataset, for citation.</ResponseField>
    <ResponseField name="as_of_date" type="string">Regulatory disclosure snapshot date (`YYYY-MM-DD`). If `as_of` is passed, this is the latest available date `<= as_of`.</ResponseField>
    <ResponseField name="fetched_at" type="string">ISO timestamp when LLMQuant Data last refreshed this holdings data.</ResponseField>
    <ResponseField name="stale" type="boolean">`true` when the snapshot is past the freshness window or a refresh degraded.</ResponseField>

    <ResponseField name="coverage_status" type="string">
      One of `full` / `partial` / `stale` / `unsupported`.
    </ResponseField>

    <ResponseField name="coverage_notice" type="string">
      Plain-English explanation of what's covered or why it isn't.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">
  `1` for `full` / `partial` / `stale` returns. `0` when `coverage_status="unsupported"`.
</ResponseField>

<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · etf_holdings (supported)" expandable theme={null}
{
  "data": {
    "ticker": "SPY",
    "fund_name": "SPDR S&P 500 ETF Trust",
    "issuer": "State Street",
    "holdings": [
      {
        "holding_name": "APPLE INC",
        "ticker": "AAPL",
        "cusip": "037833100",
        "isin": "US0378331005",
        "sedol": null,
        "asset_type": "equity",
        "sector": "Information Technology",
        "country": "US",
        "shares": 168000000,
        "market_value": 30450000000,
        "weight": 0.071,
        "notional_value": null,
        "source": "sec_nport",
        "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
        "as_of_date": "2019-09-30"
      },
      {
        "holding_name": "MICROSOFT CORP",
        "ticker": "MSFT",
        "cusip": "594918104",
        "isin": "US5949181045",
        "sedol": null,
        "asset_type": "equity",
        "sector": "Information Technology",
        "country": "US",
        "shares": 78000000,
        "market_value": 27890000000,
        "weight": 0.065,
        "notional_value": null,
        "source": "sec_nport",
        "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
        "as_of_date": "2019-09-30"
      }
    ],
    "source": "sec_nport",
    "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
    "as_of_date": "2019-09-30",
    "fetched_at": "2026-05-12T03:14:00Z",
    "stale": false,
    "coverage_status": "full",
    "coverage_notice": "Latest available SEC regulatory disclosure snapshot. Not the issuer's daily latest holdings."
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

```json title="200 OK · etf_holdings (unsupported)" expandable theme={null}
{
  "data": {
    "ticker": "IBIT",
    "fund_name": null,
    "issuer": null,
    "holdings": [],
    "source": "sec_nport",
    "source_url": null,
    "as_of_date": null,
    "fetched_at": null,
    "stale": false,
    "coverage_status": "unsupported",
    "coverage_notice": "IBIT is not in the current covered ETF list. As a spot Bitcoin trust, its SEC disclosure path differs from the conventional ETFs we cover today."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## Credit rule

| Coverage outcome                                                   | HTTP  |                         `creditsUsed`                         |
| ------------------------------------------------------------------ | ----- | :-----------------------------------------------------------: |
| `full` / `partial` / `stale` (holdings returned)                   | `200` |                              `1`                              |
| `unsupported` (no holdings, explicit notice)                       | `200` |                              `0`                              |
| Caller has insufficient credits **and** ticker is in coverage      | `402` |                  n/a — holdings not returned                  |
| Caller has insufficient credits **and** ticker is outside coverage | `200` | `0` — coverage envelope is delivered without spending credits |

Core rule: checking whether a ticker is covered is free; only a resolved holdings retrieval charges 1 credit. This free-when-unsupported behaviour is a documented, sanctioned exception scoped to ETF Holdings — every other endpoint charges as soon as the action runs, even when the result is empty.

## Notes

<Tip>
  **For overlap between two ETFs**, call `etf_holdings` twice and diff client-side. **Join by `cusip` first**, then `isin`, then `ticker` — holding rows often have a `null` ticker for bonds / cash / derivatives, but stable identifiers like CUSIP survive.
</Tip>

<Tip>
  **Concentration metrics** (Top-10 weight, HHI) are cheap once you have the rows. Sort is already weight-descending; just slice.
</Tip>

<Tip>
  Use [`etf_lookup`](/en/api/etf/lookup) first (free) to confirm coverage and read `holdings_count` before deciding the `limit` for this call. Broad-market ETFs like `VTI` have thousands of positions; default `limit=50` is enough for most agent workflows.
</Tip>

### Current limitations

<Warning>
  **Not current / daily holdings.** Rows reflect the latest SEC official regulatory disclosure snapshot (typically monthly or quarterly disclosure with a public-release lag), not the issuer's daily book. `as_of_date` makes this explicit.
</Warning>

<Warning>
  **Per-row `ticker` is nullable.** Bonds, cash, derivatives, and crypto trusts frequently have no ticker in a holdings row. Always fall back to CUSIP / ISIN for identification and joins.
</Warning>

<Warning>
  **No `etf_compare_holdings` server-side.** Cross-ETF overlap, weight-difference, and basket comparisons are agent-side computations from two `etf_holdings` calls.
</Warning>

<Warning>
  **Only single-date historical lookup is supported.** `as_of` selects the latest snapshot at or before one date; ranges, quarters, and multi-period returns are not part of this endpoint.
</Warning>

<Warning>
  **Coverage is limited.** Currently covered: `SPY`, `QQQ`, `VTI`, `SOXX`, `ARKK` and other curated popular ETFs. `IBIT` / `DRAM` are outside coverage today.
</Warning>

<Warning>
  **Regulatory disclosures only.** Issuer fact-sheet PDFs and other non-regulatory datasets are not used in this response.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // Default — top 50 by weight
    {
      "method": "tools/call",
      "params": {
        "name": "etf_holdings",
        "arguments": { "ticker": "SPY" }
      }
    }

    // Custom limit + as-of snapshot
    {
      "method": "tools/call",
      "params": {
        "name": "etf_holdings",
        "arguments": { "ticker": "VTI", "limit": 200, "as_of": "2025-10-01" }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    resp = requests.get(
        "https://api.llmquantdata.com/api/etf/holdings",
        headers=headers,
        params={"ticker": "VTI", "limit": 50, "as_of": "2025-10-01"},
    ).json()
    d = resp["data"]
    if d["coverage_status"] == "unsupported":
        print(f"Not covered: {d['coverage_notice']}")
    else:
        top10_weight = sum(h["weight"] or 0 for h in d["holdings"][:10])
        print(f"{d['ticker']} snapshot {d['as_of_date']}  Top-10 weight: {top10_weight:.1%}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/etf/holdings?ticker=VTI&limit=50&as_of=2025-10-01" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="etf_holdings — request parameters" icon="sliders">
  <ParamField type="string">
    US-listed ETF ticker (e.g. `SPY`, `QQQ`, `VTI`, `SOXX`, `ARKK`). Case-insensitive; the server uppercases and trims. Tickers outside coverage return `200 OK` with `coverage_status="unsupported"` and `creditsUsed=0`.
  </ParamField>

  <ParamField type="integer">
    Maximum number of holdings rows to return, sorted by `weight` descending. Default `50`. Max `500`. For broad-market ETFs (e.g. `VTI`), the full underlying list will exceed the maximum; cursor-based pagination is on the roadmap.
  </ParamField>

  <ParamField type="string">
    Optional period date in `YYYY-MM-DD` format. Returns the latest holdings snapshot with `as_of_date <= as_of`; omit it for the latest available snapshot.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="ETF Lookup" icon="magnifying-glass" href="/en/api/etf/lookup">
    Fund identity, SEC mapping, top holdings summary, and exposure breakdowns — free.
  </Card>

  <Card title="Equity Historical Prices" icon="chart-line" href="/en/api/prices/equity-historical">
    ETF OHLCV history lives on the equity daily-bar endpoint.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# ETF Lookup
Source: https://docs.llmquantdata.com/en/api/etf/lookup

Fund identity, SEC mapping, latest/as-of regulatory snapshot, derived exposure summary, and top holdings for a single US-listed ETF.

<Note icon="sparkles">
  **Available as MCP tool**: `etf_lookup` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · 0 credits</Badge>

## What it does for your agent

`etf_lookup` returns a single US-listed ETF's **basic info** (name, issuer, asset class, category), **SEC registration info** (CIK / Series / Class), the **latest or as-of regulatory disclosure snapshot**, and **summary derivatives** — top holdings, sector / country / asset-type exposure. Use it as the ETF context entry point: when an agent needs to know what an ETF is, what it held around a reporting date, or whether the symbol is even covered, this is the first call.

It is **not** an OHLCV endpoint. For price history use [`equity_historical_prices`](/en/api/prices/equity-historical) — ETFs trade like stocks and live on the same daily-bar contract. Pass `as_of=YYYY-MM-DD` when the agent needs the latest snapshot with `as_of_date <= as_of`; this is still a regulatory snapshot, **not the issuer's daily latest book**.

Tickers outside coverage (today: `IBIT` / `DRAM`) still return `200 OK` with `coverage_status="unsupported"` and an explicit `coverage_notice` — so the agent can keep reasoning instead of mis-reading silence as "no holdings".

## Response

<ResponseField name="data" type="EtfLookupResult">
  <Expandable title="EtfLookupResult fields">
    <ResponseField name="ticker" type="string">
      ETF ticker (uppercased, e.g. `SPY`).
    </ResponseField>

    <ResponseField name="fund_name" type="string">
      Fund display name. `null` when `coverage_status="unsupported"`.
    </ResponseField>

    <ResponseField name="issuer" type="string">
      Issuer / sponsor (e.g. `State Street`, `Vanguard`, `Invesco`, `BlackRock`).
    </ResponseField>

    <ResponseField name="asset_class" type="string">
      `equity` / `fixed_income` / `commodity` / `crypto` / `multi_asset` / `other`.
    </ResponseField>

    <ResponseField name="category" type="string">
      Issuer or platform category label (e.g. `Large Blend`, `Semiconductors`).
    </ResponseField>

    <ResponseField name="cik" type="string">SEC CIK of the registrant.</ResponseField>
    <ResponseField name="series_id" type="string">SEC Investment Company Series ID.</ResponseField>
    <ResponseField name="class_id" type="string">SEC Class ID.</ResponseField>

    <ResponseField name="expense_ratio" type="number">
      Expense ratio when available in regulatory filings; may be `null`.
    </ResponseField>

    <ResponseField name="aum" type="number">AUM in USD; may be `null`.</ResponseField>
    <ResponseField name="nav" type="number">Latest NAV; may be `null`.</ResponseField>
    <ResponseField name="market_price" type="number">Latest market price; may be `null`.</ResponseField>
    <ResponseField name="premium_discount_pct" type="number">Premium / discount vs NAV; may be `null`.</ResponseField>
    <ResponseField name="inception_date" type="string">Fund inception date (`YYYY-MM-DD`).</ResponseField>

    <ResponseField name="holdings_count" type="number">
      Number of holdings in the latest regulatory snapshot. Use this to decide whether to paginate `etf_holdings`.
    </ResponseField>

    <ResponseField name="top_holdings" type="array">
      Top holdings summary (typically top 10 by weight). For the full list call [`etf_holdings`](/en/api/etf/holdings).
    </ResponseField>

    <ResponseField name="sector_exposure" type="array">
      Sector breakdown; may be `null`.
    </ResponseField>

    <ResponseField name="country_exposure" type="array">
      Country breakdown; may be `null`.
    </ResponseField>

    <ResponseField name="asset_type_exposure" type="array">
      Asset-type breakdown (equity / fixed\_income / cash / derivative / …); may be `null`.
    </ResponseField>

    <ResponseField name="source" type="string">
      Identifier of the originating SEC regulatory disclosure dataset. Always present, even when the ticker is outside coverage.
    </ResponseField>

    <ResponseField name="source_url" type="string">
      Link to the underlying SEC disclosure dataset, for citation.
    </ResponseField>

    <ResponseField name="as_of_date" type="string">
      Date the regulatory disclosure snapshot reflects (`YYYY-MM-DD`). If `as_of` is passed, this is the latest available date `<= as_of`. **Not the fetch time, not "today".**
    </ResponseField>

    <ResponseField name="fetched_at" type="string">
      ISO timestamp when LLMQuant Data last refreshed this ETF's profile and holdings summary.
    </ResponseField>

    <ResponseField name="stale" type="boolean">
      `true` when the snapshot is past the freshness window or the refresh degraded to older available data.
    </ResponseField>

    <ResponseField name="coverage_status" type="string">
      One of `full` / `partial` / `stale` / `unsupported`. See [Coverage semantics](#coverage-semantics).
    </ResponseField>

    <ResponseField name="coverage_notice" type="string">
      Plain-English explanation of what's covered or why it isn't. Always present.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — lookup is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · etf_lookup (supported)" expandable theme={null}
{
  "data": {
    "ticker": "SPY",
    "fund_name": "SPDR S&P 500 ETF Trust",
    "issuer": "State Street",
    "asset_class": "equity",
    "category": "Large Blend",
    "cik": "0000884394",
    "series_id": "S000004310",
    "class_id": "C000012075",
    "expense_ratio": 0.0945,
    "aum": null,
    "nav": null,
    "market_price": null,
    "premium_discount_pct": null,
    "inception_date": "1993-01-22",
    "holdings_count": 503,
    "top_holdings": [
      { "ticker": "AAPL", "holding_name": "APPLE INC", "weight": 0.071 },
      { "ticker": "MSFT", "holding_name": "MICROSOFT CORP", "weight": 0.065 }
    ],
    "sector_exposure": [
      { "sector": "Information Technology", "weight": 0.297 },
      { "sector": "Financials", "weight": 0.135 }
    ],
    "country_exposure": [{ "country": "US", "weight": 0.99 }],
    "asset_type_exposure": [{ "asset_type": "equity", "weight": 0.995 }],
    "source": "sec_nport",
    "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
    "as_of_date": "2019-09-30",
    "fetched_at": "2026-05-12T03:14:00Z",
    "stale": false,
    "coverage_status": "full",
    "coverage_notice": "Latest available SEC regulatory disclosure snapshot. Not the issuer's daily latest holdings."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

```json title="200 OK · etf_lookup (outside coverage)" expandable theme={null}
{
  "data": {
    "ticker": "IBIT",
    "fund_name": null,
    "issuer": null,
    "asset_class": null,
    "category": null,
    "cik": null,
    "series_id": null,
    "class_id": null,
    "expense_ratio": null,
    "aum": null,
    "nav": null,
    "market_price": null,
    "premium_discount_pct": null,
    "inception_date": null,
    "holdings_count": null,
    "top_holdings": null,
    "sector_exposure": null,
    "country_exposure": null,
    "asset_type_exposure": null,
    "source": "sec_nport",
    "source_url": null,
    "as_of_date": null,
    "fetched_at": null,
    "stale": false,
    "coverage_status": "unsupported",
    "coverage_notice": "IBIT is not in the current covered ETF list. As a spot Bitcoin trust, its SEC disclosure path differs from the conventional ETFs we cover today; we may add a dedicated path later."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## Coverage semantics

| `coverage_status` | Meaning                                                                                                                        | `stale`             |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `full`            | Ticker is in the current covered ETF list; core fields and the holdings snapshot are available.                                | `false` (typically) |
| `partial`         | Ticker is covered but some fields are missing — `null` on the affected fields.                                                 | `false` / `true`    |
| `stale`           | Snapshot was once available but the latest refresh failed or aged past the freshness window. Older available data is returned. | `true`              |
| `unsupported`     | Ticker is **not** in the current covered list. Returns `200 OK` with an explicit notice — never a silent empty.                | `false`             |

Treat `coverage_status` as a contract: agents should branch on it before consuming downstream fields.

## Notes

<Tip>
  **Pair with [`etf_holdings`](/en/api/etf/holdings)** when the agent needs the full position list, weights, or wants to compute overlap between two ETFs. `etf_lookup` already returns a `top_holdings` summary; only escalate to `etf_holdings` if the top-N isn't enough.
</Tip>

<Tip>
  For ETF **price history**, do not call this tool — call [`equity_historical_prices`](/en/api/prices/equity-historical) with the ETF ticker. ETF OHLCV lives on the same equity historical contract.
</Tip>

<Tip>
  `lookup` is free (0 credits), but the call is still recorded in your usage log. Use it to confirm whether an ETF is covered before spending credits on holdings.
</Tip>

### Current limitations

<Warning>
  **Coverage is limited.** We cover a curated set of popular ETFs today (e.g. `SPY`, `QQQ`, `VTI`, `SOXX`, `ARKK`). Tickers outside coverage return `coverage_status="unsupported"` — never a silent empty. We do **not** promise the full US ETF universe.
</Warning>

<Warning>
  **Regulatory disclosure snapshot, not daily.** Holdings + exposure come from SEC official regulatory disclosure datasets with a multi-week to \~60-day publication lag. `as_of_date` is the disclosure report date, **not "today's holdings"**.
</Warning>

<Warning>
  **`IBIT` / `DRAM` are outside coverage today.** `IBIT` is a spot Bitcoin trust whose SEC disclosure path differs from the conventional ETFs we cover. `DRAM` is not currently covered. Both return `coverage_status="unsupported"`.
</Warning>

<Warning>
  **Regulatory disclosures only.** Issuer fact-sheet PDFs are not used, so `expense_ratio` / `aum` / `nav` / `market_price` / `premium_discount_pct` may be `null`.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // As-of lookup — latest snapshot at or before 2025-10-01
    {
      "method": "tools/call",
      "params": {
        "name": "etf_lookup",
        "arguments": { "ticker": "VTI", "as_of": "2025-10-01" }
      }
    }

    // Unsupported ticker — returns 200 OK with coverage_status="unsupported"
    {
      "method": "tools/call",
      "params": {
        "name": "etf_lookup",
        "arguments": { "ticker": "IBIT" }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    resp = requests.get(
        "https://api.llmquantdata.com/api/etf/lookup",
        headers=headers,
        params={"ticker": "VTI", "as_of": "2025-10-01"},
    ).json()
    d = resp["data"]
    if d["coverage_status"] == "unsupported":
        print(f"Not covered: {d['coverage_notice']}")
    else:
        print(f"{d['ticker']} · {d['fund_name']} · {d['holdings_count']} holdings · "
              f"snapshot {d['as_of_date']} (stale={d['stale']})")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/etf/lookup?ticker=VTI&as_of=2025-10-01" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="etf_lookup — request parameters" icon="sliders">
  <ParamField type="string">
    US-listed ETF ticker (e.g. `SPY`, `QQQ`, `VTI`, `SOXX`, `ARKK`). Case-insensitive; the server uppercases and trims. Only `A-Z`, `0-9`, `.`, `-` are accepted. Tickers outside coverage return `200 OK` with `coverage_status="unsupported"`.
  </ParamField>

  <ParamField type="string">
    Optional period date in `YYYY-MM-DD` format. Returns the latest regulatory snapshot with `as_of_date <= as_of`; omit it for the latest available snapshot.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="ETF Holdings" icon="layer-group" href="/en/api/etf/holdings">
    Full holdings list for one ETF — paginated, sorted by weight descending.
  </Card>

  <Card title="Equity Historical Prices" icon="chart-line" href="/en/api/prices/equity-historical">
    ETF OHLCV history lives on the equity daily-bar endpoint.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# 13F Holdings by Manager
Source: https://docs.llmquantdata.com/en/api/filings/13f-by-manager

List a single institutional manager's full SEC Form 13F holdings for a given quarter — the "what is this fund holding?" lookup.

<Note icon="sparkles">
  **Available as MCP tool**: `sec_13f_list_manager_holdings` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit per call</Badge>

## What it does for your agent

`sec_13f_list_manager_holdings` is the **forward direction** of the 13F smart-money lookup: given a `manager_cik` or natural-language `manager_name` plus optional `(year, quarter)`, return that institution's full SEC Form 13F-HR holdings for that quarter — CUSIP, mapped ticker, position value, share count, voting authority, options vs cash. Use it when an agent already knows the fund and wants to enumerate its book.

Pass two different `(year, quarter)` values to do **quarter-over-quarter holdings diffs** (added / trimmed / new buys / fully sold) for the same fund.

This tool is **not semantic search**. `manager_name` is resolved by a lightweight server-side `exact → alias → light fuzzy` matcher; it doesn't accept long natural-language queries. Coverage is the **requested quarter's top 1,000 institutional managers** ranked by 13F reportable value (an AUM proxy); each quarter has its own top 1,000. Managers outside that quarter's covered set return empty `data` with an explanatory `meta.notice`.

## Response

<ResponseField name="data" type="ManagerHoldingsResult">
  <Expandable title="ManagerHoldingsResult fields">
    <ResponseField name="ranking_period" type="string">
      Quarter (YYYY-MM-DD) the response data is from; equals the quarter-end matching your `(year, quarter)` input.
    </ResponseField>

    <ResponseField name="manager" type="object">
      Resolved manager identity and AUM proxy.

      <Expandable title="manager fields">
        <ResponseField name="manager_cik" type="string">SEC CIK.</ResponseField>
        <ResponseField name="manager_name" type="string">Canonical manager name.</ResponseField>
        <ResponseField name="match_type" type="string">How the manager was resolved: `cik` / `exact` / `alias` / `fuzzy`.</ResponseField>
        <ResponseField name="latest_reportable_value_usd" type="number">**Manager's overall most-recent size** (independent of requested quarter): latest 13F reportable value (AUM proxy).</ResponseField>
        <ResponseField name="latest_reportable_value_period" type="string">Period of `latest_reportable_value_usd`.</ResponseField>
        <ResponseField name="period_rank" type="integer">Manager's rank in the covered Top 1,000 manager set for `ranking_period` (null if no ranking exists for that quarter).</ResponseField>
        <ResponseField name="period_reportable_value_usd" type="number">Manager's reportable value for `ranking_period` (USD).</ResponseField>
        <ResponseField name="is_in_covered_manager_set" type="boolean">Whether the manager is in `ranking_period`'s covered Top 1,000 manager set — evaluated per quarter, since each quarter has its own Top 1,000.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="filing" type="object">
      Filing identifier of the matched 13F-HR submission.

      <Expandable title="filing fields">
        <ResponseField name="filing_type" type="string">`13F-HR` or `13F-HR/A` (amendment).</ResponseField>
        <ResponseField name="accession_number" type="string">SEC accession number.</ResponseField>
        <ResponseField name="filed_at" type="string">Date filed (`YYYY-MM-DD`).</ResponseField>
        <ResponseField name="period_of_report" type="string">Quarter-end the filing reports on.</ResponseField>
        <ResponseField name="is_amendment" type="boolean">True for an amendment filing.</ResponseField>
        <ResponseField name="table_entry_total" type="integer">Total holdings rows in the source filing.</ResponseField>
        <ResponseField name="table_value_total" type="number">Sum of `value_usd` across the source filing.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="holdings" type="Holding[]">
      Holdings sorted by `value_usd` descending.

      <Expandable title="Holding fields">
        <ResponseField name="cusip" type="string">CUSIP identifier.</ResponseField>
        <ResponseField name="ticker" type="string">Mapped U.S. ticker (null for cash, options, private placements).</ResponseField>
        <ResponseField name="name_of_issuer" type="string">Issuer name as filed.</ResponseField>
        <ResponseField name="title_of_class" type="string">Security class (e.g. `COM`).</ResponseField>
        <ResponseField name="value_usd" type="number">Position market value in USD.</ResponseField>
        <ResponseField name="shares" type="number">Number of shares (or principal amount).</ResponseField>
        <ResponseField name="shares_type" type="string">`SH` (shares) or `PRN` (principal).</ResponseField>
        <ResponseField name="investment_discretion" type="string">`SOLE` / `SHARED` / `NONE` / `DFND`.</ResponseField>
        <ResponseField name="voting_sole" type="number">Sole voting authority shares.</ResponseField>
        <ResponseField name="voting_shared" type="number">Shared voting authority shares.</ResponseField>
        <ResponseField name="voting_none" type="number">No voting authority shares.</ResponseField>
        <ResponseField name="put_call" type="string">`PUT` / `CALL`, or `null` for non-options.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed (always `1`).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Credits left after this call.</ResponseField>
<ResponseField name="meta.notice" type="string">Plain-English coverage note, when the response needs one.</ResponseField>

```json title="200 OK · sec_13f_list_manager_holdings" expandable theme={null}
{
  "data": {
    "ranking_period": "2025-12-31",
    "manager": {
      "manager_cik": "1067983",
      "manager_name": "BERKSHIRE HATHAWAY INC",
      "match_type": "alias",
      "latest_reportable_value_usd": 302459211458,
      "latest_reportable_value_period": "2025-12-31",
      "period_rank": 7,
      "period_reportable_value_usd": 302459211458,
      "is_in_covered_manager_set": true
    },
    "filing": {
      "filing_type": "13F-HR",
      "accession_number": "0000950123-26-001234",
      "filed_at": "2026-02-14",
      "period_of_report": "2025-12-31",
      "is_amendment": false,
      "table_entry_total": 110,
      "table_value_total": 302459211458
    },
    "holdings": [
      {
        "cusip": "025816109",
        "ticker": "AXP",
        "name_of_issuer": "AMERICAN EXPRESS CO",
        "title_of_class": "COM",
        "value_usd": 55145133598,
        "shares": 149061045,
        "shares_type": "SH",
        "investment_discretion": "SOLE",
        "voting_sole": 149061045,
        "voting_shared": 0,
        "voting_none": 0,
        "put_call": null
      }
    ]
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 999,
    "notice": "13F coverage: Top 1,000 managers for quarter 2025-12-31 (each quarter has its own Top 1,000). Ranking data available for 4 quarters: 2025-03-31 … 2025-12-31. Reportable value is an AUM proxy excluding fixed income, options, non-U.S. holdings, and shorts."
  }
}
```

## Notes

<Tip>
  **Canonical workflow**: pair this tool with `sec_13f_list_top_managers` (to derive a fund pool, e.g. top 30) and `sec_13f_list_ticker_holders` (to invert "who holds X?"). For consensus / overlap analyses: enumerate top managers → fan out one call per manager into this tool → aggregate client-side.
</Tip>

<Tip>
  **Typical agent queries**: this tool returns single-quarter holdings only; quarter-over-quarter comparisons require the agent to call it twice and diff locally.

  <Prompt description="Single-quarter holdings for one manager">
    Show me Berkshire's 13F holdings for 2025 Q4 — what are the top 10 positions by value?
  </Prompt>

  <Prompt description="Quarter-over-quarter holdings change for one manager">
    Compare Berkshire's 13F holdings between the latest two quarters — which positions did they add to, trim, newly buy, or fully sell?
  </Prompt>
</Tip>

<Warning>
  **Top 1,000 only.** Outside-scope `manager_cik` returns 200 OK with empty `data` and `meta.notice`.
</Warning>

<Warning>
  Errors: `manager_name` resolves to nothing → 200 OK with empty `data` and `meta.notice`. `manager_name` is ambiguous → `400 invalid_request`; provide `manager_cik` to disambiguate.
</Warning>

<Warning>
  Confidential / delayed-disclosure holdings are not exposed.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_manager_holdings",
        "arguments": {
          "manager_name": "Berkshire Hathaway",
          "year": 2025,
          "quarter": 4,
          "limit": 200
        }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/filings/13f/by-manager",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"manager_name": "Berkshire Hathaway", "year": 2025, "quarter": 4},
    ).json()
    manager = resp["data"]["manager"]
    for h in resp["data"]["holdings"][:10]:
        label = h["ticker"] or h["cusip"]
        print(f"{label:<8} ${h['value_usd']:>15,}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/filings/13f/by-manager?manager_name=Berkshire%20Hathaway&year=2025&quarter=4" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="sec_13f_list_manager_holdings — request parameters" icon="sliders">
  <ParamField type="string">
    SEC CIK of the filing manager (e.g. `1067983` for Berkshire Hathaway). When both `manager_cik` and `manager_name` are supplied, `manager_cik` is authoritative; disagreement returns `400`.
  </ParamField>

  <ParamField type="string">
    Free-form manager name (e.g. `Bridgewater`, `Berkshire Hathaway`). Resolved server-side via `exact → alias → light fuzzy`.
  </ParamField>

  <ParamField type="integer">
    Calendar year of the quarter to query (e.g. `2025`). Range `[2013, 2030]`. **Must be paired with `quarter`**; omit both for the manager's most recent covered quarter.
  </ParamField>

  <ParamField type="integer">
    Calendar quarter `1-4` (Q1=Jan-Mar, Q4=Oct-Dec). **Must be paired with `year`**.
  </ParamField>

  <ParamField type="integer">
    Maximum holdings returned. Default `200`. Max `500`.
  </ParamField>

  <Warning>
    At least one of `manager_cik` or `manager_name` must be provided.
  </Warning>
</Accordion>

## Related

<Columns>
  <Card title="13F Holders by Ticker" icon="rotate" href="/en/api/filings/13f-by-ticker">
    Reverse direction — which Top 1000 managers hold this ticker?
  </Card>

  <Card title="13F Top Managers" icon="ranking-star" href="/en/api/filings/13f-top-managers">
    Enumerate the covered Top 1000 manager set to build a fund pool.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# 13F Holders by Ticker
Source: https://docs.llmquantdata.com/en/api/filings/13f-by-ticker

Find which Top 1,000 institutional managers hold a given U.S. ticker for a given quarter — the reverse 13F lookup.

<Note icon="sparkles">
  **Available as MCP tool**: `sec_13f_list_ticker_holders` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit per call</Badge>

## What it does for your agent

`sec_13f_list_ticker_holders` is the **reverse direction** of the 13F smart-money lookup: given a U.S. ticker and a quarter, return the list of Top 1,000 institutional managers that held the ticker, with each holder's position size plus manager-level reportable value / scope rank. Use it to answer "who's behind this name?" — the position list is sorted by `value_usd` desc, and clients can derive a top-N-by-AUM-proxy holder cohort locally.

This tool is **not semantic search**: it's parameterized lookup by `(ticker, period)`. Coverage is restricted to the **requested quarter's top 1,000 managers** (an AUM-proxy ranking; each quarter has its own top 1,000) — the result is not the full set of 13F filers holding the ticker.

## Response

<ResponseField name="data" type="TickerHoldersResult">
  <Expandable title="TickerHoldersResult fields">
    <ResponseField name="ticker" type="string">Normalized ticker (e.g. `BRK.B → BRK-B`).</ResponseField>
    <ResponseField name="ranking_period" type="string">Quarter-end this snapshot reflects (`YYYY-MM-DD`); equals the quarter-end matching your `(year, quarter)` input.</ResponseField>

    <ResponseField name="total_holders_in_scope" type="integer">
      Number of Top 1000 managers that held the ticker (≤ 1000). Use this to size the cohort before iterating.
    </ResponseField>

    <ResponseField name="aggregate_value_usd" type="number">
      Sum of `value_usd` across all in-scope holders.
    </ResponseField>

    <ResponseField name="holders" type="HolderEntry[]">
      Sorted by `value_usd` descending.

      <Expandable title="HolderEntry fields">
        <ResponseField name="manager_cik" type="string">Holder CIK.</ResponseField>
        <ResponseField name="manager_name" type="string">Canonical manager name.</ResponseField>
        <ResponseField name="manager_period_reportable_value_usd" type="number">Manager's 13F reportable value (AUM proxy) for `ranking_period`. **Null when ranking data is not yet available for that quarter** — the holding is still returned, only the ranking value is missing.</ResponseField>
        <ResponseField name="manager_period_of_report" type="string">Period of the manager's reportable value; null when ranking is missing.</ResponseField>
        <ResponseField name="manager_period_rank" type="integer">Manager's rank within the Top 1000 manager set for `ranking_period`; null when ranking is missing.</ResponseField>
        <ResponseField name="accession_number" type="string">SEC accession number.</ResponseField>
        <ResponseField name="cusip" type="string">CUSIP of the position.</ResponseField>
        <ResponseField name="title_of_class" type="string">Security class.</ResponseField>
        <ResponseField name="value_usd" type="number">Position market value in USD.</ResponseField>
        <ResponseField name="shares" type="number">Number of shares.</ResponseField>
        <ResponseField name="shares_type" type="string">`SH` or `PRN`.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed (always `1`).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Credits left after this call.</ResponseField>
<ResponseField name="meta.notice" type="string">Plain-English coverage note, when the response needs one.</ResponseField>

```json title="200 OK · sec_13f_list_ticker_holders" expandable theme={null}
{
  "data": {
    "ticker": "NVDA",
    "ranking_period": "2025-12-31",
    "total_holders_in_scope": 187,
    "aggregate_value_usd": 123456789000,
    "holders": [
      {
        "manager_cik": "1067983",
        "manager_name": "BERKSHIRE HATHAWAY INC",
        "manager_period_reportable_value_usd": 302459211458,
        "manager_period_of_report": "2025-12-31",
        "manager_period_rank": 7,
        "accession_number": "0000950123-26-001234",
        "cusip": "67066G104",
        "title_of_class": "COM",
        "value_usd": 1234567890,
        "shares": 9000000,
        "shares_type": "SH"
      }
    ]
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 999,
    "notice": "Holders list is restricted to the Top 1,000 manager set; not full-market ownership. 13F coverage: Top 1,000 managers for quarter 2025-12-31 (each quarter has its own Top 1,000). Ranking data available for 4 quarters: 2025-03-31 … 2025-12-31. Reportable value is an AUM proxy excluding fixed income, options, non-U.S. holdings, and shorts."
  }
}
```

## Notes

<Tip>
  **Canonical workflow**: pair this reverse lookup with `sec_13f_list_top_managers` (to size the covered manager set) and `sec_13f_list_manager_holdings` (to drill into a specific holder's full book). This tool answers "who holds X?"; the manager-direction tool answers "what does this fund hold?".
</Tip>

<Tip>
  Use `manager_period_rank` and `manager_period_reportable_value_usd` to filter holders client-side — e.g. only display the Top 30 managers among holders to avoid surfacing tiny long-tail positions.
</Tip>

<Tip>
  **Typical agent queries**: this tool returns a single-quarter holder list only; quarter-over-quarter comparisons require the agent to call it twice and diff locally.

  <Prompt description="Single-quarter holders for one ticker">
    Show me NVDA's smart-money holders in the latest 13F quarter — top 20 by position size.
  </Prompt>

  <Prompt description="Quarter-over-quarter holder change for one ticker">
    Compare NVDA's smart-money holders between the latest two quarters — who newly entered, who exited, and who added the most to their position?
  </Prompt>

  Coverage is the requested quarter's Top 1000 covered manager set only, not full-market ownership; a manager's quarter-to-quarter visibility change may also reflect "dropped out of that quarter's Top 1000" rather than truly "exited the stock". Agents should keep this caveat in mind.
</Tip>

<Warning>
  **Top 1,000 manager scope only.** This is **not** full-market ownership. Funds outside the requested quarter's covered manager set (and all retail / direct holders) are excluded.
</Warning>

<Warning>
  If no Top 1,000 manager in the requested quarter held the ticker, the tool returns `200 OK` with empty `holders` plus `meta.notice`.
</Warning>

<Warning>
  Confidential / delayed-disclosure holdings are not exposed.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_ticker_holders",
        "arguments": { "ticker": "NVDA", "year": 2025, "quarter": 4, "limit": 100 }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/filings/13f/by-ticker",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"ticker": "NVDA", "year": 2025, "quarter": 4, "limit": 50},
    ).json()
    data = resp["data"]
    print(f"{data['ticker']} {data['ranking_period']}: {data['total_holders_in_scope']} holders")
    for h in data["holders"][:10]:
        print(f"  #{h['manager_period_rank']:>4}  {h['manager_name']:<40}  ${h['value_usd']:>15,}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/filings/13f/by-ticker?ticker=NVDA&year=2025&quarter=4&limit=50" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="sec_13f_list_ticker_holders — request parameters" icon="sliders">
  <ParamField type="string">
    U.S. equity ticker (e.g. `NVDA`, `TSLA`, `AAPL`). Case-insensitive; the server normalizes `BRK.B → BRK-B`.
  </ParamField>

  <ParamField type="integer">
    Calendar year of the quarter to query (e.g. `2025`). Range `[2013, 2030]`. **Must be paired with `quarter`**; omit both for the most recent covered quarter.
  </ParamField>

  <ParamField type="integer">
    Calendar quarter `1-4` (Q1=Jan-Mar, Q4=Oct-Dec). **Must be paired with `year`**.
  </ParamField>

  <ParamField type="integer">
    Maximum holders to return. Default `100`. Max `1000` — use a high limit if the consumer wants the full Top 1000 holder list and will trim by manager AUM proxy client-side.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="13F Holdings by Manager" icon="briefcase" href="/en/api/filings/13f-by-manager">
    Forward direction — list a single fund's full holdings for one quarter.
  </Card>

  <Card title="13F Top Managers" icon="ranking-star" href="/en/api/filings/13f-top-managers">
    Enumerate the covered Top 1000 manager set to size or filter the holder cohort.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# 13F Top Managers
Source: https://docs.llmquantdata.com/en/api/filings/13f-top-managers

Enumerate any covered quarter's SEC Form 13F Top 1,000 manager set ranked by reportable value — each quarter has its own Top 1,000; quarter-over-quarter roster and rank diffs supported.

<Note icon="sparkles">
  **Available as MCP tool**: `sec_13f_list_top_managers` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · ranked list</Badge>

## What it does for your agent

`sec_13f_list_top_managers` enumerates the requested quarter's SEC Form 13F Top 1,000 manager set ranked by 13F reportable value — rank `1` is the institution with the largest reportable value that quarter. Each quarter has its own Top 1,000, so an older quarter's result stays stable when a newer quarter is released. Use it to build a fund pool when an agent doesn't yet know a specific `manager_cik` or `ticker`: derive the Top N (e.g. 30) here, then fan out to `sec_13f_list_manager_holdings` to pull each manager's holdings for consensus / overlap / Q-over-Q rank-diff analyses.

### Two quarter fields — they point to the same quarter

* **`manager_set_period`** — the quarter whose Top 1,000 manager set this response covers. **Equal to the quarter you query** (`year + quarter`); defaults to the most recent covered quarter when you omit both.
* **`ranking_period`** — the quarter the response's ranks and values are computed from. **Equal to `manager_set_period`** — each quarter is served from its own Top 1,000.

Query a different `(year, quarter)` to get that quarter's own roster; rosters change across quarters as managers move in and out, and an older quarter's roster stays stable when a newer quarter is released. Passing a `(year, quarter)` outside the covered range returns 200 OK with an empty `managers` array plus an explanatory `meta.notice`.

## Response

<ResponseField name="data" type="TopManagersResult">
  <Expandable title="TopManagersResult fields">
    <ResponseField name="manager_set_period" type="string">
      Quarter (YYYY-MM-DD) whose Top 1,000 manager set this response covers; equals the quarter you query (or the most recent covered quarter when you omit `year`/`quarter`), and equals `ranking_period`.
    </ResponseField>

    <ResponseField name="ranking_period" type="string">
      Quarter (YYYY-MM-DD) the ranks and values in this response were computed from; equals `manager_set_period`.
    </ResponseField>

    <ResponseField name="managers" type="TopManager[]">
      Managers sorted by `period_rank` ascending.

      <Expandable title="TopManager fields">
        <ResponseField name="manager_cik" type="string">SEC CIK.</ResponseField>
        <ResponseField name="manager_name" type="string">Canonical manager name.</ResponseField>

        <ResponseField name="aliases" type="string[]">
          Known aliases / DBA names (may be empty). Useful for matching natural-language manager mentions to a `manager_cik`.
        </ResponseField>

        <ResponseField name="period_rank" type="integer">
          Rank within the covered Top 1,000 manager set for `ranking_period` (`1` = largest reportable value that quarter).
        </ResponseField>

        <ResponseField name="period_reportable_value_usd" type="number">
          13F reportable value (USD) for `ranking_period`. **AUM proxy, not true firmwide AUM** — excludes fixed income, options, non-U.S. holdings, shorts.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — this endpoint is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Credits left after this call.</ResponseField>

<ResponseField name="meta.notice" type="string">
  Plain-English coverage note; extended with "has no ranking data" when a `(year, quarter)` outside the covered range is requested.
</ResponseField>

```json title="200 OK · sec_13f_list_top_managers" expandable theme={null}
{
  "data": {
    "manager_set_period": "2025-12-31",
    "ranking_period": "2025-12-31",
    "managers": [
      {
        "manager_cik": "0001364742",
        "manager_name": "BLACKROCK INC.",
        "aliases": ["BLACKROCK", "BLACKROCK FUND ADVISORS"],
        "period_rank": 1,
        "period_reportable_value_usd": 4521893245678
      },
      {
        "manager_cik": "0000102909",
        "manager_name": "VANGUARD GROUP INC",
        "aliases": ["VANGUARD"],
        "period_rank": 2,
        "period_reportable_value_usd": 4123456789012
      }
    ]
  },
  "meta": {
    "creditsUsed": 0,
    "remainingCredits": 999,
    "notice": "13F coverage: Top 1,000 managers for quarter 2025-12-31 (each quarter has its own Top 1,000). Ranking data available for 4 quarters: 2025-03-31 … 2025-12-31. Reportable value is an AUM proxy excluding fixed income, options, non-U.S. holdings, and shorts."
  }
}
```

## Notes

<Tip>
  **Canonical workflow — Smart Money Consensus pool**:

  1. `sec_13f_list_top_managers?limit=30` — pick the Top 30 fund pool.
  2. Loop each `manager_cik` into `sec_13f_list_manager_holdings` to fetch holdings.
  3. Aggregate client-side to build a consensus / overlap leaderboard.

  Holdings are **not** included in this response — fan-out is required.
</Tip>

<Tip>
  **Typical agent queries**: each quarter has its own Top 1,000 and rankings are computed per quarter — the agent can decide how many times to call the tool and which quarters to compare.

  <Prompt description="Top 30 smart money roster quarter-over-quarter">
    Compare the Top 30 13F smart-money managers between the latest quarter and the prior quarter — who entered, who fell out, and who moved the most in rank?
  </Prompt>

  <Prompt description="Top N fund pool for a specific quarter">
    Give me the top 30 institutions by 13F reportable value for 2025 Q4, ranked descending.
  </Prompt>
</Tip>

<Tip>
  Use `aliases` to match natural-language manager mentions ("BlackRock", "Vanguard") to the canonical `manager_cik` before calling `sec_13f_list_manager_holdings`. Saves a round trip through the `manager_name` resolver.
</Tip>

<Warning>
  **Each quarter has its own Top 1,000 manager set**: passing a different `(year, quarter)` returns that quarter's own roster — managers move in and out across quarters, so a roster diff is meaningful. A manager appears in the response for every quarter it was inside that quarter's Top 1,000, and an older quarter's roster stays stable when a newer quarter is released.
</Warning>

<Warning>
  **Top 1,000 only**, ranked by 13F reportable value (an AUM proxy, **not** true AUM). Excludes fixed income, options, non-U.S. holdings, shorts.
</Warning>

<Warning>
  This is **not** a semantic / keyword search — there is no free-text manager filter. For natural-language manager lookups, call `sec_13f_list_manager_holdings` with `manager_name`.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Latest-quarter Top 30 fund pool
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_top_managers",
        "arguments": { "limit": 30 }
      }
    }

    // 2) Previous-quarter Top 30 — for roster diff
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_top_managers",
        "arguments": { "limit": 30, "year": 2025, "quarter": 3 }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # Latest-quarter Top 30
    latest = requests.get(
        f"{base}/api/filings/13f/managers",
        headers=headers,
        params={"limit": 30},
    ).json()["data"]["managers"]

    # Specific quarter
    prev = requests.get(
        f"{base}/api/filings/13f/managers",
        headers=headers,
        params={"limit": 30, "year": 2025, "quarter": 3},
    ).json()["data"]["managers"]
    ```

    ```bash cURL theme={null}
    # Latest-quarter Top 30
    curl "https://api.llmquantdata.com/api/filings/13f/managers?limit=30" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # Specific quarter
    curl "https://api.llmquantdata.com/api/filings/13f/managers?limit=30&year=2025&quarter=3" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="sec_13f_list_top_managers — request parameters" icon="sliders">
  <ParamField type="integer">
    Number of managers to return, sorted by `period_rank` ascending. Default `30`. Range `[1, 1000]`; server clamps out-of-range values.
  </ParamField>

  <ParamField type="integer">
    Calendar year of the quarter to query (e.g. `2025`). Range `[2013, 2030]`. **Must be paired with `quarter`**; omit both for the most recent quarter the data covers.
  </ParamField>

  <ParamField type="integer">
    Calendar quarter `1-4` (Q1=Jan-Mar, Q4=Oct-Dec). **Must be paired with `year`**.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="13F Holdings by Manager" icon="briefcase" href="/en/api/filings/13f-by-manager">
    Forward direction — fetch one fund's full holdings (the natural fan-out from this tool).
  </Card>

  <Card title="13F Holders by Ticker" icon="rotate" href="/en/api/filings/13f-by-ticker">
    Reverse direction — which Top 1000 managers hold a given ticker?
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# SEC Filing Browse
Source: https://docs.llmquantdata.com/en/api/filings/browse

List SEC 10-K / 10-Q / 8-K filing metadata for a U.S. ticker — the discovery half of the progressive-disclosure pattern.

<Note icon="sparkles">
  **Available as MCP tool**: `sec_filing_browse` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · listing</Badge>

## What it does for your agent

`sec_filing_browse` is the **first step** in SEC Filing's progressive-disclosure pattern: given a U.S. ticker, it returns the metadata list of available 10-K / 10-Q / 8-K filings (no section text). Use it to discover what filings exist for a company, then call `sec_filing_read` to fetch the actual section content — by `year` / `quarter` for 10-K / 10-Q, or by `accession_number` for 8-K (event-driven, many per year). Every filing also carries `section_keys` — the section codes available for it — so an agent can tell what an 8-K is about before reading a single line.

Browse is **not semantic search**: it accepts only a ticker + optional `filing_type` filter. No keyword matching, no relevance ranking, no natural-language queries.

## Response

<ResponseField name="data" type="Filing[]">
  Array of SEC filings sorted by `filing_date` descending.

  <Expandable title="Filing fields">
    <ResponseField name="sec_filing_id" type="string">
      Stable LLMQuant filing id. Consistent across requests.
    </ResponseField>

    <ResponseField name="ticker" type="string">
      The ticker symbol (uppercased).
    </ResponseField>

    <ResponseField name="company_name" type="string">
      Company name as filed with the SEC.
    </ResponseField>

    <ResponseField name="filing_type" type="string">
      Filing type — `10-K`, `10-Q`, or `8-K`.
    </ResponseField>

    <ResponseField name="accession_number" type="string">
      SEC accession number (e.g. `0000320193-25-000079`). **Pass this to `sec_filing_read` to target the exact filing.**
    </ResponseField>

    <ResponseField name="filing_date" type="string">
      Date the filing was submitted to the SEC (`YYYY-MM-DD`).
    </ResponseField>

    <ResponseField name="report_date" type="string">
      The reporting period covered by the filing (`YYYY-MM-DD`). Null when SEC does not report it.
    </ResponseField>

    <ResponseField name="url" type="string">
      Canonical SEC EDGAR link.
    </ResponseField>

    <ResponseField name="section_keys" type="string[]">
      The sections you can read from this filing — e.g. 8-K `["item2.02","item9.01","ex99.1"]`, 10-K `["1","1A","7", …]`. An empty `[]` means none are listed yet. Pass any code to `sec_filing_read` to pull that section. The codes also tell you what an 8-K is: `item2.02` is earnings, `item5.02` an executive change — no need to open it first.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — browse is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · sec_filing_browse" expandable theme={null}
{
  "data": [
    {
      "sec_filing_id": "a1b2c3d4-...",
      "ticker": "AAPL",
      "company_name": "Apple Inc.",
      "filing_type": "10-K",
      "accession_number": "0000320193-25-000079",
      "filing_date": "2025-10-31",
      "report_date": "2025-09-27",
      "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm",
      "section_keys": ["1", "1A", "7", "7A", "8"]
    }
  ],
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## Notes

<Tip>
  **Two-step lookup is canonical** for SEC filings: `sec_filing_browse` returns the list of filings (free), then `sec_filing_read` extracts a specific section (1 credit). Pass the `accession_number` from browse straight into read for unambiguous targeting.
</Tip>

<Tip>
  Every filing carries `section_keys` — the section codes available for it. For 8-K (many per year, all named "8-K") this is how an agent picks the right one without reading it: `item2.02` = earnings, `item5.02` = executive change, `ex99.1` = press-release exhibit. Pass the codes you want straight into `sec_filing_read`'s `items`.
</Tip>

<Tip>
  Published filings never change, so a result stays valid for good. The first lookup for a ticker may take a moment; every repeat is instant.
</Tip>

<Warning>
  **10-K, 10-Q, and 8-K supported.** 20-F and proxy (DEF 14A) filings are not currently supported.
</Warning>

<Warning>
  **No date-range filter** (`filed_at_gte` / `filed_at_lte`) and **no CIK lookup**. Only `ticker` (+ optional `filing_type`) is accepted.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "sec_filing_browse",
        "arguments": { "ticker": "AAPL", "filing_type": "10-K", "limit": 10 }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/filings",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"ticker": "AAPL", "filing_type": "10-K", "limit": 10},
    ).json()
    for f in resp["data"]:
        print(f"{f['filing_type']}  {f['filing_date']}  {f['accession_number']}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/filings?ticker=AAPL&filing_type=10-K&limit=10" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="sec_filing_browse — request parameters" icon="sliders">
  <ParamField type="string">
    U.S. equity ticker (e.g. `AAPL`, `MSFT`, `BRK.B`).
  </ParamField>

  <ParamField type="string">
    Filter by filing type. Allowed values: `10-K`, `10-Q`, `8-K`. Omit to return all.
  </ParamField>

  <ParamField type="integer">
    Maximum filings to return. Default `10`. Max `50`.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="SEC Filing Read" icon="file-lines" href="/en/api/filings/read">
    Step 2 of progressive disclosure — fetch the full text of one item from a specific filing.
  </Card>

  <Card title="13F Top Managers" icon="ranking-star" href="/en/api/filings/13f-top-managers">
    Enumerate any covered quarter's Top 1,000 manager set to kick off consensus analyses.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# SEC Filing Read
Source: https://docs.llmquantdata.com/en/api/filings/read

Extract the full text of a specific item from a SEC 10-K, 10-Q, or 8-K filing — the read half of the progressive-disclosure pattern.

<Note icon="sparkles">
  **Available as MCP tool**: `sec_filing_read` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit per call</Badge>

## What it does for your agent

`sec_filing_read` is the **second step** in SEC Filing's progressive-disclosure pattern: after `sec_filing_browse` returns the list of filings for a ticker, use this tool to extract the full text of a specific item (Risk Factors, MD\&A, Financial Statements, earnings press releases, etc.). Pass either `accession_number` (recommended after browse, and **required for 8-K**) or `year` / `quarter` plus the section code(s), and the response carries the section text plus a manifest of the filing's other sections. Pass `items` (an array) to pull several sections in one call — still 1 credit — and a requested code the filing doesn't have is simply dropped from the result rather than erroring.

`sec_filing_read` is **not semantic search**: it performs parameterized lookup by `(ticker, filing_type, accession_number OR year[+quarter], item)` and returns the exact section text — no relevance ranking, no fuzzy matching.

## Response

<ResponseField name="data" type="FilingReadResult">
  <Expandable title="FilingReadResult fields">
    <ResponseField name="ticker" type="string">The ticker symbol.</ResponseField>
    <ResponseField name="filing_type" type="string">Filing type — `10-K`, `10-Q`, or `8-K`.</ResponseField>
    <ResponseField name="accession_number" type="string">SEC accession number of the matched filing.</ResponseField>
    <ResponseField name="year" type="integer">Calendar year of `period_of_report` (`null` for 8-K — event-driven, no period).</ResponseField>
    <ResponseField name="quarter" type="integer">Quarter of `period_of_report` (1-4 for 10-Q; `null` for 10-K and 8-K).</ResponseField>

    <ResponseField name="available_sections" type="SectionManifest[]">
      Manifest of every extractable section in this filing — use this to discover what else you could read.

      <Expandable title="SectionManifest fields">
        <ResponseField name="section_key" type="string">Item code (`1`, `1A`, `7`, `part1item2`, `item2.02` …).</ResponseField>
        <ResponseField name="section_title" type="string">Section name (`Business`, `Risk Factors` …).</ResponseField>
        <ResponseField name="ordinal" type="integer">Display order within the filing.</ResponseField>
        <ResponseField name="char_count" type="integer">Character count, or `0` if the section has not been read yet.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="items" type="Item[]">
      Extracted section content for the requested `items` (or every section when none are specified). Codes absent from the filing are omitted here — cross-check `available_sections`.

      <Expandable title="Item fields">
        <ResponseField name="number" type="string">Item code (e.g. `1A`, `part1item2`).</ResponseField>
        <ResponseField name="name" type="string">Section name (e.g. `Risk Factors`, `MD&A`).</ResponseField>
        <ResponseField name="text" type="string">Plain-text section body extracted from the filing.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed (always `1`).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · sec_filing_read" expandable theme={null}
{
  "data": {
    "ticker": "NVDA",
    "filing_type": "10-K",
    "accession_number": "0001045810-26-000021",
    "year": 2025,
    "quarter": null,
    "available_sections": [
      { "section_key": "1", "section_title": "Business", "ordinal": 1, "char_count": 48578 },
      { "section_key": "1A", "section_title": "Risk Factors", "ordinal": 2, "char_count": 32100 },
      { "section_key": "7", "section_title": "MD&A", "ordinal": 10, "char_count": 25400 }
    ],
    "items": [
      {
        "number": "1A",
        "name": "Risk Factors",
        "text": "Item 1A. Risk Factors\n\nOur business, financial condition and operating results may be materially affected by..."
      }
    ]
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

## Notes

<Tip>
  **Two-step lookup is canonical**: call `sec_filing_browse` first (free) to get the list of filings, grab the `accession_number` you want, then call `sec_filing_read` (1 credit) with that accession + a specific `item`. This avoids ambiguity around `period_of_report` vs `filed_at` years for 10-Q.
</Tip>

<Tip>
  Inspect `available_sections[i].char_count` before pulling more sections — long items (Risk Factors, MD\&A) can be tens of thousands of characters. Read one section per call to keep agent context small.
</Tip>

<Tip>
  Need several sections from one filing? Pass `items` (e.g. `["item2.02","item9.01"]`) to fetch them in a single call — still 1 credit — and skip pulling large exhibits you didn't ask for.
</Tip>

<Warning>
  **10-K, 10-Q, and 8-K use different item code systems** — see the parameter reference below. Mixing them returns `400`.
</Warning>

<Warning>
  **Missing codes are dropped, not errored.** A format-valid `item` / `items` code the filing doesn't contain is omitted from the result (check `available_sections` for what exists). The call returns `400` only when *none* of the requested codes can be returned; a malformed code (wrong system for the filing type) still returns `400`.
</Warning>

<Warning>
  For 10-Q, **`year` alone is not enough** — you must pass either `year + quarter`, or `accession_number`. `year` for 10-Q without `quarter` returns `400`.
</Warning>

<Warning>
  **8-K must be located by `accession_number`.** It is event-driven (many filings per year), so `year` / `quarter` cannot identify one — browse first, then read by `accession_number`. Passing `year` or `quarter` for 8-K returns `400`.
</Warning>

<Warning>
  Plain-text output only. HTML / structured tables are not exposed by this tool. Very recently filed reports may take a moment to become available while they are processed.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Browse to get the list of filings
    {
      "method": "tools/call",
      "params": {
        "name": "sec_filing_browse",
        "arguments": { "ticker": "NVDA", "filing_type": "10-K", "limit": 5 }
      }
    }

    // 2) Read Risk Factors + MD&A (items 1A, 7) from the latest 10-K in one call
    {
      "method": "tools/call",
      "params": {
        "name": "sec_filing_read",
        "arguments": {
          "ticker": "NVDA",
          "filing_type": "10-K",
          "accession_number": "0001045810-26-000021",
          "items": ["1A", "7"]
        }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) Browse
    filings = requests.get(
        f"{base}/api/filings",
        headers=headers,
        params={"ticker": "NVDA", "filing_type": "10-K", "limit": 5},
    ).json()["data"]

    # 2) Read items 1A + 7 from the most recent 10-K in one call
    latest = filings[0]
    resp = requests.get(
        f"{base}/api/filings/sections",
        headers=headers,
        params={
            "ticker": "NVDA",
            "filing_type": "10-K",
            "accession_number": latest["accession_number"],
            "items": "1A,7",
        },
    ).json()
    print(resp["data"]["items"][0]["text"][:500])
    ```

    ```bash cURL theme={null}
    # 1) Browse
    curl "https://api.llmquantdata.com/api/filings?ticker=NVDA&filing_type=10-K&limit=5" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2) Read items 1A + 7 in one call
    curl "https://api.llmquantdata.com/api/filings/sections?ticker=NVDA&filing_type=10-K&accession_number=0001045810-26-000021&items=1A,7" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="sec_filing_read — request parameters" icon="sliders">
  <ParamField type="string">
    U.S. equity ticker (e.g. `AAPL`, `NVDA`, `META`).
  </ParamField>

  <ParamField type="string">
    Filing type — `10-K`, `10-Q`, or `8-K`.
  </ParamField>

  <ParamField type="integer">
    Calendar year of `period_of_report`. **Required** for 10-K when `accession_number` is omitted; required together with `quarter` for 10-Q when `accession_number` is omitted. Not used for 8-K (locate by `accession_number`).
  </ParamField>

  <ParamField type="integer">
    Quarter of `period_of_report` (1-4). Only valid for 10-Q (rejected for 10-K and 8-K). Required when looking up a 10-Q by `year` (without `accession_number`).
  </ParamField>

  <ParamField type="string[]">
    Fetch several sections in one call. Over HTTP, comma-separate them (`items=item2.02,item9.01`); for the MCP tool, pass an array. The codes are the same as `item` below. Up to 25 per call, duplicates removed, still 1 credit. A code this filing doesn't have is skipped; you only get a `400` when none of them match. Omit to return every section.
  </ParamField>

  <ParamField type="string">
    Singular alias for `items` (HTTP only; the MCP tool exposes only `items`) — equivalent to `items=[<item>]`. Omit to return every extractable section.

    **10-K item codes:** `1`, `1A`, `1B`, `1C`, `2`, `3`, `4`, `5`, `6`, `7`, `7A`, `8`, `9`, `9A`, `9B`, `10`, `11`, `12`, `13`, `14`, `15`.

    **10-Q item codes:** `part1item1`, `part1item2`, `part1item3`, `part1item4`, `part2item1`, `part2item1a`, `part2item2`, `part2item3`, `part2item4`, `part2item5`, `part2item6`.

    **8-K item codes:** vary per filing (event-driven) — e.g. `item2.02` (earnings / Results of Operations), `item5.02` (executive changes), `item1.01` (material agreement), `item8.01` (other events), plus exhibits like `ex99.1` (press release). Read `available_sections` from any response to see the exact set a given 8-K contains.

    Common picks: 10-K `1` (Business) · `1A` (Risk Factors) · `7` (MD\&A) · `8` (Financial Statements) · `10` (Directors / Officers); 10-Q `part1item1` (Financial Statements) · `part1item2` (MD\&A) · `part2item1a` (Risk Factors).
  </ParamField>

  <ParamField type="string">
    Exact SEC accession number (e.g. `0001045810-26-000021`). Recommended after `sec_filing_browse`, and **required for 8-K**. Cannot be combined with `year` or `quarter`.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="SEC Filing Browse" icon="folder-open" href="/en/api/filings/browse">
    Step 1 — list available filings for a ticker before calling read.
  </Card>

  <Card title="13F Holdings by Manager" icon="briefcase" href="/en/api/filings/13f-by-manager">
    Institutional ownership data — a different SEC filing family (Form 13F).
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# Paper Search
Source: https://docs.llmquantdata.com/en/api/knowledge/paper-search

Semantic search over the LLMQuant Quant Paper corpus — find research papers, then load specific sections on demand.

<Note icon="sparkles">
  **Available as MCP tools**: `paper_search` + `paper_read` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit · search</Badge>
 
<Badge>free · read</Badge>

## What it does for your agent

`paper_search` returns the most relevant Quant Paper knowledge cards for a natural-language query — research on factors, anomalies, microstructure, ML for finance, and more. Use it as a **literature entry point**: when an agent needs to ground a claim in academic work ("is the momentum crash effect real?", "what does the factor zoo paper actually say?"), call `paper_search` to surface candidate `paperCardId`s + `availableSections`, then `paper_read` to load the exact sections that answer the question.

The vectors are built from `title + abstract + summary + tags`, so a card-level hit is a green light to call `paper_read` for sections — `paper_search` deliberately does **not** return full text.

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: paper_search(query, limit=5)
  MCP-->>Agent: items[] · paperCardId · summary · availableSections
  Note over Agent: scan summaries + section manifest
  alt summary is enough
    Agent->>Agent: answer from summary + tags
  else need specific sections
    Agent->>MCP: paper_read(paperCardId, sections=[keys])
    MCP-->>Agent: sections[].content (Markdown)
  else need full paper
    Agent->>MCP: paper_read(paperCardId, sections=["all"])
    MCP-->>Agent: full sections[] in order
  end
```

## Response

### `paper_search` response

<ResponseField name="data" type="PaperCard[]">
  Ranked array of paper cards (highest relevance first).

  <Expandable title="PaperCard fields">
    <ResponseField name="paperCardId" type="string">
      Stable identifier. Pass to `paper_read` to load section content.
    </ResponseField>

    <ResponseField name="sourcePaperId" type="string">
      Identifier from the original source (e.g. arXiv ID).
    </ResponseField>

    <ResponseField name="title" type="string">
      Paper title.
    </ResponseField>

    <ResponseField name="authors" type="string[]">
      List of paper authors.
    </ResponseField>

    <ResponseField name="abstract" type="string">
      Original abstract of the paper.
    </ResponseField>

    <ResponseField name="summary" type="string">
      LLM-generated 2–3 sentence summary. **Use this to decide whether to spend a `paper_read` call** on full sections.
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      Research topic tags (e.g. `factor`, `momentum`, `deep-learning`).
    </ResponseField>

    <ResponseField name="availableSections" type="object[]">
      Section manifest. Each entry has `section_key`, `section_type`, `title`, `char_count`, `section_order`. Use the `section_key` values when calling `paper_read`.
    </ResponseField>

    <ResponseField name="sectionCount" type="number">
      Total number of available sections.
    </ResponseField>

    <ResponseField name="fullTextCharCount" type="number">
      Total character count across all sections.
    </ResponseField>

    <ResponseField name="pdfUrl" type="string">
      Direct URL to the paper PDF.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed by this call (always `1` for search).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · paper_search" expandable theme={null}
{
  "data": [
    {
      "paperCardId": "card_abc123",
      "sourcePaperId": "arxiv:1404.4944",
      "title": "Momentum Crashes",
      "authors": ["Kent Daniel", "Tobias J. Moskowitz"],
      "abstract": "Despite their strong positive abnormal returns, momentum strategies experience infrequent but severe crashes...",
      "summary": "Documents that momentum portfolios crash following bear-market rebounds. The crashes are forecastable in real time using market-state and volatility variables.",
      "tags": ["factor", "momentum", "crash"],
      "availableSections": [
        { "section_key": "introduction", "section_type": "introduction", "title": "Introduction", "char_count": 18420, "section_order": 1 },
        { "section_key": "methodology", "section_type": "method", "title": "Methodology", "char_count": 22150, "section_order": 2 }
      ],
      "sectionCount": 6,
      "fullTextCharCount": 102345,
      "pdfUrl": "https://arxiv.org/pdf/1404.4944"
    }
  ],
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

### `paper_read` response

<ResponseField name="data" type="PaperReadResult">
  The selected sections of one paper card.

  <Expandable title="PaperReadResult fields">
    <ResponseField name="paperCardId" type="string">Stable identifier.</ResponseField>
    <ResponseField name="sourcePaperId" type="string">Identifier from the original source.</ResponseField>
    <ResponseField name="title" type="string">Paper title.</ResponseField>
    <ResponseField name="authors" type="string[]">List of paper authors.</ResponseField>
    <ResponseField name="abstract" type="string">Original abstract.</ResponseField>
    <ResponseField name="summary" type="string">LLM summary.</ResponseField>
    <ResponseField name="tags" type="string[]">Topic tags.</ResponseField>
    <ResponseField name="pdfUrl" type="string">Direct URL to the paper PDF.</ResponseField>

    <ResponseField name="availableSections" type="object[]">
      Section manifest (same shape as in `paper_search`).
    </ResponseField>

    <ResponseField name="sectionCount" type="number">Total number of available sections.</ResponseField>
    <ResponseField name="fullTextCharCount" type="number">Total character count across all sections.</ResponseField>

    <ResponseField name="sections" type="object[]">
      The requested sections, in `section_order`. Each entry has `section_key`, `section_type`, `title`, `content` (Markdown), `char_count`, `section_order`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for read.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

## Notes

<Tip>
  **Two-step lookup is canonical**: `paper_search` returns IDs + summaries + section manifest cheaply (1 credit), then `paper_read` loads only the section(s) you actually need (free). Read top-1's `introduction` + `methodology` first; pull more sections only when you need to verify a specific claim.
</Tip>

<Tip>
  Decide which sections to read **before** calling `paper_read` by inspecting `availableSections[i].char_count` from `paper_search`. Avoid `["all"]` for long papers — pull 1-2 targeted sections to keep agent context small.
</Tip>

<Warning>
  Queries longer than **2,000 characters** are rejected with `400`. Summarize long agent context before calling.
</Warning>

<Warning>
  `limit` must be between **1** and **10** for `paper_search`; values outside that range return `400`.
</Warning>

<Warning>
  `paper_search` returns **card-level metadata only** — no full text. To get section content, you must call `paper_read`.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Search
    {
      "method": "tools/call",
      "params": {
        "name": "paper_search",
        "arguments": { "query": "momentum crash", "limit": 5 }
      }
    }

    // 2) Read targeted sections from the top hit
    {
      "method": "tools/call",
      "params": {
        "name": "paper_read",
        "arguments": {
          "paperCardId": "card_abc123",
          "sections": ["introduction", "methodology"]
        }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {
        "Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}",
        "Content-Type": "application/json",
    }

    # 1) Search
    hits = requests.post(
        f"{base}/api/paper/search",
        headers=headers,
        json={"query": "momentum crash", "limit": 5},
    ).json()["data"]

    # 2) Read targeted sections from the top hit
    top = hits[0]
    paper = requests.post(
        f"{base}/api/paper/read",
        headers=headers,
        json={
            "paperCardId": top["paperCardId"],
            "sections": ["introduction", "methodology"],
        },
    ).json()["data"]

    for section in paper["sections"]:
        print(f"## {section['title']} ({section['char_count']} chars)")
        print(section["content"][:500])
    ```

    ```bash cURL theme={null}
    # 1) Search
    curl -X POST "https://api.llmquantdata.com/api/paper/search" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "momentum crash", "limit": 5}'

    # 2) Read targeted sections
    curl -X POST "https://api.llmquantdata.com/api/paper/read" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"paperCardId": "card_abc123", "sections": ["introduction", "methodology"]}'
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<AccordionGroup>
  <Accordion title="paper_search — request parameters" icon="magnifying-glass">
    <ParamField type="string">
      Natural-language search query. Max 2,000 characters.
    </ParamField>

    <ParamField type="number">
      Maximum results to return. Range `1–10`.
    </ParamField>
  </Accordion>

  <Accordion title="paper_read — request parameters" icon="book-open">
    <ParamField type="string">
      The `paperCardId` returned by `paper_search`.
    </ParamField>

    <ParamField type="string[]">
      Section keys from `availableSections[].section_key`. Pass `["all"]` (the default when omitted) to read every section.
    </ParamField>
  </Accordion>
</AccordionGroup>

## Related

<Columns>
  <Card title="Wiki Search" icon="book" href="/en/api/knowledge/wiki-search">
    Same two-step pattern over the curated Quant Wiki corpus (concepts, formulas, factors).
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# Wiki Search
Source: https://docs.llmquantdata.com/en/api/knowledge/wiki-search

Semantic search over the LLMQuant Quant Wiki — find concepts, formulas, factors, and strategies for your agent.

<Note icon="sparkles">
  **Available as MCP tools**: `wiki_search` + `wiki_read` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit · search</Badge>
 
<Badge>free · read</Badge>

## What it does for your agent

`wiki_search` returns the most relevant Quant Wiki entries for a natural-language query — concepts, formulas, factors, and strategies. Use it as a **research entry point**: when an agent encounters a finance term mid-task ("what's the Black-Scholes assumption?", "explain pairs trading"), call `wiki_search` first to locate the right `wikiItemId`s, then `wiki_read` to load the full markdown body.

The hybrid ranker blends semantic similarity with keyword matching — so terse jargon and verbose questions both retrieve well.

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: wiki_search(query, limit=5)
  MCP-->>Agent: items[] · wikiItemId · summary · scores
  Note over Agent: scan summaries
  alt summary is enough
    Agent->>Agent: answer from summary
  else need full text
    Agent->>MCP: wiki_read(wikiItemId, maxLength?)
    MCP-->>Agent: body_markdown
  end
```

## Response

### `wiki_search` response

<ResponseField name="data" type="WikiItem[]">
  Ranked array of wiki items (highest relevance first).

  <Expandable title="WikiItem fields">
    <ResponseField name="wikiItemId" type="string">
      Stable identifier. Pass to `wiki_read` for the full article.
    </ResponseField>

    <ResponseField name="slug" type="string">
      URL-friendly slug derived from the title.
    </ResponseField>

    <ResponseField name="title" type="string">
      Article title.
    </ResponseField>

    <ResponseField name="summary" type="string">
      LLM-generated 2–3 sentence summary. **Use this to decide whether to load the full article** before spending a `wiki_read`.
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      Topic tags (e.g. `equity`, `factor`, `derivatives`).
    </ResponseField>

    <ResponseField name="scores" type="object">
      Hybrid relevance scores. `combined` is the blended final score; `semantic` and `lexical` are the components (all 0–1).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed by this call (always `1` for search).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · wiki_search" expandable theme={null}
{
  "data": [
    {
      "wikiItemId": "11111111-1111-4111-8111-111111111111",
      "slug": "momentum-factor",
      "title": "Momentum Factor",
      "summary": "Momentum captures the tendency of recent winners to keep winning over horizons of 3–12 months. It is one of the canonical Fama-French factors and underpins many systematic equity strategies.",
      "tags": ["equity", "factor"],
      "scores": { "combined": 0.91, "semantic": 0.88, "lexical": 0.79 }
    }
  ],
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

### `wiki_read` response

<ResponseField name="data" type="WikiItem">
  The full wiki entry.

  <Expandable title="WikiItem fields">
    <ResponseField name="wikiItemId" type="string">Stable identifier.</ResponseField>
    <ResponseField name="title" type="string">Article title.</ResponseField>
    <ResponseField name="summary" type="string">2–3 sentence summary.</ResponseField>

    <ResponseField name="body_markdown" type="string">
      Full article body in Markdown. Truncated to `maxLength` characters if specified.
    </ResponseField>

    <ResponseField name="item_type" type="string">
      One of `concept`, `formula`, `strategy`, `factor`.
    </ResponseField>

    <ResponseField name="tags" type="string[]">Topic tags.</ResponseField>
    <ResponseField name="source_url" type="string">Canonical URL on `quant-wiki.com`.</ResponseField>
    <ResponseField name="updated_at" type="datetime">ISO-8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for read.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

## Notes

<Tip>
  **Two-step lookup is canonical**: search returns IDs + summaries cheaply (1 credit, multiple hits), then `wiki_read` loads only the article(s) the agent actually needs (free). Read top-1 by default; read top-2 only when summaries are ambiguous.
</Tip>

<Tip>
  Use `maxLength` on `wiki_read` to preview a long article before spending agent context tokens on the full body.
</Tip>

<Warning>
  Queries longer than **2,000 characters** are rejected with `400`. Truncate or summarize long agent context before calling.
</Warning>

<Warning>
  `limit` must be between **1** and **10** for `wiki_search`; values outside that range return `400`.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Search
    {
      "method": "tools/call",
      "params": {
        "name": "wiki_search",
        "arguments": { "query": "momentum factor", "limit": 5 }
      }
    }

    // 2) Read top hit
    {
      "method": "tools/call",
      "params": {
        "name": "wiki_read",
        "arguments": { "wikiItemId": "11111111-1111-4111-8111-111111111111", "maxLength": 1500 }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) Search
    hits = requests.post(
        f"{base}/api/wiki/search",
        headers=headers,
        json={"query": "momentum factor", "limit": 5},
    ).json()["data"]

    # 2) Read top hit
    top = requests.get(
        f"{base}/api/wiki/items/{hits[0]['wikiItemId']}",
        headers=headers,
        params={"max_length": 1500},
    ).json()["data"]
    print(top["body_markdown"])
    ```

    ```bash cURL theme={null}
    # 1) Search
    curl -X POST "https://api.llmquantdata.com/api/wiki/search" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "momentum factor", "limit": 5}'

    # 2) Read top hit (replace this sample UUID with wikiItemId from step 1)
    WIKI_ITEM_ID="11111111-1111-4111-8111-111111111111"
    curl "https://api.llmquantdata.com/api/wiki/items/${WIKI_ITEM_ID}?max_length=1500" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<AccordionGroup>
  <Accordion title="wiki_search — request parameters" icon="magnifying-glass">
    <ParamField type="string">
      Natural-language search query. Max 2,000 characters.
    </ParamField>

    <ParamField type="number">
      Maximum results to return. Range `1–10`.
    </ParamField>
  </Accordion>

  <Accordion title="wiki_read — request parameters" icon="book-open">
    <ParamField type="string">
      The `wikiItemId` returned by `wiki_search`.
    </ParamField>

    <ParamField type="number">
      Maximum character length for `body_markdown`. Useful for previewing long articles before consuming agent context.
    </ParamField>
  </Accordion>
</AccordionGroup>

## Related

<Columns>
  <Card title="Paper Search" icon="file-lines" href="/en/api/knowledge/paper-search">
    Same two-step pattern over the academic paper corpus.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# Macro Historical Observations
Source: https://docs.llmquantdata.com/en/api/macro/historical

Latest-vintage historical time series for a single U.S. macro indicator.

<Note icon="sparkles">
  **Available as MCP tools**: `macro_indicator_search` + `macro_indicator_history` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit · history</Badge>
 
<Badge>free · search</Badge>

## What it does for your agent

`macro_indicator_history` returns the **latest-vintage historical time series** for one supported U.S. macro indicator (CPI, UNRATE, Fed Funds, 10Y yield, GDP, etc.) — a list of `{ date, value, realtime_start, realtime_end }` observations. Use it as a **macro time-series fetcher** mid-task: when an agent needs to chart inflation over the last 5 years, compute a yield-curve slope, or feed observations into a downstream model.

The canonical agent flow is two-step: call `macro_indicator_search` first (free) to locate the right `indicator` alias, then `macro_indicator_history` to pull the series. Time boundaries are optional: use `start_date` and/or `end_date` to filter the candidate window, then `limit` and `take_from` choose which edge to keep. Results always return oldest first.

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: macro_indicator_search(query?, category?, frequency?)
  MCP-->>Agent: items[] · indicator · series_id · frequency · units
  Note over Agent: pick the right alias
  alt question is "what's the trend?"
    Agent->>MCP: macro_indicator_history(indicator, limit=60)
    MCP-->>Agent: observations[] · date · value · realtime_start
  else question is "beginning of a window"
    Agent->>MCP: macro_indicator_history(indicator, start_date, end_date, limit=12, take_from=earliest)
    MCP-->>Agent: observations[] · earliest 12 in window
  end
  Note over Agent: chart, compare, or feed downstream
```

## Response

<ResponseField name="data" type="MacroHistorical">
  Indicator metadata + observations array.

  <Expandable title="MacroHistorical fields">
    <ResponseField name="indicator" type="string">
      Stable platform alias echoed back (e.g. `us.cpi.headline`).
    </ResponseField>

    <ResponseField name="series_id" type="string">
      Raw series ID (e.g. `CPIAUCSL`).
    </ResponseField>

    <ResponseField name="title" type="string">
      Human-readable indicator title.
    </ResponseField>

    <ResponseField name="frequency" type="string">
      Native cadence: `Daily`, `Weekly`, `Monthly`, `Quarterly`, `Annual`.
    </ResponseField>

    <ResponseField name="units" type="string">
      Unit string (e.g. `Index 1982-1984=100`, `Percent`).
    </ResponseField>

    <ResponseField name="observations" type="MacroObservation[]">
      Time-ordered observations (oldest → newest).

      <Expandable title="MacroObservation fields">
        <ResponseField name="date" type="string">
          Observation period start (YYYY-MM-DD).
        </ResponseField>

        <ResponseField name="value" type="number">
          Reported value. `null` when the period is missing.
        </ResponseField>

        <ResponseField name="realtime_start" type="string">
          First date this value was published (YYYY-MM-DD). Use to detect revisions.
        </ResponseField>

        <ResponseField name="realtime_end" type="string">
          Last date this value remained current. Same as `realtime_start` for the latest vintage of an unchanged value.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="attribution" type="string">
      Required attribution string for display.
    </ResponseField>

    <ResponseField name="stale" type="boolean">
      `true` if the response uses older available data after a refresh failed.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed (always `1`).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>
<ResponseField name="meta.notice" type="string">Present only when the candidate window held more bars than were returned — i.e. `limit` truncated the result. The message tells the agent to narrow the window or split the query: `More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · macro_indicator_history" expandable theme={null}
{
  "data": {
    "indicator": "us.cpi.headline",
    "series_id": "CPIAUCSL",
    "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
    "frequency": "Monthly",
    "units": "Index 1982-1984=100",
    "observations": [
      {
        "date": "2026-01-01",
        "value": 318.412,
        "realtime_start": "2026-02-12",
        "realtime_end": "2026-02-12"
      },
      {
        "date": "2026-02-01",
        "value": 319.082,
        "realtime_start": "2026-03-12",
        "realtime_end": "2026-03-12"
      },
      {
        "date": "2026-03-01",
        "value": 319.799,
        "realtime_start": "2026-04-10",
        "realtime_end": "2026-04-10"
      }
    ],
    "attribution": "Source: U.S. Bureau of Labor Statistics via FRED",
    "stale": false
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 99
  }
}
```

<Note>
  Each series carries its own `attribution` string (FRED source notice) under `data` — surface it when you display the data. This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.
</Note>

## Notes

<Tip>
  **Revision-aware**: macro observations get revised. The series returns the **current latest vintage**, not the value released originally. Use `realtime_start` / `realtime_end` to detect whether you're seeing a revised print. As-of vintage replay is not currently supported.
</Tip>

<Tip>
  Default `limit=60` covers the latest \~5 years for monthly series, \~1 year for weekly, or \~3 months for daily. Use `start_date` / `end_date` to bound the window, and `take_from=earliest` when you need the first N observations from that window.
</Tip>

<Warning>
  `take_from=earliest` requires `start_date`. If both date boundaries are provided, `start_date` must not be after `end_date`.
</Warning>

<Warning>
  **Supported catalog only.** \~50 curated U.S. indicators. Arbitrary `series_id` values outside the catalog return `404`. Use `macro_indicator_search` to discover what's available.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Discover the alias
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_search",
        "arguments": { "query": "cpi", "category": "Inflation" }
      }
    }

    // 2) Fetch recent history (default 60)
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_history",
        "arguments": { "indicator": "us.cpi.headline", "limit": 60 }
      }
    }

    // 2b) Or fetch the earliest 12 observations inside an explicit date range
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_history",
        "arguments": {
          "indicator": "us.cpi.headline",
          "start_date": "2020-01-01",
          "end_date": "2026-03-01",
          "limit": 12,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) Discover the alias
    catalog = requests.get(
        f"{base}/api/macro/indicators",
        headers=headers,
        params={"query": "cpi", "category": "Inflation"},
    ).json()["data"]

    alias = catalog[0]["indicator"]  # e.g. us.cpi.headline

    # 2) Fetch recent history
    hist = requests.get(
        f"{base}/api/macro/historical",
        headers=headers,
        params={"indicator": alias, "limit": 60},
    ).json()
    for obs in hist["data"]["observations"][-3:]:
        print(obs["date"], obs["value"])
    ```

    ```bash cURL theme={null}
    # 1) Discover the alias
    curl "https://api.llmquantdata.com/api/macro/indicators?query=cpi&category=Inflation" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2) Fetch recent history (no date boundaries)
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&limit=60" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2b) Earliest 12 observations in a bounded window
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&start_date=2020-01-01&end_date=2026-03-01&limit=12&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<AccordionGroup>
  <Accordion title="macro_indicator_search — request parameters" icon="magnifying-glass">
    <ParamField type="string">
      Free-text keyword. Matches indicator alias, indicator title, and `series_id`.
    </ParamField>

    <ParamField type="string">
      Filter by theme (`Inflation`, `Rates`, `Labor`, `Growth`, `Housing`, `Liquidity`, `Conditions`, `FX`, `Credit`, `Sentiment`, `Energy`, `Inflation Expectations`, `Consumption`).
    </ParamField>

    <ParamField type="string">
      Filter by cadence (`Daily`, `Weekly`, `Monthly`, `Quarterly`, `Annual`).
    </ParamField>

    <ParamField type="number">
      Max items returned. Range `1–100`.
    </ParamField>
  </Accordion>

  <Accordion title="macro_indicator_history — request parameters" icon="chart-line">
    <ParamField type="string">
      Platform alias (e.g. `us.cpi.headline`, `us.rates.fed_funds`). Use this **OR** `series_id`.
    </ParamField>

    <ParamField type="string">
      Raw series ID (e.g. `CPIAUCSL`). Use this **OR** `indicator`. Must be in the supported catalog.
    </ParamField>

    <ParamField type="string">
      Optional inclusive lower boundary, ISO date `YYYY-MM-DD`.
    </ParamField>

    <ParamField type="string">
      Optional inclusive upper boundary, ISO date `YYYY-MM-DD`.
    </ParamField>

    <ParamField type="number">
      Maximum observations to return after boundary filtering. Range `1–500`.
    </ParamField>

    <ParamField type="string">
      Which side of the filtered window to keep when more than `limit` observations match. Use `latest` or `earliest`; output remains chronological.
    </ParamField>
  </Accordion>
</AccordionGroup>

## Related

<Columns>
  <Card title="Macro Indicators Catalog" icon="landmark" href="/en/api/macro/indicators">
    Discover the \~50-indicator catalog (free).
  </Card>

  <Card title="Macro Snapshot" icon="gauge-high" href="/en/api/macro/snapshot">
    Just the latest print + delta vs previous (no full series).
  </Card>
</Columns>


# Macro Indicators Catalog
Source: https://docs.llmquantdata.com/en/api/macro/indicators

Browse and search the supported U.S. macro indicators catalog (~50 series).

<Note icon="sparkles">
  **Available as MCP tool**: `macro_indicator_search` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · 0 credits</Badge>

## What it does for your agent

`macro_indicator_search` returns the LLMQuant Data **supported catalog of \~50 U.S. macro indicators** — Inflation (CPI / PCE), Rates (Fed Funds, Treasury yields), Labor (UNRATE, payrolls), Growth (GDP), Housing, Liquidity (M2, Fed balance sheet), Financial Conditions, FX, and more. Use it as a **catalog discovery step**: when an agent needs to figure out which `indicator` alias or `series_id` to feed into `macro_indicator_history` / `macro_indicator_snapshot`, call this tool first to browse the catalog by `category`, `frequency`, or free-text keyword.

It does **not** expose every possible macro series — only the curated, attribution-cleared supported catalog. Call with no parameters to list everything.

## Response

<ResponseField name="data" type="MacroIndicatorCatalogItem[]">
  Curated catalog entries. Each entry is one supported indicator.

  <Expandable title="MacroIndicatorCatalogItem fields">
    <ResponseField name="indicator" type="string">
      Stable platform alias. Pass to `macro_indicator_history` / `macro_indicator_snapshot` (e.g. `us.cpi.headline`, `us.rates.fed_funds`).
    </ResponseField>

    <ResponseField name="series_id" type="string">
      Raw series ID (e.g. `CPIAUCSL`, `FEDFUNDS`). Also accepted by history/snapshot tools.
    </ResponseField>

    <ResponseField name="title" type="string">
      Human-readable indicator title.
    </ResponseField>

    <ResponseField name="category" type="string">
      Theme bucket: `Growth`, `Consumption`, `Inflation`, `Labor`, `Housing`, `Rates`, `Inflation Expectations`, `Liquidity`, `Conditions`, `FX`, `Credit`, `Sentiment`, `Energy`.
    </ResponseField>

    <ResponseField name="frequency" type="string">
      Native release cadence: `Daily`, `Weekly`, `Monthly`, `Quarterly`, `Annual`.
    </ResponseField>

    <ResponseField name="units" type="string">
      Unit string (e.g. `Index 1982-1984=100`, `Percent`, `Thousands of Persons`).
    </ResponseField>

    <ResponseField name="observation_start" type="string">
      Earliest observation date currently available (YYYY-MM-DD).
    </ResponseField>

    <ResponseField name="observation_end" type="string">
      Most recent observation date currently available (YYYY-MM-DD).
    </ResponseField>

    <ResponseField name="copyright_status" type="string">
      Either `Public Domain: Citation requested` or `Copyrighted: Citation required`. `Pre-approval required` series are not listed.
    </ResponseField>

    <ResponseField name="attribution" type="string">
      Required attribution string. Surface this when displaying the data.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — catalog discovery is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Credits left on your balance after this call.</ResponseField>

```json title="200 OK · macro_indicator_search" expandable theme={null}
{
  "data": [
    {
      "indicator": "us.cpi.headline",
      "series_id": "CPIAUCSL",
      "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
      "category": "Inflation",
      "frequency": "Monthly",
      "units": "Index 1982-1984=100",
      "observation_start": "1947-01-01",
      "observation_end": "2026-03-01",
      "copyright_status": "Public Domain: Citation requested",
      "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
    },
    {
      "indicator": "us.unemployment_rate",
      "series_id": "UNRATE",
      "title": "Unemployment Rate",
      "category": "Labor",
      "frequency": "Monthly",
      "units": "Percent",
      "observation_start": "1948-01-01",
      "observation_end": "2026-03-01",
      "copyright_status": "Public Domain: Citation requested",
      "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
    }
  ],
  "meta": {
    "creditsUsed": 0,
    "remainingCredits": 500
  }
}
```

<Note>
  Each catalog entry carries its own `attribution` string (FRED source notice) under `data` — surface it when you display the data. The catalog uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.
</Note>

## Notes

<Tip>
  **Two-step pattern**: call `macro_indicator_search` first (free) to find the right alias, then `macro_indicator_history` (1 credit) for time series or `macro_indicator_snapshot` (free) for the latest print. Catalog calls don't burn credits, so call freely.
</Tip>

<Tip>
  Prefer the platform `indicator` alias (`us.cpi.headline`) over raw `series_id` (`CPIAUCSL`) — aliases are stable across raw series naming changes and give clearer intent in agent traces.
</Tip>

<Warning>
  **Supported catalog only.** Roughly 50 U.S. macro series. Arbitrary `series_id` values outside the catalog return `404`. If you need a series that isn't listed, file a request.
</Warning>

<Warning>
  Catalog rows are **not real-time**: `observation_end` reflects the latest known release time available to LLMQuant Data, not necessarily today.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_search",
        "arguments": { "category": "Inflation", "limit": 10 }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/macro/indicators",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"category": "Inflation", "limit": 10},
    ).json()
    for item in resp["data"]:
        print(f"{item['indicator']}  ({item['series_id']})  {item['frequency']}")
    ```

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

## Full parameter reference

<Accordion title="macro_indicator_search — request parameters" icon="sliders">
  <ParamField type="string">
    Free-text keyword. Matches indicator alias, indicator title, and `series_id`.
  </ParamField>

  <ParamField type="string">
    Filter by theme. Values: `Growth`, `Consumption`, `Inflation`, `Labor`, `Housing`, `Rates`, `Inflation Expectations`, `Liquidity`, `Conditions`, `FX`, `Credit`, `Sentiment`, `Energy`.
  </ParamField>

  <ParamField type="string">
    Filter by release cadence. Values: `Daily`, `Weekly`, `Monthly`, `Quarterly`, `Annual`.
  </ParamField>

  <ParamField type="number">
    Max items returned. Range `1–100`.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="Macro Historical" icon="chart-line" href="/en/api/macro/historical">
    Time-series observations for one indicator, filtered by date window and bounded by `limit` / `take_from`.
  </Card>

  <Card title="Macro Snapshot" icon="gauge-high" href="/en/api/macro/snapshot">
    Latest print + previous value + delta for one indicator.
  </Card>
</Columns>


# Macro Indicator Snapshot
Source: https://docs.llmquantdata.com/en/api/macro/snapshot

Latest value + previous value + delta for a single U.S. macro indicator.

<Note icon="sparkles">
  **Available as MCP tool**: `macro_indicator_snapshot` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · latest</Badge>

## What it does for your agent

`macro_indicator_snapshot` returns the **latest observation** for a U.S. macro indicator plus the **previous value** and the **delta** between them. Use it as a **macro checkpoint**: when an agent needs to answer "what's the current Fed Funds rate?", "is unemployment up or down vs last month?", or tag the current macro regime — without pulling the full historical series.

`macro_indicator_snapshot({ indicator })` → `latest`, `previous`, `delta_abs`, `delta_pct`. That's it. For the full series, use [`macro_indicator_history`](/en/api/macro/historical).

## Response

<ResponseField name="data" type="MacroSnapshot">
  <Expandable title="MacroSnapshot fields">
    <ResponseField name="indicator" type="string">
      Stable platform alias (e.g. `us.rates.fed_funds`).
    </ResponseField>

    <ResponseField name="series_id" type="string">
      Raw series ID (e.g. `FEDFUNDS`).
    </ResponseField>

    <ResponseField name="title" type="string">
      Human-readable indicator title.
    </ResponseField>

    <ResponseField name="frequency" type="string">
      Native cadence (`Daily`, `Weekly`, `Monthly`, `Quarterly`, `Annual`).
    </ResponseField>

    <ResponseField name="units" type="string">
      Unit string (e.g. `Percent`, `Index 1982-1984=100`).
    </ResponseField>

    <ResponseField name="latest" type="object">
      Latest observation. `null` if no observations are available yet.

      <Expandable title="latest fields">
        <ResponseField name="date" type="string">Observation date (YYYY-MM-DD).</ResponseField>
        <ResponseField name="value" type="number">Reported value, or `null`.</ResponseField>
        <ResponseField name="realtime_start" type="string">First date this value was published.</ResponseField>
        <ResponseField name="realtime_end" type="string">Last date this value remained current.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="previous" type="object">
      Previous observation. `null` if only one print is available.

      <Expandable title="previous fields">
        <ResponseField name="date" type="string">Previous observation date.</ResponseField>
        <ResponseField name="value" type="number">Previous value.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="delta_abs" type="number">
      `latest.value − previous.value`. `null` when either side is missing.
    </ResponseField>

    <ResponseField name="delta_pct" type="number">
      Percent change vs previous (i.e. `delta_abs / previous.value * 100`). `null` when either side is missing or `previous.value == 0`.
    </ResponseField>

    <ResponseField name="attribution" type="string">
      Required attribution string for display.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — this endpoint is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · macro_indicator_snapshot" expandable theme={null}
{
  "data": {
    "indicator": "us.unemployment_rate",
    "series_id": "UNRATE",
    "title": "Unemployment Rate",
    "frequency": "Monthly",
    "units": "Percent",
    "latest": {
      "date": "2026-03-01",
      "value": 4.1,
      "realtime_start": "2026-04-04",
      "realtime_end": "2026-04-04"
    },
    "previous": {
      "date": "2026-02-01",
      "value": 4.0
    },
    "delta_abs": 0.1,
    "delta_pct": 2.5,
    "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
  },
  "meta": {
    "creditsUsed": 0,
    "remainingCredits": 99
  }
}
```

<Note>
  The snapshot carries its own `attribution` string (FRED source notice) under `data` — surface it when you display the data. This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis.
</Note>

## Notes

<Tip>
  **Revision-aware**: snapshots return the **latest vintage** — not the value originally released. If a recent print has been revised, you'll see the revised value. Check `latest.realtime_start` to see when the value was last published.
</Tip>

<Tip>
  Snapshot returns far fewer tokens than `macro_indicator_history`, and this endpoint is free. Reach for snapshot when the agent needs "what is it now?" and doesn't need a series.
</Tip>

<Warning>
  **Supported catalog only.** \~50 curated U.S. indicators. Use `macro_indicator_search` to discover what's available; arbitrary `series_id` values outside the catalog return `404`.
</Warning>

<Warning>
  Frequency-aware freshness: daily/weekly indicators refresh within 24 h; monthly/quarterly within 7 days. The snapshot may be a few hours behind the absolute latest release.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_snapshot",
        "arguments": { "indicator": "us.unemployment_rate" }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/macro/snapshot",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"indicator": "us.unemployment_rate"},
    ).json()
    d = resp["data"]
    print(f"{d['indicator']}: {d['latest']['value']}{d['units'][:1]} "
          f"({d['delta_abs']:+.2f} vs prev)")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/macro/snapshot?indicator=us.unemployment_rate" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="macro_indicator_snapshot — request parameters" icon="sliders">
  <ParamField type="string">
    Platform alias (e.g. `us.cpi.headline`, `us.rates.fed_funds`, `us.unemployment_rate`). Use this **OR** `series_id`.
  </ParamField>

  <ParamField type="string">
    Raw series ID (e.g. `UNRATE`, `FEDFUNDS`). Use this **OR** `indicator`. Must be in the supported catalog.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="Macro Historical" icon="chart-line" href="/en/api/macro/historical">
    Full latest-vintage time series for the same indicator, filtered by date window and bounded by `limit` / `take_from`.
  </Card>

  <Card title="Macro Indicators Catalog" icon="landmark" href="/en/api/macro/indicators">
    Browse the \~50-indicator catalog (free).
  </Card>
</Columns>


# News Browse
Source: https://docs.llmquantdata.com/en/api/news/browse

Browse continuously updated company news by ticker, event, topic, or date.

<Note icon="sparkles">
  **Available as MCP tool**: `news_browse` — call it directly from Claude, Cursor, or any MCP client. See [MCP Server](/en/integration/mcp-server) for setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>2 credits per call</Badge>

## What it does for your agent

`news_browse` gives your agent recent company news with concise titles, abstracts, and detailed summaries. Use exact filters to scan the market, follow companies, or find specific event and topic combinations.

Availability varies by company and date. Start with a recent query, then narrow the results with exact filters.

## Response

<ResponseField name="data" type="object">
  The matching news items and returned count.

  <Expandable title="data fields">
    <ResponseField name="items" type="NewsArticle[]">
      Results ordered by `published_at` descending, most recent first.

      <Expandable title="NewsArticle fields">
        <ResponseField name="title" type="string">
          Short title for scanning the result list.
        </ResponseField>

        <ResponseField name="abstract" type="string">
          One or two sentences for deciding whether to read the full summary.
        </ResponseField>

        <ResponseField name="summary" type="string">
          Detailed article summary with material facts and qualifying context.
        </ResponseField>

        <ResponseField name="events" type="string[]">
          Controlled event values in alphabetical order. Ignore unknown future values.
        </ResponseField>

        <ResponseField name="topics" type="string[]">
          Controlled subject topics in alphabetical order. Ignore unknown future values.
        </ResponseField>

        <ResponseField name="tickers" type="string[]">
          Equity symbols connected to the article.
        </ResponseField>

        <ResponseField name="published_at" type="string">
          Publication date in UTC, with day-level precision.
        </ResponseField>

        <ResponseField name="source_url" type="string">
          Link to the original announcement. Follow it when the agent needs the source text.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">
      Number of items returned in this response.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `2` after a valid query runs, including an empty result.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>
<ResponseField name="meta.notice" type="string">Present when no data matches or more items exist beyond `limit`.</ResponseField>

```json title="200 OK · news_browse" expandable theme={null}
{
  "data": {
    "items": [
      {
        "title": "NVIDIA Announces Q1 Results",
        "abstract": "NVIDIA reported quarterly results and described demand across its major businesses.",
        "summary": "NVIDIA reported quarterly performance and provided updated guidance for the next period.",
        "events": ["earnings", "guidance"],
        "topics": ["artificial_intelligence", "semiconductors"],
        "tickers": ["NVDA"],
        "published_at": "2026-06-01",
        "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000123/nvda-ex99_1.htm"
      }
    ],
    "count": 1
  },
  "meta": { "creditsUsed": 2, "remainingCredits": 98 }
}
```

## Notes

<Tip>
  Start without filters for recent market activity. Then combine `tickers`, `events`, and `topics` to narrow the result set.
</Tip>

<Warning>
  Availability varies by company, date, and category. A valid query can return no items when nothing matches the selected filters.
</Warning>

<Warning>
  Every valid query costs 2 credits, even when no items match. Invalid requests and service errors do not consume credits.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "news_browse",
        "arguments": {
          "tickers": ["NVDA"],
          "events": ["earnings", "guidance"],
          "limit": 5
        }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/news/browse",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"tickers": "NVDA", "events": "earnings,guidance", "limit": 5},
    ).json()

    for item in resp["data"]["items"]:
        print(item["published_at"], item["title"])
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/news/browse?tickers=NVDA&events=earnings,guidance&limit=5" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="news_browse — request parameters" icon="sliders">
  <ParamField type="string">
    Comma-separated equity symbols. Values use OR logic. Maximum: 5.
  </ParamField>

  <ParamField type="string">
    Comma-separated event values. Values use OR logic. Supported values: `earnings`, `guidance`, `m_and_a`, `partnership`, `product`, `regulatory_approval`, `regulatory`, `legal`, `leadership_change`, `workforce`, `restructuring`, `bankruptcy`, `capital_action`, `credit_rating`, `analyst_rating`, `accounting_audit`, `operational_incident`, `shareholder_meeting`, `strategic_update`, `other`.
  </ParamField>

  <ParamField type="string">
    Comma-separated subject topics. Values use OR logic. Supported values: `semiconductors`, `software`, `cloud_computing`, `cybersecurity`, `artificial_intelligence`, `consumer_electronics`, `it_hardware_networking`, `telecommunications`, `media_entertainment`, `internet_services`, `biotech_pharma`, `medical_devices`, `life_sciences_tools`, `healthcare_services`, `banking`, `capital_markets`, `insurance`, `fintech`, `crypto_digital_assets`, `real_estate`, `automotive`, `retail`, `consumer_packaged_goods`, `apparel_luxury`, `restaurants_leisure`, `aerospace_defense`, `industrial_machinery`, `transportation_logistics`, `construction_engineering`, `business_services`, `oil_gas`, `renewable_energy`, `utilities`, `metals_mining`, `chemicals`, `agriculture_food_production`, `paper_packaging_forestry`, `environmental_services`, `space_economy`, `quantum_computing`, `data_centers`, `macroeconomics_policy`, `geopolitics_trade`.
  </ParamField>

  <ParamField type="string">
    Inclusive UTC start date in `YYYY-MM-DD` format. Requires `end_date`.
  </ParamField>

  <ParamField type="string">
    Inclusive UTC end date in `YYYY-MM-DD` format. Requires `start_date`.
  </ParamField>

  <ParamField type="number">
    Maximum items returned. Range: 1–25.
  </ParamField>
</Accordion>

Parameters use AND logic across fields and OR logic within `tickers`, `events`, or `topics`. All parameters are optional, so an empty query returns recent market activity.

## Related

<Columns>
  <Card title="Authentication" icon="key" href="/en/authentication">
    Create an API key and authenticate direct HTTP requests.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude, Cursor, or another agent harness in 60 seconds.
  </Card>
</Columns>


# Personal Holdings
Source: https://docs.llmquantdata.com/en/api/personal/holdings

Read the holdings you saved in Dashboard Profile for portfolio-aware agent answers.

<Note icon="sparkles">
  **Available as MCP tool**: `personal_holdings` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · 0 credits</Badge>

## What it does for your agent

`personal_holdings` returns the positions you saved in **Dashboard → Profile**. Use it when an agent needs your portfolio context before calling market, filing, or research tools: concentration checks, "what do I own?", asset-class filters, or portfolio-aware research.

The tool is read-only. It does not place trades, connect to a brokerage account, or fetch live balances. Values are what you saved in Profile; combine this with price tools when the answer needs current market data.

Only your own account's Profile data is returned.

## Response

<ResponseField name="data" type="object">
  Saved holdings envelope for the caller's own account.

  <Expandable title="data fields">
    <ResponseField name="total_count" type="number">
      Number of returned holdings after filters and limit.
    </ResponseField>

    <ResponseField name="holdings" type="PersonalHolding[]">
      Holdings saved in Profile, most recently saved rows first.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.holdings[]" type="PersonalHolding">
  <Expandable title="PersonalHolding fields">
    <ResponseField name="symbol" type="string">Ticker or symbol, when saved.</ResponseField>
    <ResponseField name="name" type="string">Display name, when saved.</ResponseField>

    <ResponseField name="asset_class" type="string">
      One of `equity`, `etf`, `crypto`, `cash`, `fund`, `bond`, or `other`.
    </ResponseField>

    <ResponseField name="quantity" type="number">Saved position size.</ResponseField>
    <ResponseField name="market_value" type="number">Saved market value.</ResponseField>

    <ResponseField name="cost_basis" type="number">
      Saved aggregate total cost for the position. If both `cost_basis` and `quantity` exist, agents can derive an average cost as `cost_basis / quantity`.
    </ResponseField>

    <ResponseField name="currency" type="string">Currency code, usually `USD`.</ResponseField>
    <ResponseField name="as_of_date" type="string">Date attached to the saved value (`YYYY-MM-DD`).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — this read is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</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 · empty portfolio" expandable theme={null}
{
  "data": { "total_count": 0, "holdings": [] },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## Notes

<Tip>
  Start with `personal_holdings` when the user asks a portfolio-aware question, then call market tools only for the tickers that matter. This keeps the agent focused on the user's saved positions.
</Tip>

<Warning>
  Any active API key or Remote MCP URL for your account can read this saved Profile data until you delete the saved rows or revoke the credential.
</Warning>

<Warning>
  Values are user-saved profile values, not live market quotes or brokerage balances. Use price tools for current market data.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" 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>

## Full parameter reference

<Accordion title="All request parameters" icon="sliders">
  <ParamField type="string">
    Optional filter. One of `equity`, `etf`, `crypto`, `cash`, `fund`, `bond`, or `other`.
  </ParamField>

  <ParamField type="number">
    Maximum holdings returned. Range `1-50`; values above `50` are capped at `50`.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="Personal Profile" icon="user" href="/en/api/personal/profile">
    Read saved risk preference, time horizon, base currency, and notes.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any agent harness in 60 seconds.
  </Card>
</Columns>


# Personal Profile
Source: https://docs.llmquantdata.com/en/api/personal/profile

Read the financial profile you saved in Dashboard Profile for personalized agent context.

<Note icon="sparkles">
  **Available as MCP tool**: `personal_profile` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · 0 credits</Badge>

## What it does for your agent

`personal_profile` returns the financial profile you saved in **Dashboard → Profile**: risk preference, investment horizon, base currency, and notes. Use it when an agent needs to adapt wording, assumptions, or portfolio analysis to your own constraints.

The tool is read-only. It does not change your profile, place trades, or infer missing answers. If you have not saved a profile, the endpoint returns `data: null` with `200 OK`.

Only your own account's Profile data is returned.

## Response

<ResponseField name="data" type="PersonalProfile | null">
  Saved profile for the caller's own account, or `null` when no profile is saved.

  <Expandable title="PersonalProfile fields">
    <ResponseField name="risk_preference" type="string">
      Saved risk preference, such as conservative or aggressive, when provided.
    </ResponseField>

    <ResponseField name="investment_horizon" type="string">
      Saved time horizon, when provided.
    </ResponseField>

    <ResponseField name="base_currency" type="string">
      Base currency code used for the profile. Defaults to `USD`.
    </ResponseField>

    <ResponseField name="extra_notes" type="string">
      Saved notes for personal constraints or preferences. Long notes are shortened to 1,000 characters.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — this read is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · personal_profile" expandable theme={null}
{
  "data": {
    "risk_preference": "moderate",
    "investment_horizon": "5-10 years",
    "base_currency": "USD",
    "extra_notes": "Prefer diversified ETFs and avoid concentrated single-stock positions."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

```json title="200 OK · no saved profile" expandable theme={null}
{
  "data": null,
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## Notes

<Tip>
  Call `personal_profile` before a portfolio-aware answer when the user asks for guidance in their own context, then combine it with [`personal_holdings`](/en/api/personal/holdings) when holdings matter.
</Tip>

<Warning>
  Any active API key or Remote MCP URL for your account can read this saved Profile data until you delete the saved profile or revoke the credential.
</Warning>

<Warning>
  Profile values are user-saved preferences and notes. They are context for the agent, not verified financial advice.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "personal_profile",
        "arguments": {}
      }
    }
    ```

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

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

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/personal/profile" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="All request parameters" icon="sliders">
  This endpoint accepts no request parameters.
</Accordion>

## Related

<Columns>
  <Card title="Personal Holdings" icon="wallet" href="/en/api/personal/holdings">
    Read the holdings saved in Dashboard Profile.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any agent harness in 60 seconds.
  </Card>
</Columns>


# Prediction Markets Events
Source: https://docs.llmquantdata.com/en/api/prediction-markets/events

Browse, search, and read finance-scoped Prediction Markets event cards for agent workflows.

<Note icon="sparkles">
  **Available as MCP tools**: `polymarket_event_browse` + `polymarket_event_search` + `polymarket_event_read` - call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit · browse</Badge>
 
<Badge>2 credits · search</Badge>
 
<Badge>free · read</Badge>

## What it does for your agent

Prediction Markets events group related market questions into one agent-readable card. Use `polymarket_event_search` for natural-language questions such as "Bitcoin ETF approval" or "Fed rate cut odds"; use `polymarket_event_browse` only for list requests or exact filters such as `query=ETF`, `tag=policy`, or `min_volume=10000`.

The event card is the entry point, not the final stop. After browse or search returns an `event_card_id`, call `polymarket_event_read` to load the event description, lifecycle state, tags, and child market previews before choosing a market.

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  alt User gives filters
    Agent->>MCP: polymarket_event_browse(status, query, tag, asset, limit)
    MCP-->>Agent: events[] · eventCardId · title · markets[]
  else User asks in natural language
    Agent->>MCP: polymarket_event_search(query, status, limit)
    MCP-->>Agent: events[] · semanticScore · eventCardId
  end
  Note over Agent: choose the event whose markets match the task
  Agent->>MCP: polymarket_event_read(event_card_id)
  MCP-->>Agent: event card · market previews · coverage status
```

## Response

### Browse and search response

<ResponseField name="data.events" type="PolymarketEvent[]">
  Browse results use lifecycle and liquidity ordering. Search results use semantic relevance.

  <Expandable title="PolymarketEvent fields">
    <ResponseField name="event_card_id" type="string">
      Stable LLMQuant event id. Pass this to `polymarket_event_read`.
    </ResponseField>

    <ResponseField name="title" type="string">
      Human-readable event title.
    </ResponseField>

    <ResponseField name="description" type="string">
      Event-level description when available.
    </ResponseField>

    <ResponseField name="market_count" type="number">
      Number of child markets in the event card.
    </ResponseField>

    <ResponseField name="markets" type="PolymarketMarketPreview[]">
      Market previews with `market_card_id`, `market_question`, outcomes, status, liquidity, and volume.
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      Finance tags such as `crypto`, `policy`, or `macro`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Event status: `active`, `inactive`, or `closed`.
    </ResponseField>

    <ResponseField name="coverage_status" type="string">
      Coverage state for this normalized event card.
    </ResponseField>

    <ResponseField name="semantic_score" type="number">
      Present on semantic search results. Higher means closer to the query.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">Number of returned events.</ResponseField>
<ResponseField name="data.nextCursor" type="string">Pagination cursor for browse, when more events are available.</ResponseField>
<ResponseField name="data.scope" type="string">Always `finance` for this product surface.</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">`1` for browse and `2` for search.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · event search" expandable theme={null}
{
  "data": {
    "events": [
      {
        "event_card_id": "4b8f35c6-4781-4f3c-9237-142fc16467cd",
        "title": "Bitcoin ETF approved by Jan 15?",
        "description": "Markets related to whether a spot Bitcoin ETF is approved.",
        "market_count": 1,
        "markets": [
          {
            "market_card_id": "e370488a-33b5-4abd-8c5c-37c7ad8a60fc",
            "market_question": "Bitcoin ETF approved by Jan 15?",
            "outcomes": [
              { "label": "Yes", "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658", "current_probability": 0.51 }
            ],
            "status": "closed",
            "volume": 1250000,
            "liquidity": 48000
          }
        ],
        "tags": ["crypto", "etf"],
        "status": "closed",
        "coverage_status": "partial",
        "semantic_score": 0.91
      }
    ],
    "count": 1,
    "scope": "finance"
  },
  "meta": { "creditsUsed": 2, "remainingCredits": 98 }
}
```

### Event read response

<ResponseField name="data" type="PolymarketEvent">
  One event card with the same fields returned by browse/search, plus full event metadata.
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for event read.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

## Notes

<Tip>
  Use search for user language. Use browse only for explicit list or exact lexical filters (`status=active`, `query=ETF`, `min_volume=10000`). Read the selected event before choosing a market so the agent sees all child questions together.
</Tip>

<Tip>
  For market-level outcomes and probability history, continue to [`Prediction Markets Market Details`](/en/api/prediction-markets/markets) with the `market_card_id` returned in the event card.
</Tip>

<Warning>
  This surface is finance-scoped. It does not cover sports, entertainment, wallet state, order books, or trading actions.
</Warning>

<Warning>
  For exact time windows, use `polymarket_event_browse`. Pass `start_time` and `end_time` together, with `start_time` no later than `end_time`.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Search for an event
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_event_search",
        "arguments": { "query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5 }
      }
    }

    // 2) Read the selected event
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_event_read",
        "arguments": { "event_card_id": "pme_902959" }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    events = requests.post(
        f"{base}/api/polymarket/events/search",
        headers=headers,
        json={"query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5},
    ).json()["data"]["events"]

    event = requests.get(
        f"{base}/api/polymarket/events/{events[0]['event_card_id']}",
        headers=headers,
    ).json()["data"]
    print(event["title"], event["market_count"])
    ```

    ```bash cURL theme={null}
    curl -X POST "https://api.llmquantdata.com/api/polymarket/events/search" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5}'

    curl "https://api.llmquantdata.com/api/polymarket/events/pme_902959" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<AccordionGroup>
  <Accordion title="polymarket_event_browse — request parameters" icon="sliders">
    <ParamField type="string">
      One of `active`, `inactive`, `closed`, or `active_or_recently_closed`.
    </ParamField>

    <ParamField type="string">Optional exact lexical filter across event title, slug, tags, child market questions, and outcome labels. Max 200 characters.</ParamField>
    <ParamField type="string">Optional finance tag, such as `crypto` or `policy`.</ParamField>
    <ParamField type="string">Optional asset or entity filter, such as `BTC`.</ParamField>
    <ParamField type="string">ISO 8601 UTC start. Must be used with `end_time`.</ParamField>
    <ParamField type="string">ISO 8601 UTC end. Must be used with `start_time`.</ParamField>
    <ParamField type="number">Optional minimum event-level market volume.</ParamField>
    <ParamField type="number">Optional minimum event-level market liquidity.</ParamField>
    <ParamField type="number">Maximum events returned. Range `1-100`.</ParamField>
    <ParamField type="string">Pagination cursor from `data.nextCursor`.</ParamField>
  </Accordion>

  <Accordion title="polymarket_event_search — request parameters" icon="magnifying-glass">
    <ParamField type="string">Natural-language query. Max 2,000 characters.</ParamField>

    <ParamField type="string">
      One of `active`, `inactive`, `closed`, or `active_or_recently_closed`.
    </ParamField>

    <ParamField type="string">Optional finance tag.</ParamField>
    <ParamField type="number">Maximum events returned. Range `1-20`.</ParamField>
  </Accordion>

  <Accordion title="polymarket_event_read — request parameters" icon="file-lines">
    <ParamField type="string">
      Event id returned by browse or search; the alias `pme_902959` is also accepted.
    </ParamField>
  </Accordion>
</AccordionGroup>

## Related

<Columns>
  <Card title="Prediction Markets Market Details" icon="gauge-high" href="/en/api/prediction-markets/markets">
    Read market outcomes and implied-probability history.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# Prediction Markets Market Details
Source: https://docs.llmquantdata.com/en/api/prediction-markets/markets

Read Prediction Markets market cards and outcome ids before loading probability history.

<Note icon="sparkles">
  **Available as MCP tools**: `polymarket_market_read` + `polymarket_price_history` - call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · market read</Badge>
 
<Badge>free · price history</Badge>

## What it does for your agent

`polymarket_market_read` loads one market selected from a Prediction Markets event card. It returns the market question, status, outcomes, outcome token ids, tags, liquidity, volume, and event context so an agent can decide which side of the market to inspect.

`polymarket_price_history` takes one `outcome_token_id` from that market and returns implied-probability points at `1h` or `1d` resolution. Use it to show how market-implied odds moved over time; do not treat it as OHLCV candles, order book depth, or executable quotes.

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: polymarket_market_read(market_card_id)
  MCP-->>Agent: market card · outcomes[] · outcomeTokenId
  alt outcome token is present
    Agent->>MCP: polymarket_price_history(outcome_token_id, interval, range)
    MCP-->>Agent: points[] · probability · coverage status
  else outcome token is missing
    Agent->>Agent: answer from market card only
  end
```

## Response

### Market read response

<ResponseField name="data" type="PolymarketMarket">
  One market card.

  <Expandable title="PolymarketMarket fields">
    <ResponseField name="market_card_id" type="string">
      Stable LLMQuant market id. Use this after reading an event card.
    </ResponseField>

    <ResponseField name="event_card_id" type="string">
      Parent event id.
    </ResponseField>

    <ResponseField name="market_question" type="string">
      The market question agents should quote or summarize.
    </ResponseField>

    <ResponseField name="outcomes" type="PolymarketOutcome[]">
      Outcome sides. Each outcome can include `label`, `outcome_token_id`, `current_probability`, and latest price metadata.
    </ResponseField>

    <ResponseField name="status" type="string">
      Market status: `active`, `inactive`, or `closed`.
    </ResponseField>

    <ResponseField name="volume" type="number">Reported market volume when available.</ResponseField>
    <ResponseField name="liquidity" type="number">Reported market liquidity when available.</ResponseField>
    <ResponseField name="coverage_status" type="string">Coverage state for this market card.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for market read.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · market read" expandable theme={null}
{
  "data": {
    "market_card_id": "e370488a-33b5-4abd-8c5c-37c7ad8a60fc",
    "event_card_id": "4b8f35c6-4781-4f3c-9237-142fc16467cd",
    "market_question": "Bitcoin ETF approved by Jan 15?",
    "outcomes": [
      {
        "label": "Yes",
        "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
        "current_probability": 0.51,
        "last_price_time": "2024-01-10T00:00:00Z",
        "coverage_status": "partial"
      },
      { "label": "No", "outcome_token_id": null, "current_probability": 0.49 }
    ],
    "status": "closed",
    "volume": 1250000,
    "liquidity": 48000,
    "coverage_status": "partial"
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

### Price history response

<ResponseField name="data" type="PolymarketPriceHistory">
  Probability history for one outcome token.

  <Expandable title="PolymarketPriceHistory fields">
    <ResponseField name="outcome_token_id" type="string">Outcome token requested.</ResponseField>
    <ResponseField name="interval" type="string">`1h` or `1d`.</ResponseField>

    <ResponseField name="points" type="PolymarketPricePoint[]">
      Ordered probability points.
    </ResponseField>

    <ResponseField name="coverage_status" type="string">
      Data availability state for the requested token and range.
    </ResponseField>

    <ResponseField name="coverage_notice" type="string">
      Plain-English explanation of availability.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">Number of returned points.</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for price history.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · price history" expandable theme={null}
{
  "data": {
    "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
    "interval": "1d",
    "points": [
      { "time": "2024-01-01T00:00:00Z", "probability": 0.39, "price": 0.39 },
      { "time": "2024-01-02T00:00:00Z", "probability": 0.42, "price": 0.42 }
    ],
    "coverage_status": "partial",
    "coverage_notice": "Partial probability history is available for the requested window.",
    "count": 2
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## Notes

<Tip>
  Start from [`Prediction Markets Events`](/en/api/prediction-markets/events). Market ids and outcome token ids are selected from event cards, not guessed.
</Tip>

<Tip>
  Use `1d` for narrative timelines and `1h` when the agent needs intraday movement around a dated event.
</Tip>

<Warning>
  `interval` only accepts `1h` and `1d`. Requests such as `interval=15m` return `400` before any credit is charged.
</Warning>

<Warning>
  Price history returns implied-probability points for one outcome token. It is not OHLCV, order book data, trade history, or investment advice.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Read the market
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_market_read",
        "arguments": { "market_card_id": "pmm_253254" }
      }
    }

    // 2) Load daily probability history for the Yes outcome
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_price_history",
        "arguments": {
          "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
          "interval": "1d",
          "start_time": "2024-01-01T00:00:00Z",
          "end_time": "2024-01-15T00:00:00Z"
        }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    market = requests.get(
        f"{base}/api/polymarket/markets/pmm_253254",
        headers=headers,
    ).json()["data"]
    token = market["outcomes"][0]["outcome_token_id"]

    history = requests.get(
        f"{base}/api/polymarket/price-history",
        headers=headers,
        params={
            "outcome_token_id": token,
            "interval": "1d",
            "start_time": "2024-01-01T00:00:00Z",
            "end_time": "2024-01-15T00:00:00Z",
        },
    ).json()["data"]
    print(history["points"][:2])
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/polymarket/markets/pmm_253254" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    curl "https://api.llmquantdata.com/api/polymarket/price-history?outcome_token_id=98787006152320761811798607481686168525551752574583108841982899511109091268658&interval=1d&start_time=2024-01-01T00%3A00%3A00Z&end_time=2024-01-15T00%3A00%3A00Z" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<AccordionGroup>
  <Accordion title="polymarket_market_read — request parameters" icon="file-lines">
    <ParamField type="string">
      Market id returned by an event card; the alias `pmm_253254` is also accepted.
    </ParamField>
  </Accordion>

  <Accordion title="polymarket_price_history — request parameters" icon="chart-line">
    <ParamField type="string">
      Outcome token id returned by `polymarket_market_read`.
    </ParamField>

    <ParamField type="string">
      `1h` or `1d`.
    </ParamField>

    <ParamField type="string">Optional inclusive ISO 8601 UTC lower boundary.</ParamField>
    <ParamField type="string">Optional inclusive ISO 8601 UTC upper boundary.</ParamField>
    <ParamField type="number">Maximum points returned after boundary filtering. Default `720` for `1h`, `365` for `1d`; max `20000`.</ParamField>
    <ParamField type="string">Use `latest` or `earliest`; output remains chronological.</ParamField>
  </Accordion>
</AccordionGroup>

## Related

<Columns>
  <Card title="Prediction Markets Events" icon="gauge-high" href="/en/api/prediction-markets/events">
    Browse, search, and read event cards before selecting a market.
  </Card>

  <Card title="Prediction Markets Price History" icon="chart-line" href="/en/api/prediction-markets/price-history">
    Query probability history after selecting an outcome token.
  </Card>
</Columns>


# Prediction Markets Price History
Source: https://docs.llmquantdata.com/en/api/prediction-markets/price-history

Hourly or daily implied-probability history for one Prediction Markets outcome token.

<Note icon="sparkles">
  **Available as MCP tool**: `polymarket_price_history` - call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free</Badge>

## What it does for your agent

`polymarket_price_history` returns how one outcome's implied probability changed over time. Use it after your agent has selected a market outcome and needs a clean timeline for a chart, event recap, or probability-move explanation.

Pass an `outcome_token_id`, choose `1h` or `1d`, optionally set one or two UTC time boundaries, then use `limit` and `take_from` to choose which edge to keep. The response gives ordered points with `time`, `probability`, and `price`.

## Response

<ResponseField name="data" type="PolymarketPriceHistory">
  Probability history for one outcome token.

  <Expandable title="PolymarketPriceHistory fields">
    <ResponseField name="outcome_token_id" type="string">
      The outcome token you requested.
    </ResponseField>

    <ResponseField name="interval" type="string">
      `1h` or `1d`.
    </ResponseField>

    <ResponseField name="points" type="PolymarketPricePoint[]">
      Ordered probability points. Each point includes `time`, `probability`, and `price`.
    </ResponseField>

    <ResponseField name="coverage_status" type="string">
      Availability state for the requested token and time range.
    </ResponseField>

    <ResponseField name="coverage_notice" type="string">
      Short explanation of what data was available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">Number of returned points.</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for this call.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>
<ResponseField name="meta.notice" type="string">Present only when the candidate window held more bars than were returned — i.e. `limit` truncated the result. The message tells the agent to narrow the window or split the query: `More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · polymarket_price_history" expandable theme={null}
{
  "data": {
    "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
    "interval": "1d",
    "points": [
      { "time": "2024-01-01T00:00:00Z", "probability": 0.39, "price": 0.39 },
      { "time": "2024-01-02T00:00:00Z", "probability": 0.42, "price": 0.42 }
    ],
    "coverage_status": "partial",
    "coverage_notice": "Partial probability history is available for the requested window.",
    "count": 2
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## Notes

<Tip>
  Start from [`Prediction Markets Events`](/en/api/prediction-markets/events), read the selected market, then pass one returned `outcome_token_id` here.
</Tip>

<Tip>
  Use `1d` for a simple timeline. Use `1h` when the agent needs to explain movement around a specific day or announcement.
</Tip>

<Warning>
  `interval` only accepts `1h` and `1d`. Requests such as `interval=15m` return `400` before any credit is charged.
</Warning>

<Warning>
  This returns implied-probability points for one outcome. It is not OHLCV data, an order book, trade history, or investment advice.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_price_history",
        "arguments": {
          "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
          "interval": "1d",
          "start_time": "2024-01-01T00:00:00Z",
          "end_time": "2024-01-15T00:00:00Z",
          "limit": 10,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/polymarket/price-history",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={
            "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
            "interval": "1d",
            "start_time": "2024-01-01T00:00:00Z",
            "end_time": "2024-01-15T00:00:00Z",
            "limit": 10,
            "take_from": "earliest",
        },
    ).json()
    print(resp["data"]["points"][:2])
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/polymarket/price-history?outcome_token_id=98787006152320761811798607481686168525551752574583108841982899511109091268658&interval=1d&start_time=2024-01-01T00%3A00%3A00Z&end_time=2024-01-15T00%3A00%3A00Z&limit=10&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="polymarket_price_history — request parameters" icon="chart-line">
  <ParamField type="string">
    Outcome token id returned by `polymarket_market_read`.
  </ParamField>

  <ParamField type="string">
    `1h` or `1d`.
  </ParamField>

  <ParamField type="string">Optional inclusive ISO 8601 UTC lower boundary.</ParamField>
  <ParamField type="string">Optional inclusive ISO 8601 UTC upper boundary.</ParamField>
  <ParamField type="number">Maximum points returned after boundary filtering. Default `720` for `1h`, `365` for `1d`; max `20000`.</ParamField>
  <ParamField type="string">Which side of the filtered window to keep when more than `limit` points match. Use `latest` or `earliest`; output remains chronological.</ParamField>
</Accordion>

## Related

<Columns>
  <Card title="Prediction Markets Events" icon="gauge-high" href="/en/api/prediction-markets/events">
    Browse, search, and read event cards before selecting a market.
  </Card>

  <Card title="Prediction Markets Market Details" icon="file-lines" href="/en/api/prediction-markets/markets">
    Read market outcomes and copy the `outcome_token_id` you need.
  </Card>
</Columns>


# Crypto Historical Klines
Source: https://docs.llmquantdata.com/en/api/prices/crypto-historical

OHLCV K-line bars for crypto pairs with limit/take_from selection and 1h / 4h / 1d / 1w intervals.

<Note icon="sparkles">
  **Available as MCP tool**: `crypto_historical_klines` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit per call</Badge>

## What it does for your agent

`crypto_historical_klines` returns OHLCV candlestick bars for a single crypto pair. Use it as the **historical pricing primitive** an agent reaches for whenever it needs returns, drawdowns, technicals, or backtest data — not for the latest tick (use `crypto_snapshot` for that).

Use `start_time` and/or `end_time` to filter the candidate window, then `limit` and `take_from` choose which edge to keep. Results always return oldest first. Only **closed candles** are returned — the in-progress candle is never included.

## Response

<ResponseField name="data" type="CryptoHistoricalResult">
  <Expandable title="CryptoHistoricalResult fields">
    <ResponseField name="ticker" type="string">
      The trading pair in `BASE-QUOTE` format (e.g. `BTC-USD`).
    </ResponseField>

    <ResponseField name="interval" type="string">
      Candlestick interval (`1h` / `4h` / `1d` / `1w`).
    </ResponseField>

    <ResponseField name="prices" type="CryptoKlineBar[]">
      Klines in chronological order. Closed candles only.

      <Expandable title="CryptoKlineBar fields">
        <ResponseField name="open" type="number">Opening price.</ResponseField>
        <ResponseField name="high" type="number">High price.</ResponseField>
        <ResponseField name="low" type="number">Low price.</ResponseField>
        <ResponseField name="close" type="number">Closing price.</ResponseField>
        <ResponseField name="volume" type="number">Base-asset trading volume.</ResponseField>
        <ResponseField name="time" type="string">Bar open time (ISO 8601 UTC).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed (always `1`).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>
<ResponseField name="meta.notice" type="string">Present only when the candidate window held more bars than were returned — i.e. `limit` truncated the result. The message tells the agent to narrow the window or split the query: `More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · crypto_historical_klines" expandable theme={null}
{
  "data": {
    "ticker": "BTC-USD",
    "interval": "1d",
    "prices": [
      {
        "open": 87000.50,
        "high": 87500.00,
        "low": 86800.00,
        "close": 87200.00,
        "volume": 1234.56,
        "time": "2026-03-01T00:00:00Z"
      },
      {
        "open": 87200.00,
        "high": 88100.00,
        "low": 87000.00,
        "close": 87950.00,
        "volume": 1456.78,
        "time": "2026-03-02T00:00:00Z"
      }
    ]
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

## Notes

<Tip>
  For the **latest tick** (price + 24h change), use `crypto_snapshot` — it's a different primitive and is much cheaper conceptually. Reach for `crypto_historical_klines` only when you need a series of bars.
</Tip>

<Tip>
  The first request for a ticker + interval + range can be slower. Subsequent identical queries usually return faster.
</Tip>

<Tip>
  Use `data.prices.length` when you need the returned bar count; `meta` is reserved for credits and optional notices.
</Tip>

<Warning>
  **Spot markets only.** Futures, perpetuals, funding rates, and open interest are not exposed.
</Warning>

<Warning>
  **No minute-level intervals.** `1m`, `5m`, `15m` are not supported — only `1h`, `4h`, `1d`, `1w`.
</Warning>

<Warning>
  **Closed candles only.** The current in-progress candle is never included.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // No time boundaries — the most recent 30 daily candles
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_historical_klines",
        "arguments": { "ticker": "BTC-USD", "interval": "1d", "limit": 30 }
      }
    }

    // Earliest 12 candles inside an explicit window
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_historical_klines",
        "arguments": {
          "ticker": "ETH-USD",
          "interval": "1h",
          "start_time": "2026-03-01T00:00:00Z",
          "end_time": "2026-03-02T00:00:00Z",
          "limit": 12,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # No time boundaries — most recent candles
    resp = requests.get(
        "https://api.llmquantdata.com/api/crypto/historical",
        headers=headers,
        params={"ticker": "BTC-USD", "interval": "1d", "limit": 30},
    ).json()
    for bar in resp["data"]["prices"]:
        print(f"{bar['time']}  C={bar['close']}  V={bar['volume']}")

    # Earliest 12 candles inside a bounded window
    resp = requests.get(
        "https://api.llmquantdata.com/api/crypto/historical",
        headers=headers,
        params={
            "ticker": "ETH-USD",
            "interval": "1h",
            "start_time": "2026-03-01T00:00:00Z",
            "end_time": "2026-03-02T00:00:00Z",
            "limit": 12,
            "take_from": "earliest",
        },
    ).json()
    print(f"Bounded query returned {len(resp['data']['prices'])} bars")
    ```

    ```bash cURL theme={null}
    # No time boundaries — most recent candles
    curl "https://api.llmquantdata.com/api/crypto/historical?ticker=BTC-USD&interval=1d&limit=30" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # Earliest 12 candles inside a bounded window
    curl "https://api.llmquantdata.com/api/crypto/historical?ticker=ETH-USD&interval=1h&start_time=2026-03-01T00:00:00Z&end_time=2026-03-02T00:00:00Z&limit=12&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="crypto_historical_klines — request parameters" icon="sliders">
  <ParamField type="string">
    Trading pair in `BASE-QUOTE` format. Examples: `BTC-USD`, `ETH-USD`, `SOL-USD`.
  </ParamField>

  <ParamField type="string">
    Candlestick interval. One of `1h`, `4h`, `1d`, `1w`. Minute-level intervals are not supported.
  </ParamField>

  <ParamField type="string">
    Optional inclusive lower boundary in ISO 8601 UTC (e.g. `2026-03-01T00:00:00Z`).
  </ParamField>

  <ParamField type="string">
    Optional inclusive upper boundary in ISO 8601 UTC.
  </ParamField>

  <ParamField type="integer">
    Maximum candles to return after boundary filtering. Defaults vary by interval: `1h` = 24, `4h` = 42, `1d` = 30, `1w` = 12. Max `200`.
  </ParamField>

  <ParamField type="string">
    Which side of the filtered window to keep when more than `limit` candles match. Use `latest` or `earliest`; output remains chronological.
  </ParamField>

  <Warning>
    `take_from=earliest` requires `start_time`. If both time boundaries are provided, `start_time` must not be after `end_time`.
  </Warning>
</Accordion>

## Related

<Columns>
  <Card title="Crypto Snapshot" icon="bolt" href="/en/api/prices/crypto-snapshot">
    Latest spot price + 24h stats for a crypto pair — use this when you only need "right now".
  </Card>

  <Card title="Equity Historical Prices" icon="square-chart-gantt" href="/en/api/prices/equity-historical">
    Same bounded historical-series shape for US equities at daily granularity.
  </Card>
</Columns>


# Crypto Price Snapshot
Source: https://docs.llmquantdata.com/en/api/prices/crypto-snapshot

Latest spot price + 24h stats for a crypto pair.

<Note icon="sparkles">
  **Available as MCP tool**: `crypto_snapshot` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · snapshot</Badge>

## What it does for your agent

`crypto_snapshot` returns the current spot price for a single crypto pair plus its 24-hour change and volume. Use it as a **pricing checkpoint** mid-task — when an agent needs to verify current price levels, compare assets, or tag a market regime — without pulling the full klines history.

`crypto_snapshot({ ticker })` → `price`, `dayChange`, `dayChangePercent`, `volume24h`, `time`. That's it.

## Response

<ResponseField name="data" type="CryptoSnapshot">
  <Expandable title="CryptoSnapshot fields">
    <ResponseField name="ticker" type="string">
      The trading pair in `BASE-QUOTE` format (e.g. `BTC-USD`).
    </ResponseField>

    <ResponseField name="price" type="number">
      Latest traded price.
    </ResponseField>

    <ResponseField name="dayChange" type="number">
      Absolute price change over the last 24 hours.
    </ResponseField>

    <ResponseField name="dayChangePercent" type="number">
      Percentage price change over the last 24 hours.
    </ResponseField>

    <ResponseField name="volume24h" type="number">
      24-hour trading volume in the base asset.
    </ResponseField>

    <ResponseField name="time" type="string">
      Snapshot timestamp (ISO-8601 UTC).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — this endpoint is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · crypto_snapshot" expandable theme={null}
{
  "data": {
    "ticker": "BTC-USD",
    "price": 87200.00,
    "dayChange": 1200.50,
    "dayChangePercent": 1.26,
    "volume24h": 12345678,
    "time": "2026-04-29T12:30:00Z"
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## Notes

<Tip>
  For **historical bars**, use `crypto_historical_klines` — it returns OHLCV candles at `1h`, `4h`, `1d`, or `1w` intervals. `crypto_snapshot` is only for "right now".
</Tip>

<Warning>
  **Spot markets only.** Futures, perpetuals, funding rates, and open interest are not exposed by this tool.
</Warning>

<Warning>
  Not trading-grade real-time. It can lag the latest market print by up to 30 seconds. Don't trade on it.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_snapshot",
        "arguments": { "ticker": "BTC-USD" }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/crypto/snapshot",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"ticker": "BTC-USD"},
    ).json()
    d = resp["data"]
    print(f"{d['ticker']}: ${d['price']:,.2f} ({d['dayChangePercent']:+.2f}%)")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/crypto/snapshot?ticker=BTC-USD" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="crypto_snapshot — request parameters" icon="sliders">
  <ParamField type="string">
    Trading pair in `BASE-QUOTE` format. Examples: `BTC-USD`, `ETH-USD`, `SOL-USD`.
  </ParamField>
</Accordion>

## Related

<Columns>
  <Card title="Crypto Historical Klines" icon="chart-line" href="/en/api/prices/crypto-historical">
    OHLCV candles at `1h`, `4h`, `1d`, or `1w` intervals.
  </Card>

  <Card title="Equity Snapshot" icon="square-chart-gantt" href="/en/api/prices/equity-historical">
    Same shape for US equities (different endpoint).
  </Card>
</Columns>


# Equity Historical Prices
Source: https://docs.llmquantdata.com/en/api/prices/equity-historical

Daily OHLCV bars for US equities — filter by date window, keep a bounded slice with limit/take_from, with adjusted close, dividends, and splits.

<Note icon="sparkles">
  **Available as MCP tool**: `equity_historical_prices` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>free · daily bars</Badge>

## What it does for your agent

`equity_historical_prices` returns daily OHLCV bars for a single US equity (NYSE / NASDAQ), plus `adjusted_close`, `dividend`, and `stock_split` per bar. Use it as the **historical pricing primitive** an agent reaches for whenever it needs returns, drawdowns, or backtest data — not for the latest tick.

Use `start_date` and/or `end_date` to filter the candidate window, then `limit` and `take_from` choose which edge to keep. Results always return oldest first. Only **closed trading days** are returned — the in-progress day is never included.

## Response

<ResponseField name="data" type="EquityHistoricalResult">
  <Expandable title="EquityHistoricalResult fields">
    <ResponseField name="ticker" type="string">
      The stock ticker symbol (e.g. `AAPL`).
    </ResponseField>

    <ResponseField name="interval" type="string">
      Always `"1d"` — only daily bars are supported.
    </ResponseField>

    <ResponseField name="prices" type="EquityDailyBar[]">
      Daily bars in chronological order. Closed trading days only.

      <Expandable title="EquityDailyBar fields">
        <ResponseField name="open" type="number">Opening price.</ResponseField>
        <ResponseField name="high" type="number">High price.</ResponseField>
        <ResponseField name="low" type="number">Low price.</ResponseField>
        <ResponseField name="close" type="number">Closing price.</ResponseField>
        <ResponseField name="volume" type="number">Trading volume.</ResponseField>
        <ResponseField name="adjusted_close" type="number">Split- and dividend-adjusted close. Use this for return calculations.</ResponseField>
        <ResponseField name="dividend" type="number">Dividend amount paid on this date (`0` if none).</ResponseField>
        <ResponseField name="stock_split" type="number">Stock split ratio on this date (`0` if none).</ResponseField>
        <ResponseField name="time" type="string">Trading date (`YYYY-MM-DD`).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` — this endpoint is free.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>
<ResponseField name="meta.notice" type="string">Present only when the candidate window held more bars than were returned — i.e. `limit` truncated the result. The message tells the agent to narrow the window or split the query: `More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · equity_historical_prices" expandable theme={null}
{
  "data": {
    "ticker": "AAPL",
    "interval": "1d",
    "prices": [
      {
        "open": 178.50,
        "high": 182.30,
        "low": 177.80,
        "close": 181.20,
        "volume": 52340000,
        "adjusted_close": 181.20,
        "dividend": 0.24,
        "stock_split": 0,
        "time": "2025-03-28"
      },
      {
        "open": 181.00,
        "high": 183.50,
        "low": 180.20,
        "close": 182.90,
        "volume": 48120000,
        "adjusted_close": 182.90,
        "dividend": 0,
        "stock_split": 0,
        "time": "2025-03-31"
      }
    ]
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## Notes

<Tip>
  For **return calculations**, always use `adjusted_close` — it bakes in dividends and splits. Plain `close` is only safe when you're rendering raw price charts.
</Tip>

<Tip>
  The first request for a ticker + range can be slower. Subsequent identical queries usually return faster.
</Tip>

<Tip>
  Use `data.prices.length` when you need the returned bar count; `meta` is reserved for credits and optional notices.
</Tip>

<Warning>
  **US equities only** (NYSE / NASDAQ). No ADRs of non-US listings, no international markets.
</Warning>

<Warning>
  **Daily interval only.** Minute-level (`1m`, `5m`, `15m`) bars are not exposed. For `1h` regular-session bars, use [`equity_intraday_prices`](/en/api/prices/equity-intraday).
</Warning>

<Warning>
  **No real-time quote.** The current trading day is excluded until market close. For latest price, this tool isn't the right primitive.
</Warning>

<Warning>
  Coverage is broad but not guaranteed. A handful of less-liquid tickers may occasionally return empty.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // No date boundaries — the most recent 30 trading days
    {
      "method": "tools/call",
      "params": {
        "name": "equity_historical_prices",
        "arguments": { "ticker": "AAPL", "limit": 30 }
      }
    }

    // Earliest 10 bars inside an explicit window
    {
      "method": "tools/call",
      "params": {
        "name": "equity_historical_prices",
        "arguments": {
          "ticker": "MSFT",
          "start_date": "2025-04-01",
          "end_date": "2025-04-30",
          "limit": 10,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # No date boundaries — most recent bars
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/historical",
        headers=headers,
        params={"ticker": "AAPL", "limit": 30},
    ).json()
    for bar in resp["data"]["prices"]:
        print(f"{bar['time']}  C={bar['close']:.2f}  V={bar['volume']}")

    # Earliest 10 bars inside a bounded window
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/historical",
        headers=headers,
        params={
            "ticker": "MSFT",
            "start_date": "2025-04-01",
            "end_date": "2025-04-30",
            "limit": 10,
            "take_from": "earliest",
        },
    ).json()
    print(f"Bounded query returned {len(resp['data']['prices'])} bars")
    ```

    ```bash cURL theme={null}
    # No date boundaries — most recent bars
    curl "https://api.llmquantdata.com/api/equity/historical?ticker=AAPL&limit=30" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # Earliest 10 bars inside a bounded window
    curl "https://api.llmquantdata.com/api/equity/historical?ticker=MSFT&start_date=2025-04-01&end_date=2025-04-30&limit=10&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="equity_historical_prices — request parameters" icon="sliders">
  <ParamField type="string">
    US equity ticker (e.g. `AAPL`, `MSFT`, `BRK.B`, `^GSPC` for S\&P 500 index).
  </ParamField>

  <ParamField type="string">
    Optional inclusive lower boundary in `YYYY-MM-DD` (e.g. `2025-04-01`).
  </ParamField>

  <ParamField type="string">
    Optional inclusive upper boundary in `YYYY-MM-DD`.
  </ParamField>

  <ParamField type="integer">
    Maximum trading days to return after boundary filtering. Default `30`. Max `200`.
  </ParamField>

  <ParamField type="string">
    Which side of the filtered window to keep when more than `limit` bars match. Use `latest` or `earliest`; output remains chronological.
  </ParamField>

  <Warning>
    `take_from=earliest` requires `start_date`. If both date boundaries are provided, `start_date` must not be after `end_date`.
  </Warning>
</Accordion>

## Related

<Columns>
  <Card title="Equity Intraday Prices" icon="clock" href="/en/api/prices/equity-intraday">
    `1h` regular-session bars for the same US equities — the short-lookback companion.
  </Card>

  <Card title="Crypto Historical Klines" icon="chart-line" href="/en/api/prices/crypto-historical">
    Same bounded historical-series shape for crypto pairs at sub-daily intervals.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# Equity Intraday Prices
Source: https://docs.llmquantdata.com/en/api/prices/equity-intraday

1h regular-session OHLCV bars for US equities — recent N bars, or a date window of up to 14 calendar days, US market hours only.

<Note icon="sparkles">
  **Available as MCP tool**: `equity_intraday_prices` — call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>1 credit per call</Badge>

## What it does for your agent

`equity_intraday_prices` returns **1h** OHLCV bars for a single US equity (NYSE / NASDAQ) during the **regular trading session**. Use it as the **intraday pricing primitive** an agent reaches for when answering "how did this trade today / over the last few sessions, did it gap, did it reverse, how did it close" — without pulling overly fine minute-level data.

It is the short-lookback companion to [`equity_historical_prices`](/en/api/prices/equity-historical): same equity-bars family, same response envelope, but intraday bars. Use `start_date` and/or `end_date` to filter the candidate window, then `limit` and `take_from` choose which edge to keep. The queried window is capped at **14 calendar days**. Only **closed bars** are returned — the in-progress bar is never included.

## Response

<ResponseField name="data" type="EquityIntradayResult">
  <Expandable title="EquityIntradayResult fields">
    <ResponseField name="ticker" type="string">
      The stock ticker symbol (e.g. `AAPL`).
    </ResponseField>

    <ResponseField name="interval" type="string">
      Always `"1h"` — only hourly bars are supported.
    </ResponseField>

    <ResponseField name="prices" type="EquityIntradayBar[]">
      Hourly bars in chronological order. Regular-session, closed bars only.

      <Expandable title="EquityIntradayBar fields">
        <ResponseField name="open" type="number">Opening price of the bar.</ResponseField>
        <ResponseField name="high" type="number">High price of the bar.</ResponseField>
        <ResponseField name="low" type="number">Low price of the bar.</ResponseField>
        <ResponseField name="close" type="number">Closing price of the bar.</ResponseField>
        <ResponseField name="volume" type="number">Trading volume during the bar.</ResponseField>
        <ResponseField name="time" type="string">Bar start time as an ISO 8601 UTC timestamp (e.g. `2026-06-18T14:30:00Z`).</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Credits consumed (always `1`).</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

```json title="200 OK · equity_intraday_prices" expandable theme={null}
{
  "data": {
    "ticker": "AAPL",
    "interval": "1h",
    "prices": [
      {
        "open": 181.20,
        "high": 181.95,
        "low": 180.85,
        "close": 181.60,
        "volume": 4821000,
        "time": "2026-06-18T13:30:00Z"
      },
      {
        "open": 181.60,
        "high": 182.40,
        "low": 181.40,
        "close": 182.10,
        "volume": 3950000,
        "time": "2026-06-18T14:30:00Z"
      }
    ]
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

## Notes

<Tip>
  `time` is an ISO 8601 **UTC** timestamp marking the start of each bar. Bars cover the US regular session, so convert to `America/New_York` if you need exchange-local hours.
</Tip>

<Tip>
  Use `data.prices.length` when you need the returned bar count; `meta` is reserved for credits and optional notices.
</Tip>

<Warning>
  **Hourly interval only.** Minute-level (`1m`, `5m`, `15m`) and `30m` bars are not exposed. Pass `interval=1h` or omit it; any other value returns a `400` error.
</Warning>

<Warning>
  **Regular session only.** Pre-market and after-hours bars are not included. For full trading days, use [`equity_historical_prices`](/en/api/prices/equity-historical).
</Warning>

<Warning>
  **No real-time quote.** The current, still-forming bar is excluded until it closes. For the latest tick, this tool isn't the right primitive.
</Warning>

<Warning>
  **14 calendar days maximum.** The queried window must span 14 calendar days or less, inclusive of both boundaries; a wider window returns `400` and costs no credits. The cap is measured against the **effective** window: when `end_date` is omitted it defaults to the current US Eastern date, so `start_date=2015-01-01` on its own is also rejected. Narrow the window, or use [`equity_historical_prices`](/en/api/prices/equity-historical) for daily bars over longer periods.
</Warning>

<Warning>
  The response is bounded by `limit` (default `35`, max `70`). For long-term history, use daily bars.
</Warning>

## Direct invocation

<Accordion title="HTTP / SDK examples" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // Recent mode — last 35 bars (~5 trading days)
    {
      "method": "tools/call",
      "params": {
        "name": "equity_intraday_prices",
        "arguments": { "ticker": "AAPL", "limit": 35 }
      }
    }

    // Earliest 10 bars inside an explicit window
    {
      "method": "tools/call",
      "params": {
        "name": "equity_intraday_prices",
        "arguments": {
          "ticker": "MSFT",
          "start_date": "2026-06-08",
          "end_date": "2026-06-18",
          "limit": 10,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # Recent mode
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/intraday",
        headers=headers,
        params={"ticker": "AAPL", "limit": 35},
    ).json()
    for bar in resp["data"]["prices"]:
        print(f"{bar['time']}  C={bar['close']:.2f}  V={bar['volume']}")

    # Earliest 10 bars inside a bounded window
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/intraday",
        headers=headers,
        params={
            "ticker": "MSFT",
            "start_date": "2026-06-08",
            "end_date": "2026-06-18",
            "limit": 10,
            "take_from": "earliest",
        },
    ).json()
    print(f"Bounded query returned {len(resp['data']['prices'])} bars")
    ```

    ```bash cURL theme={null}
    # Recent mode
    curl "https://api.llmquantdata.com/api/equity/intraday?ticker=AAPL&limit=35" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # Earliest 10 bars inside a bounded window
    curl "https://api.llmquantdata.com/api/equity/intraday?ticker=MSFT&start_date=2026-06-08&end_date=2026-06-18&limit=10&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## Full parameter reference

<Accordion title="equity_intraday_prices — request parameters" icon="sliders">
  <ParamField type="string">
    US equity ticker (e.g. `AAPL`, `MSFT`, `BRK.B`, `^GSPC` for S\&P 500 index).
  </ParamField>

  <ParamField type="string">
    Bar interval. Only `1h` is supported; any other value returns a `400` error.
  </ParamField>

  <ParamField type="string">
    Optional inclusive lower trading-date boundary in `YYYY-MM-DD` (interpreted in `America/New_York`). The window it opens must stay within 14 calendar days of `end_date` — or of the current US Eastern date when `end_date` is omitted.
  </ParamField>

  <ParamField type="string">
    Optional inclusive upper trading-date boundary in `YYYY-MM-DD` (interpreted in `America/New_York`). Defaults to the current US Eastern date.
  </ParamField>

  <ParamField type="integer">
    Maximum `1h` bars to return after boundary filtering. Default `35`. Max `70`.
  </ParamField>

  <ParamField type="string">
    Which side of the filtered window to keep when more than `limit` bars match. Use `latest` or `earliest`; output remains chronological.
  </ParamField>

  <Warning>
    `take_from=earliest` requires `start_date`. If both date boundaries are provided, `start_date` must not be after `end_date`. Either way, the resulting window must be 14 calendar days or less, otherwise the call returns `400` and costs no credits.
  </Warning>
</Accordion>

## Related

<Columns>
  <Card title="Equity Historical Prices" icon="chart-line" href="/en/api/prices/equity-historical">
    Daily OHLCV bars with adjusted close, dividends, and splits — the long-lookback companion.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>


# Authentication
Source: https://docs.llmquantdata.com/en/authentication

One API key — used as an env var by your MCP client, or as an HTTP header for direct calls.

<Note icon="key">
  Generate keys in the [Dashboard → API Keys](https://llmquantdata.com/dashboard).
</Note>

<Warning>
  Treat your API key like a password. Never commit it to source control, never expose it in client-side code, never paste it into a chat session.
</Warning>

## Get your API key

<Steps>
  <Step title="Sign in" icon="user">
    Go to [llmquantdata.com](https://llmquantdata.com) and sign up (or log in).
  </Step>

  <Step title="Create an API key" icon="key">
    Open the [Dashboard](https://llmquantdata.com/dashboard) → **API Keys** → **Create API key**. Copy it once — it won't be shown again.
  </Step>

  <Step title="Store as env var" icon="terminal">
    ```bash theme={null}
    export LLMQUANT_API_KEY=your_api_key_here
    ```

    Add it to your shell profile (`~/.zshrc`, `~/.bashrc`) for persistence. Both MCP and HTTP usage below read from this single source.
  </Step>
</Steps>

## How to use it

<Tabs>
  <Tab title="MCP runtime (recommended)">
    Every supported MCP client (Claude Code, Cursor, Codex, Gemini CLI, Claude Desktop) reads the key from `LLMQUANT_API_KEY`. For JSON config files, paste the actual key value in the `env` block.

    See [MCP Server setup](/en/integration/mcp-server#quick-setup) for the per-client commands.

    ```json title="example: Cursor / Claude Desktop config snippet" theme={null}
    {
      "mcpServers": {
        "llmquant-data": {
          "command": "npx",
          "args": ["-y", "@llmquant/data-mcp"],
          "env": {
            "LLMQUANT_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="HTTP (direct)">
    Pass the key in the `Authorization` header on every request:

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.llmquantdata.com/api/equity/historical?ticker=AAPL&limit=5" \
        -H "Authorization: Bearer $LLMQUANT_API_KEY"
      ```

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

      response = requests.get(
          "https://api.llmquantdata.com/api/equity/historical",
          headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
          params={"ticker": "AAPL", "limit": 5},
      )
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Error codes

| Status             | Meaning                                       |
| ------------------ | --------------------------------------------- |
| <Badge>200</Badge> | Success                                       |
| <Badge>400</Badge> | Bad request — invalid or missing parameters   |
| <Badge>401</Badge> | Unauthorized — invalid or missing API key     |
| <Badge>402</Badge> | Insufficient credits — top up your balance    |
| <Badge>404</Badge> | Not found — ticker or resource does not exist |
| <Badge>429</Badge> | Rate limit exceeded                           |

## Rate limits

Rate limits vary by plan. If you exceed your limit you will receive a `429` response. Contact us to discuss higher limits.

<Tip>
  An MCP runtime that retries silently on `429` can burn credits fast. Inspect the agent's tool-call log when debugging unexpected billing.
</Tip>

## Replace or revoke a key

To replace a key, create a new one in [Dashboard → API Keys](https://llmquantdata.com/dashboard), update your environments, then revoke the old key. Requests that use a revoked key return `401`.

<Warning>
  Before revoking the old key, update `LLMQUANT_API_KEY` in **every** environment that uses MCP — your shell profile, your CI secrets, your team's onboarding templates.
</Warning>


# MCP Server
Source: https://docs.llmquantdata.com/en/integration/mcp-server

The knowledge harness for AI-native finance — drop in once, every agent picks it up.

<Note icon="sparkles">
  **`@llmquant/data-mcp`** — one config gives every MCP-compatible agent access to 26 financial and personal-context tools. Source on [`LLMQuant/data-mcp`](https://github.com/LLMQuant/data-mcp).
</Note>

<Badge icon="circle-check">Live</Badge>
 
<Badge>npm · @llmquant/data-mcp</Badge>

## Why MCP

LLMQuant Data is built **agent-first**. The REST API exists as a fallback; the canonical interface is the [Model Context Protocol](https://modelcontextprotocol.io) — a standard that lets any agent runtime (Claude, Cursor, Codex, Gemini CLI, OpenClaw, ChatGPT custom GPTs…) **call our data tools natively**, with structured arguments and typed results, no glue code.

<Tip>
  **Configure once — every environment below picks it up.**
</Tip>

## Where it runs

<Columns>
  <Card title="Chatbots" icon="message">
    ChatGPT · Claude · Cursor
  </Card>

  <Card title="Agent CLIs" icon="terminal">
    Claude Code · Codex · Gemini CLI · OpenClaw
  </Card>

  <Card title="SDKs" icon="code">
    LangGraph · Google ADK · Vercel AI SDK
  </Card>
</Columns>

If your runtime speaks MCP, LLMQuant Data is one config away.

## Remote connectors

Claude web, Claude iOS, and other cloud-hosted agents cannot run a local `npx` stdio server. Use the hosted Streamable HTTP endpoint instead:

<Steps>
  <Step title="Generate a Remote MCP URL" icon="link">
    Sign in to the [Dashboard](https://llmquantdata.com/dashboard) → **Connect** → **Remote MCP URL**. Copy the URL once when it is created.

    ```text theme={null}
    https://mcp.llmquantdata.com/u/lqd_mcp_.../mcp
    ```
  </Step>

  <Step title="Paste it into Claude custom connectors" icon="plug">
    Choose Claude's **No Authentication** connector mode and paste the full URL. The token lives in the URL path, is stored hashed by LLMQuant Data, and can be revoked from the Dashboard without rotating your API key.
  </Step>

  <Step title="Verify credit and revoke behavior" icon="circle-check">
    Run a paid search or read tool, confirm the Dashboard balance changes, then revoke a test URL and confirm it fails immediately.
  </Step>
</Steps>

<Note>
  Local desktop and CLI clients can keep using the stdio setup below. Remote URLs are for cloud clients and synced Claude connectors that need a public HTTPS MCP endpoint.
</Note>

## Quick setup

<Steps>
  <Step title="Get an API key" icon="key">
    Sign in to the [Dashboard](https://llmquantdata.com/dashboard) → **API Keys** → **Create API key**. Store it as an environment variable named `LLMQUANT_API_KEY`.
  </Step>

  <Step title="Add data-mcp to your client" icon="plug">
    **Drop this prompt into your agent — it will read the canonical setup from GitHub:**

    ```text theme={null}
    Install the LLMQuant data-mcp server in this environment by following https://github.com/LLMQuant/data-mcp
    ```

    <Accordion title="Or install manually" icon="terminal">
      Pick your runtime below. Each block is the canonical config — drop it in, save, restart the client.

      <Tabs>
        <Tab title="Claude Code">
          ```bash theme={null}
          claude mcp add llmquant-data \
            -e LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
            -- npx -y @llmquant/data-mcp
          ```
        </Tab>

        <Tab title="Cursor">
          Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
          JSON config files usually do not expand shell variables, so paste your actual API key value.

          ```json title=".cursor/mcp.json" theme={null}
          {
            "mcpServers": {
              "llmquant-data": {
                "command": "npx",
                "args": ["-y", "@llmquant/data-mcp"],
                "env": {
                  "LLMQUANT_API_KEY": "your_api_key_here"
                }
              }
            }
          }
          ```
        </Tab>

        <Tab title="Codex CLI">
          ```bash theme={null}
          codex mcp add llmquant-data \
            --env LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
            -- npx -y @llmquant/data-mcp
          ```
        </Tab>

        <Tab title="Gemini CLI">
          ```bash theme={null}
          gemini mcp add -s user \
            -e LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
            llmquant-data \
            npx -y @llmquant/data-mcp
          ```
        </Tab>

        <Tab title="Claude Desktop">
          Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`):
          JSON config files usually do not expand shell variables, so paste your actual API key value.

          ```json title="claude_desktop_config.json" theme={null}
          {
            "mcpServers": {
              "llmquant-data": {
                "command": "npx",
                "args": ["-y", "@llmquant/data-mcp"],
                "env": {
                  "LLMQUANT_API_KEY": "your_api_key_here"
                }
              }
            }
          }
          ```
        </Tab>

        <Tab title="Other (stdio)">
          Any MCP client supporting stdio transport accepts this generic config:
          JSON config files usually do not expand shell variables, so paste your actual API key value.

          ```json theme={null}
          {
            "mcpServers": {
              "llmquant-data": {
                "command": "npx",
                "args": ["-y", "@llmquant/data-mcp"],
                "env": {
                  "LLMQUANT_API_KEY": "your_api_key_here"
                }
              }
            }
          }
          ```

          Don't see your client? [Open an issue](https://github.com/LLMQuant/data-mcp/issues) and we'll add it.
        </Tab>
      </Tabs>
    </Accordion>
  </Step>

  <Step title="Ask the agent something it should now know" icon="sparkles">
    Restart the client. Then drop one of these into any chat / agent session — the agent will discover the new tools, pick the right one, and return structured results.

    <Prompt description="Wiki two-step lookup">
      Search the Quant Wiki for "momentum factor" and read the top result.
    </Prompt>

    <Prompt description="Live crypto check">
      What's BTC trading at right now? And what's its 24h change?
    </Prompt>

    <Prompt description="Research discovery">
      Find recent papers on transformer-based factor models.
    </Prompt>
  </Step>
</Steps>

## Available tools

Each tool is one MCP capability the agent can invoke. Pricing is per-call, billed in credits.

| Tool                            | What it does                                                                                                                                                       | Credits |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-----: |
| `wiki_search`                   | Semantic search over 50,000+ Quant Wiki entries                                                                                                                    |    1    |
| `wiki_read`                     | Load the full markdown body of a wiki item by ID                                                                                                                   |    0    |
| `paper_search`                  | Semantic search over 1,200+ research paper summaries                                                                                                               |    1    |
| `paper_read`                    | Read specific sections of a paper (intro, methods, conclusion…)                                                                                                    |    0    |
| `crypto_historical_klines`      | Crypto OHLCV candles with configurable interval                                                                                                                    |    1    |
| `crypto_snapshot`               | Latest spot price + 24h stats for a crypto pair                                                                                                                    |    0    |
| `polymarket_event_browse`       | List or exact-filter finance-scoped Prediction Markets events                                                                                                      |    1    |
| `polymarket_event_search`       | Semantic search over finance-scoped Prediction Markets events                                                                                                      |    2    |
| `polymarket_event_read`         | Read one Prediction Markets event card with child market previews                                                                                                  |    0    |
| `polymarket_market_read`        | Read one Prediction Markets market card with outcomes and outcome token ids                                                                                        |    0    |
| `polymarket_price_history`      | Hourly or daily implied-probability history for one outcome token                                                                                                  |    0    |
| `equity_historical_prices`      | US equity daily OHLCV + dividend / split adjustments. Also serves ETF price history.                                                                               |    0    |
| `equity_intraday_prices`        | US equity `1h` regular-session OHLCV bars (trading-day window; max 14 calendar days for the effective window—an omitted `end_date` uses the current New York date) |    1    |
| `etf_lookup`                    | ETF basic info + top holdings summary + sector / country / asset-type exposure                                                                                     |    0    |
| `etf_holdings`                  | Full ETF holdings (latest available SEC regulatory disclosure snapshot, sorted by weight). Tickers outside coverage still return `200`, no credit charge.          |    1    |
| `macro_indicator_search`        | Browse 50+ curated macro indicators                                                                                                                                |    0    |
| `macro_indicator_history`       | Historical observations for a macro series                                                                                                                         |    1    |
| `macro_indicator_snapshot`      | Latest value for a macro indicator                                                                                                                                 |    0    |
| `sec_filing_browse`             | Browse SEC 10-K / 10-Q / 8-K filing metadata                                                                                                                       |    0    |
| `sec_filing_read`               | Read specific sections of a SEC filing                                                                                                                             |    1    |
| `sec_13f_list_manager_holdings` | A manager's 13F holdings (Top 1,000 × at least the last 4 quarters)                                                                                                |    1    |
| `sec_13f_list_ticker_holders`   | Institutional holders of a ticker (Top 1,000 × at least the last 4 quarters)                                                                                       |    1    |
| `sec_13f_list_top_managers`     | Top N smart-money managers ranked by 13F reportable value                                                                                                          |    0    |
| `news_browse`                   | Browse recent company news by ticker, event, topic, or date                                                                                                        |    2    |
| `personal_holdings`             | Read the holdings you saved in Dashboard → Profile (your own account only)                                                                                         |    0    |
| `personal_profile`              | Read the financial profile you saved in Dashboard → Profile (your own account only)                                                                                |    0    |

<Tip>
  More data products, including fundamentals and earnings transcripts, are on the [roadmap](https://github.com/LLMQuant/data-mcp#roadmap).
</Tip>

## Environment variables

<ParamField type="string">
  Your LLMQuant Data API key. Generate at [Dashboard → API Keys](https://llmquantdata.com/dashboard).
</ParamField>

<ParamField type="string">
  Override the API base URL. Useful for self-hosted proxies or another compatible LLMQuant Data deployment.
</ParamField>

<ParamField type="number">
  Request timeout in milliseconds. Max `120000`.
</ParamField>

## What's next

<Columns>
  <Card title="Browse the data tools" icon="book-open" href="/en/api/knowledge/wiki-search">
    Each tool maps 1:1 to an endpoint page with `Agent flow` diagram + response schema.
  </Card>

  <Card title="Source on GitHub" icon="github" href="https://github.com/LLMQuant/data-mcp">
    Read the source, file an issue, and follow the roadmap.
  </Card>
</Columns>


# Introduction
Source: https://docs.llmquantdata.com/en/introduction

AI-native financial data platform for developers and AI agents

# LLMQuant Data API

LLMQuant Data provides unified access to financial data and proprietary quantitative knowledge — built for developers and AI agents.

<CardGroup>
  <Card title="Proprietary Knowledge" icon="book-open" href="/en/api/knowledge/wiki-search">
    50,000+ Quant Wiki entries and 1,200+ research paper summaries — semantic search + read.
  </Card>

  <Card title="Market Data" icon="chart-line" href="/en/market-coverage">
    US equities (30+ years OHLCV), crypto klines & snapshot, 50+ curated macro indicators.
  </Card>

  <Card title="SEC & Smart Money" icon="file-invoice" href="/en/api/filings/13f-top-managers">
    10-K / 10-Q / 8-K filing browse + read. Form 13F: Top 1,000 institutional managers, at least the last 4 quarters.
  </Card>

  <Card title="MCP Server" icon="plug" href="/en/integration/mcp-server">
    Drop-in `@llmquant/data-mcp` for Claude / Cursor / Codex / Gemini CLI — every tool, one config.
  </Card>
</CardGroup>

## Quick Start

<Steps>
  <Step title="Get your API key" icon="key">
    Sign in to the [Dashboard](https://llmquantdata.com/dashboard) and copy a key from the **API Keys** section. Store it as an env var:

    ```bash theme={null}
    export LLMQUANT_API_KEY=your_api_key_here
    ```

    <Tip>
      Never hardcode the key in source. See [Authentication](/en/authentication) for details.
    </Tip>
  </Step>

  <Step title="Connect via MCP (recommended)" icon="plug">
    Native MCP integration — your agent calls 26 data and personal-context tools directly, no glue code.

    **Drop this prompt into your agent — it will read the canonical setup from GitHub:**

    ```text theme={null}
    Install the LLMQuant data-mcp server in this environment by following https://github.com/LLMQuant/data-mcp
    ```

    <Accordion title="Or install manually" icon="terminal">
      <CodeGroup>
        ```bash Claude Code theme={null}
        claude mcp add llmquant-data \
          -e LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
          -- npx -y @llmquant/data-mcp
        ```

        ```bash Codex CLI theme={null}
        codex mcp add llmquant-data \
          --env LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
          -- npx -y @llmquant/data-mcp
        ```

        ```bash Gemini CLI theme={null}
        gemini mcp add -s user \
          -e LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
          llmquant-data \
          npx -y @llmquant/data-mcp
        ```
      </CodeGroup>

      Cursor, Claude Desktop, or another MCP runtime? See the full [MCP Server setup](/en/integration/mcp-server).
    </Accordion>
  </Step>

  <Step title="Try it from your agent" icon="sparkles">
    Restart the client, then drop one of these into the chat:

    <Prompt description="Wiki research">
      Search the Quant Wiki for "momentum factor" and read the top result.
    </Prompt>

    <Prompt description="Live price check">
      What's BTC trading at right now?
    </Prompt>
  </Step>

  <Step title="Or call the HTTP API directly" icon="terminal">
    Not on an MCP runtime? Hit the REST API directly at `https://api.llmquantdata.com`:

    ```python theme={null}
    import os, requests

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}
    url = "https://api.llmquantdata.com/api/equity/historical?ticker=AAPL&limit=5"
    print(requests.get(url, headers=headers).json())
    ```

    Browse the reference docs in the sidebar for every endpoint.
  </Step>
</Steps>


# Market Coverage
Source: https://docs.llmquantdata.com/en/market-coverage

What markets, assets, and reference datasets are covered by LLMQuant Data.

LLMQuant Data ships **10 data product universes** today, plus more on the [roadmap](https://github.com/LLMQuant/data-mcp#roadmap). Every universe is exposed as one or more MCP tools (see [MCP Server](/en/integration/mcp-server)) and as a REST endpoint.

## <Icon icon="book-open" /> Proprietary Knowledge

<Badge icon="circle-check">Live</Badge>

| Dataset     | Description                                                  | Count            |
| ----------- | ------------------------------------------------------------ | ---------------- |
| Quant Wiki  | Quantitative finance concepts, formulas, factors, strategies | 50,000+ entries  |
| Quant Paper | Curated summaries of academic finance papers                 | 1,200+ summaries |

Two-step lookup pattern (`*_search` → `*_read`) keeps agent context cheap.

## <Icon icon="chart-line" /> US Equities

<Badge icon="circle-check">Live</Badge>

* **Exchanges**: NYSE · NASDAQ · AMEX
* **History**: Up to 30+ years of daily OHLCV
* **Intraday**: `1h` regular-session bars over a short lookback via [`equity_intraday_prices`](/en/api/prices/equity-intraday)
* **Universe**: 10,000+ tickers (active and delisted)
* **Adjustments**: Dividends and splits applied

## <Icon icon="layer-group" /> ETFs

<Badge icon="circle-check">Live</Badge>

* **Disclosure basis**: SEC official regulatory disclosure snapshots — **not** issuer daily books, with multi-week to \~60-day publication lag
* **Currently covered**: `SPY` · `QQQ` · `VTI` · `SOXX` · `ARKK` (with more curated popular ETFs added over time)
* **Outside coverage** still return `200 OK`, `coverage_status="unsupported"` + an explicit notice — **never** silently empty. Currently outside: `IBIT` · `DRAM`
* **Two endpoints**:
  * `etf_lookup` — ETF basic info + top holdings summary + sector / country / asset-type exposure (free)
  * `etf_holdings` — full position list, sorted by weight descending (1 credit; 0 for tickers outside coverage)
* **Pricing**: ETF OHLCV history is served by [`equity_historical_prices`](/en/api/prices/equity-historical) — ETFs trade like stocks on the daily-bar contract
* **Coverage state**: every response carries `coverage_status` (`full` / `partial` / `stale` / `unsupported`), `as_of_date`, and `coverage_notice`; agents should branch on `coverage_status` before consuming data

## <Icon icon="bitcoin-sign" /> Crypto

<Badge icon="circle-check">Live</Badge>

* **Pairs**: 500+ spot pairs (BTC, ETH, SOL, USDT-quoted majors and long-tail)
* **Granularity**: 1h / 4h / 1d / 1w klines + last-trade snapshot

## <Icon icon="gauge-high" /> Prediction Markets

<Badge icon="circle-check">Live</Badge>

* **Scope**: Finance-scoped event cards and market cards
* **Workflow**: `polymarket_event_search` / `polymarket_event_browse` → `polymarket_event_read` → `polymarket_market_read` → `polymarket_price_history`
* **History**: Hourly or daily implied-probability history by returned `outcome_token_id`
* **Docs**: See [Prediction Markets Events](/en/api/prediction-markets/events)

## <Icon icon="landmark" /> Macro Indicators

<Badge icon="circle-check">Live</Badge>

* **Coverage**: Supported U.S. macro indicator catalog
* **Universe**: 50+ indicators across 8 categories — Activity, Labor, Inflation, Rates, Money, External, Markets, Sentiment
* **Series examples**: `CPIAUCSL` · `UNRATE` · `FEDFUNDS` · `GDPC1` · `DGS10`
* **Frequency**: daily · weekly · monthly · quarterly (per series)
* **Revisions**: Returns the latest published vintage, so agents may see revised values instead of the original release

## <Icon icon="file-invoice" /> SEC Filings (10-K / 10-Q / 8-K)

<Badge icon="circle-check">Live</Badge>

* **Filing system**: SEC EDGAR
* **Forms**: 10-K (annual), 10-Q (quarterly), 8-K (current report / events)
* **Universe**: All US public filers
* **Workflow**: `sec_filing_browse` (metadata, free) → `sec_filing_read` (specific item / section)

## <Icon icon="users" /> SEC Form 13F (Smart Money)

<Badge icon="circle-check">Live</Badge>

* **Universe**: Top 1,000 institutional managers per quarter (each quarter has its own Top 1,000), at least the last 4 quarters (actual covered quarters stated in response `meta.notice`)
* **Lenses**:
  * `sec_13f_list_top_managers` — leaderboard by 13F reportable value
  * `sec_13f_list_manager_holdings` — what does manager X hold?
  * `sec_13f_list_ticker_holders` — who holds ticker Y?
* **Use case**: consensus / overlap leaderboards, smart-money momentum, regime tagging

## <Icon icon="gauge-high" /> Prediction Markets

<Badge icon="circle-check">Live</Badge>

* **Coverage**: finance-scoped Prediction Markets event and market cards
* **Workflow**: `polymarket_event_search` for natural-language discovery, `polymarket_event_browse` for list or exact-filter requests, then `polymarket_event_read` / `polymarket_market_read` / `polymarket_price_history`
* **Use case**: probability tracking, event-risk briefs, and market-implied scenario checks

## <Icon icon="newspaper" /> Company News

<Badge icon="circle-check">Live</Badge>

* **Coverage**: continuously updated company news from April 11, 2026 onward
* **Workflow**: call `news_browse` for recent news, then narrow by ticker, event, topic, or date
* **Use case**: company monitoring, earnings recaps, and event-driven research

## <Icon icon="file-invoice-dollar" /> Financial Statements

<Badge icon="clock">Coming Soon</Badge>

Standardized line-items across all US public filers. Coverage will include:

* Income statements, balance sheets, cash flow statements
* Annual (10-K) and quarterly (10-Q) frequency
* Trailing twelve months (TTM) aggregations

## <Icon icon="compass" /> On the roadmap

<Badge>Planned</Badge>

Earnings call transcripts · company fundamentals. Track progress on the [data-mcp roadmap](https://github.com/LLMQuant/data-mcp#roadmap).


# ETF 持仓明细
Source: https://docs.llmquantdata.com/zh-CN/api/etf/holdings

查询单只美国上市 ETF 的最新或指定日期前可用持仓明细，字段已整理统一，并按权重从高到低排序。

<Note icon="sparkles">
  **可作为 MCP 工具调用**：`etf_holdings` —— 可在 Claude / Cursor / 任意 MCP 客户端中直接使用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>每次 1 credit（不在覆盖范围时 0）</Badge>

## 它为 Agent 做什么

`etf_holdings` 返回单只美国上市 ETF 的**完整持仓表**，可以查最新可用申报，也可以用 `as_of` 回看某个日期前已经公开的申报。返回行数受 `limit` 限制；每行都整理成同一套 `EtfHolding` 字段，包括 `ticker` / `cusip` / `isin` / `sedol`、`weight`、`market_value`、`shares`，以及 `sector` / `country` / `asset_type`。结果按 `weight` 从高到低排列。

当 agent 需要逐条持仓时用它：算前十大占比、HHI，比较两只 ETF 的重合持仓，或从某只 ETF 的底层成分里挑主题股票。如果只是想知道这只 ETF 是什么、前几大持仓是什么，优先用免费的 [`etf_lookup`](/zh-CN/api/etf/lookup)。

这个接口对平台「动作执行完成就扣费」的规则有一个登记在案的例外：把暂不支持的 ticker 当作免费的**覆盖检查**，而不是一次持仓取数。支持名单里的 ticker 会返回持仓并扣 1 credit；暂不支持的 ticker 会返回 `200 OK`、`coverage_status="unsupported"` 和空 `holdings`，**不扣 credit**。这是只针对 ETF Holdings 的明确例外，不是平台上「没数据就免费」的通用规则。传 `as_of=YYYY-MM-DD` 可取 `as_of_date <= as_of` 的最近申报；比较两只 ETF 的持仓重合仍由 agent 自己计算。

## 返回值

<ResponseField name="data" type="EtfHoldingsResult">
  <Expandable title="EtfHoldingsResult 字段">
    <ResponseField name="ticker" type="string">
      ETF ticker，服务端会转成大写。
    </ResponseField>

    <ResponseField name="fund_name" type="string">
      基金显示名称。`coverage_status="unsupported"` 时为 `null`。
    </ResponseField>

    <ResponseField name="issuer" type="string">
      基金发行方 / 管理方。
    </ResponseField>

    <ResponseField name="holdings" type="EtfHolding[]">
      持仓明细，按 `weight` 从高到低返回。`coverage_status="unsupported"` 时为空数组。

      <Expandable title="EtfHolding 字段">
        <ResponseField name="holding_name" type="string">持仓名称（按申报文件原文）。</ResponseField>

        <ResponseField name="ticker" type="string">
          底层资产 ticker。**债券、现金、衍生品、crypto trust 经常没有 ticker** —— 这时用 `cusip` / `isin` 识别。
        </ResponseField>

        <ResponseField name="cusip" type="string">CUSIP。比较两只基金的重合持仓时优先用它对齐。</ResponseField>
        <ResponseField name="isin" type="string">ISIN。CUSIP 缺失时再用它对齐。</ResponseField>
        <ResponseField name="sedol" type="string">SEDOL（申报文件提供时返回）。</ResponseField>

        <ResponseField name="asset_type" type="string">
          `equity` / `fixed_income` / `cash` / `derivative` / `crypto` / `other`。
        </ResponseField>

        <ResponseField name="sector" type="string">行业分类，可能为 `null`。</ResponseField>
        <ResponseField name="country" type="string">国家 / 地区，可能为 `null`。</ResponseField>
        <ResponseField name="shares" type="number">持有数量（股 / 份）。</ResponseField>
        <ResponseField name="market_value" type="number">市值（USD）。</ResponseField>

        <ResponseField name="weight" type="number">
          组合权重，小数形式（例如 `0.071` 表示 7.1%）。
        </ResponseField>

        <ResponseField name="notional_value" type="number">
          衍生品和特殊资产的名义本金，可能为 `null`。
        </ResponseField>

        <ResponseField name="source" type="string">本行数据所来自的 SEC 披露数据集标识。</ResponseField>
        <ResponseField name="source_url" type="string">相关 SEC 披露数据集链接，可用于引用。</ResponseField>
        <ResponseField name="as_of_date" type="string">本行对应的监管披露报告日。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="source" type="string">顶层数据所来自的 SEC 披露数据集标识。</ResponseField>
    <ResponseField name="source_url" type="string">顶层相关 SEC 披露数据集链接，可用于引用。</ResponseField>
    <ResponseField name="as_of_date" type="string">这份公开申报对应的日期（`YYYY-MM-DD`）。如果传了 `as_of`，这里是 `<= as_of` 的最近可用日期。</ResponseField>
    <ResponseField name="fetched_at" type="string">LLMQuant Data 上次更新这份持仓数据的 ISO 时间戳。</ResponseField>
    <ResponseField name="stale" type="boolean">如果数据已经偏旧，或者本次刷新降级，这里是 `true`。</ResponseField>

    <ResponseField name="coverage_status" type="string">
      `full` / `partial` / `stale` / `unsupported` 之一。
    </ResponseField>

    <ResponseField name="coverage_notice" type="string">
      当前支持情况说明，始终返回。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">
  `full` / `partial` / `stale` 数据返回时为 `1`；`coverage_status="unsupported"` 时为 `0`。
</ResponseField>

<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · etf_holdings（supported）" expandable theme={null}
{
  "data": {
    "ticker": "SPY",
    "fund_name": "SPDR S&P 500 ETF Trust",
    "issuer": "State Street",
    "holdings": [
      {
        "holding_name": "APPLE INC",
        "ticker": "AAPL",
        "cusip": "037833100",
        "isin": "US0378331005",
        "sedol": null,
        "asset_type": "equity",
        "sector": "Information Technology",
        "country": "US",
        "shares": 168000000,
        "market_value": 30450000000,
        "weight": 0.071,
        "notional_value": null,
        "source": "sec_nport",
        "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
        "as_of_date": "2019-09-30"
      },
      {
        "holding_name": "MICROSOFT CORP",
        "ticker": "MSFT",
        "cusip": "594918104",
        "isin": "US5949181045",
        "sedol": null,
        "asset_type": "equity",
        "sector": "Information Technology",
        "country": "US",
        "shares": 78000000,
        "market_value": 27890000000,
        "weight": 0.065,
        "notional_value": null,
        "source": "sec_nport",
        "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
        "as_of_date": "2019-09-30"
      }
    ],
    "source": "sec_nport",
    "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
    "as_of_date": "2019-09-30",
    "fetched_at": "2026-05-12T03:14:00Z",
    "stale": false,
    "coverage_status": "full",
    "coverage_notice": "Latest available SEC regulatory disclosure snapshot. Not the issuer's daily latest holdings."
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

```json title="200 OK · etf_holdings（不在覆盖范围）" expandable theme={null}
{
  "data": {
    "ticker": "IBIT",
    "fund_name": null,
    "issuer": null,
    "holdings": [],
    "source": "sec_nport",
    "source_url": null,
    "as_of_date": null,
    "fetched_at": null,
    "stale": false,
    "coverage_status": "unsupported",
    "coverage_notice": "IBIT is not in the current covered ETF list. As a spot Bitcoin trust, its SEC disclosure path differs from the conventional ETFs we cover today."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## 扣费规则

| 覆盖结果                                | HTTP  |          `creditsUsed`          |
| ----------------------------------- | ----- | :-----------------------------: |
| `full` / `partial` / `stale`（持仓已返回） | `200` |               `1`               |
| `unsupported`（没有持仓，但明确说明不支持）        | `200` |               `0`               |
| 调用方余额不足 **且** ticker 在覆盖范围内         | `402` |           n/a —— 不返回持仓          |
| 调用方余额不足 **且** ticker 不在覆盖范围         | `200` | `0` —— 即使没有 credit，也会返回“不支持”的说明 |

简单说：查“支不支持”这个动作不扣费，真的返回持仓明细才扣 1 credit。这个「不支持就免费」的行为是只针对 ETF Holdings 的、登记在案的明确例外 —— 其它接口都是动作一执行就扣费，哪怕结果为空。

## 说明

<Tip>
  **比较两只 ETF 的持仓重合**：分别调两次 `etf_holdings`，再由 agent 自己比较。**优先按 `cusip` 对齐**，其次 `isin`，最后 `ticker` —— 债券、现金、衍生品经常没有 ticker，但 CUSIP 等稳定标识通常有。
</Tip>

<Tip>
  **集中度指标**（Top-10 权重、HHI）拿到持仓行后很好算。返回已经按权重从高到低排好，直接取前几行即可。
</Tip>

<Tip>
  在调本接口前，可以先用免费的 [`etf_lookup`](/zh-CN/api/etf/lookup) 确认是否支持，再看 `holdings_count` 决定 `limit`。`VTI` 这类宽基 ETF 可能有上千条持仓；默认 `limit=50` 对多数问题已经够用。
</Tip>

### 当前限制

<Warning>
  **不是当日 / 每日持仓**。这些行来自最近一份 SEC 公开申报，通常按月或按季度披露，公开发布时间会滞后；不是基金公司内部的当天底仓。`as_of_date` 会告诉你这份数据对应哪一天。
</Warning>

<Warning>
  **行级 `ticker` 可能为空**。债券、现金、衍生品、crypto trust 经常没有 ticker。识别和对齐持仓时，一定要回退到 CUSIP / ISIN。
</Warning>

<Warning>
  **不提供服务端 `etf_compare_holdings`**。跨 ETF 持仓重合、权重差异、篮子比较，都由 agent 调两次 `etf_holdings` 后自己算。
</Warning>

<Warning>
  **只支持单点历史查询**。`as_of` 选择某一天或以前的最近申报；不支持区间查询、季度号查询或一次返回多期数据。
</Warning>

<Warning>
  **覆盖范围有限**。当前覆盖 `SPY`、`QQQ`、`VTI`、`SOXX`、`ARKK` 等精选热门 ETF。`IBIT` / `DRAM` 当前不在覆盖范围。
</Warning>

<Warning>
  **仅使用监管披露**。基金公司的 fact-sheet PDF 和其他非监管披露数据暂不用于这个接口。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 默认 —— 按权重前 50
    {
      "method": "tools/call",
      "params": {
        "name": "etf_holdings",
        "arguments": { "ticker": "SPY" }
      }
    }

    // 自定义 limit + 按日期回看
    {
      "method": "tools/call",
      "params": {
        "name": "etf_holdings",
        "arguments": { "ticker": "VTI", "limit": 200, "as_of": "2025-10-01" }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    resp = requests.get(
        "https://api.llmquantdata.com/api/etf/holdings",
        headers=headers,
        params={"ticker": "VTI", "limit": 50, "as_of": "2025-10-01"},
    ).json()
    d = resp["data"]
    if d["coverage_status"] == "unsupported":
        print(f"暂不支持: {d['coverage_notice']}")
    else:
        top10_weight = sum(h["weight"] or 0 for h in d["holdings"][:10])
        print(f"{d['ticker']} 申报日 {d['as_of_date']}  前十大权重: {top10_weight:.1%}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/etf/holdings?ticker=VTI&limit=50&as_of=2025-10-01" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="etf_holdings —— 请求参数" icon="sliders">
  <ParamField type="string">
    美国上市 ETF ticker（如 `SPY`、`QQQ`、`VTI`、`SOXX`、`ARKK`）。大小写不敏感；服务端会转成大写并去掉前后空格。暂不支持的 ticker 返回 `200 OK`、`coverage_status="unsupported"`，且 `creditsUsed=0`。
  </ParamField>

  <ParamField type="integer">
    返回的持仓行数上限，按 `weight` 从高到低排列。默认 `50`，最大 `500`。宽基 ETF（如 `VTI`）底层持仓可能超过最大值；分页以后再加。
  </ParamField>

  <ParamField type="string">
    可选报告日期，格式 `YYYY-MM-DD`。返回 `as_of_date <= as_of` 的最近一份持仓申报；不传则返回最新可用申报。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="ETF 基本信息" icon="magnifying-glass" href="/zh-CN/api/etf/lookup">
    基金基本信息、SEC 映射、前几大持仓和分布概览 —— 免费。
  </Card>

  <Card title="美股历史日线" icon="chart-line" href="/zh-CN/api/prices/equity-historical">
    ETF 历史价格用股票日线接口查。
  </Card>

  <Card title="MCP Server 接入" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒把 Claude / Cursor 等客户端接上。
  </Card>
</Columns>


# ETF 基本信息
Source: https://docs.llmquantdata.com/zh-CN/api/etf/lookup

查询单只美国上市 ETF 的名称、发行方、SEC 注册信息、最新或指定日期前可用的持仓申报，以及前几大持仓和分布概览。

<Note icon="sparkles">
  **可作为 MCP 工具调用**：`etf_lookup` —— 可在 Claude / Cursor / 任意 MCP 客户端中直接使用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · 0 credit</Badge>

## 它为 Agent 做什么

`etf_lookup` 用来先回答“一只 ETF 到底是什么”。它会返回基金名称、发行方、资产类型、SEC 注册信息，以及最新或某个日期前已经公开的持仓申报。它还会给出前几大持仓和行业 / 国家 / 资产类型分布，方便 agent 判断要不要继续拉完整持仓表。

它**不查价格**。ETF 历史价格请用 [`equity_historical_prices`](/zh-CN/api/prices/equity-historical)，因为 ETF 价格走和股票一样的日线接口。如果要回看某个日期以前已经公开的持仓，传 `as_of=YYYY-MM-DD`；返回的是那天以前最近一份公开申报，**不是基金公司当天内部持仓**。

不在当前支持名单里的 ticker（例如 `IBIT` / `DRAM`）也会返回 `200 OK`，并通过 `coverage_status="unsupported"` 和 `coverage_notice` 明确告诉你暂不支持，**不会**用空结果假装查到了数据。

## 返回值

<ResponseField name="data" type="EtfLookupResult">
  <Expandable title="EtfLookupResult 字段">
    <ResponseField name="ticker" type="string">
      ETF ticker，服务端会转成大写，例如 `SPY`。
    </ResponseField>

    <ResponseField name="fund_name" type="string">
      基金显示名称。`coverage_status="unsupported"` 时为 `null`。
    </ResponseField>

    <ResponseField name="issuer" type="string">
      基金发行方 / 管理方（如 `State Street`、`Vanguard`、`Invesco`、`BlackRock`）。
    </ResponseField>

    <ResponseField name="asset_class" type="string">
      `equity` / `fixed_income` / `commodity` / `crypto` / `multi_asset` / `other`。
    </ResponseField>

    <ResponseField name="category" type="string">
      基金分类标签（如 `Large Blend`、`Semiconductors`）。
    </ResponseField>

    <ResponseField name="cik" type="string">SEC 注册人 CIK。</ResponseField>
    <ResponseField name="series_id" type="string">SEC Investment Company Series ID。</ResponseField>
    <ResponseField name="class_id" type="string">SEC Class ID。</ResponseField>

    <ResponseField name="expense_ratio" type="number">
      费用率。来自 SEC 公开申报；可能为 `null`。
    </ResponseField>

    <ResponseField name="aum" type="number">AUM（USD），可能为 `null`。</ResponseField>
    <ResponseField name="nav" type="number">最新 NAV，可能为 `null`。</ResponseField>
    <ResponseField name="market_price" type="number">最新市价，可能为 `null`。</ResponseField>
    <ResponseField name="premium_discount_pct" type="number">相对 NAV 的溢价 / 折价，可能为 `null`。</ResponseField>
    <ResponseField name="inception_date" type="string">基金成立日（`YYYY-MM-DD`）。</ResponseField>

    <ResponseField name="holdings_count" type="number">
      这份申报里的持仓条数。可用它判断要不要再调用 `etf_holdings`。
    </ResponseField>

    <ResponseField name="top_holdings" type="array">
      前几大持仓摘要（通常按权重取前 10）。要完整持仓表请调 [`etf_holdings`](/zh-CN/api/etf/holdings)。
    </ResponseField>

    <ResponseField name="sector_exposure" type="array">
      行业分布，可能为 `null`。
    </ResponseField>

    <ResponseField name="country_exposure" type="array">
      国家分布，可能为 `null`。
    </ResponseField>

    <ResponseField name="asset_type_exposure" type="array">
      资产类型分布（equity / fixed\_income / cash / derivative / ...），可能为 `null`。
    </ResponseField>

    <ResponseField name="source" type="string">
      数据所来自的 SEC 监管披露数据集标识。暂不支持的 ticker 也会返回。
    </ResponseField>

    <ResponseField name="source_url" type="string">
      所依据的 SEC 披露数据集链接，可用于引用。
    </ResponseField>

    <ResponseField name="as_of_date" type="string">
      这份公开申报对应的日期（`YYYY-MM-DD`）。如果传了 `as_of`，这里是 `<= as_of` 的最近可用日期。**不是抓取时间，也不等于“今天”。**
    </ResponseField>

    <ResponseField name="fetched_at" type="string">
      LLMQuant Data 上次更新这只 ETF 基本资料和持仓摘要的 ISO 时间戳。
    </ResponseField>

    <ResponseField name="stale" type="boolean">
      如果数据已经偏旧，或者本次刷新只能返回较旧可用数据，这里是 `true`。
    </ResponseField>

    <ResponseField name="coverage_status" type="string">
      `full` / `partial` / `stale` / `unsupported` 之一。含义见 [覆盖说明](#覆盖说明)。
    </ResponseField>

    <ResponseField name="coverage_notice" type="string">
      面向用户和 agent 的说明：当前支持到什么程度，或者为什么暂不支持。始终返回。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— lookup 免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · etf_lookup（supported）" expandable theme={null}
{
  "data": {
    "ticker": "SPY",
    "fund_name": "SPDR S&P 500 ETF Trust",
    "issuer": "State Street",
    "asset_class": "equity",
    "category": "Large Blend",
    "cik": "0000884394",
    "series_id": "S000004310",
    "class_id": "C000012075",
    "expense_ratio": 0.0945,
    "aum": null,
    "nav": null,
    "market_price": null,
    "premium_discount_pct": null,
    "inception_date": "1993-01-22",
    "holdings_count": 503,
    "top_holdings": [
      { "ticker": "AAPL", "holding_name": "APPLE INC", "weight": 0.071 },
      { "ticker": "MSFT", "holding_name": "MICROSOFT CORP", "weight": 0.065 }
    ],
    "sector_exposure": [
      { "sector": "Information Technology", "weight": 0.297 },
      { "sector": "Financials", "weight": 0.135 }
    ],
    "country_exposure": [{ "country": "US", "weight": 0.99 }],
    "asset_type_exposure": [{ "asset_type": "equity", "weight": 0.995 }],
    "source": "sec_nport",
    "source_url": "https://www.sec.gov/dera/data/form-n-port-data-sets",
    "as_of_date": "2019-09-30",
    "fetched_at": "2026-05-12T03:14:00Z",
    "stale": false,
    "coverage_status": "full",
    "coverage_notice": "Latest available SEC regulatory disclosure snapshot. Not the issuer's daily latest holdings."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

```json title="200 OK · etf_lookup（不在覆盖范围）" expandable theme={null}
{
  "data": {
    "ticker": "IBIT",
    "fund_name": null,
    "issuer": null,
    "asset_class": null,
    "category": null,
    "cik": null,
    "series_id": null,
    "class_id": null,
    "expense_ratio": null,
    "aum": null,
    "nav": null,
    "market_price": null,
    "premium_discount_pct": null,
    "inception_date": null,
    "holdings_count": null,
    "top_holdings": null,
    "sector_exposure": null,
    "country_exposure": null,
    "asset_type_exposure": null,
    "source": "sec_nport",
    "source_url": null,
    "as_of_date": null,
    "fetched_at": null,
    "stale": false,
    "coverage_status": "unsupported",
    "coverage_notice": "IBIT is not in the current covered ETF list. As a spot Bitcoin trust, its SEC disclosure path differs from the conventional ETFs we cover today; we may add a dedicated path later."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## 覆盖说明

| `coverage_status` | 表示什么                                      | `stale`          |
| ----------------- | ----------------------------------------- | ---------------- |
| `full`            | 当前支持这只 ticker；基本资料和持仓申报都能返回。              | `false`（通常）      |
| `partial`         | 当前支持这只 ticker，但有些字段拿不到；缺失字段返回 `null`。     | `false` / `true` |
| `stale`           | 曾经有数据，但最近刷新失败或数据已经偏旧，所以返回较旧可用数据。          | `true`           |
| `unsupported`     | 当前**不支持**这只 ticker。仍返回 `200 OK`，但会明确说明原因。 | `false`          |

先看 `coverage_status` 再读其他字段：如果是 `unsupported`，不要把空字段理解成“这只 ETF 真的没有持仓”。

## 说明

<Tip>
  **配合 [`etf_holdings`](/zh-CN/api/etf/holdings) 使用**：如果只看概览，`etf_lookup` 返回的前几大持仓通常够用；只有需要完整持仓、具体权重，或比较两只 ETF 的重合持仓时，再调 `etf_holdings`。
</Tip>

<Tip>
  查 ETF 的**历史价格**不要用这个接口。请用 [`equity_historical_prices`](/zh-CN/api/prices/equity-historical) 配合 ETF ticker；ETF 价格和股票一样走日线价格接口。
</Tip>

<Tip>
  `lookup` 不扣 credit，但仍会记一条使用记录。可以先用它确认这只 ETF 是否支持，再决定要不要调用会扣费的 `etf_holdings`。
</Tip>

### 当前限制

<Warning>
  **覆盖范围有限**。目前只支持一批热门 ETF（如 `SPY`、`QQQ`、`VTI`、`SOXX`、`ARKK`）。不支持的 ticker 会返回 `coverage_status="unsupported"`，不会静默返回空结果。我们**还不**覆盖整个美国 ETF 市场。
</Warning>

<Warning>
  **这是公开申报数据，不是每日持仓**。持仓和分布来自 SEC 公开数据集，通常会比真实持仓晚几十天到约 60 天。`as_of_date` 是申报报告日，**不是“今天的持仓”**。
</Warning>

<Warning>
  **`IBIT` / `DRAM` 当前暂不支持**。`IBIT` 是现货 BTC trust，披露路径和当前支持的传统 ETF 不一样；`DRAM` 当前不在覆盖范围。两者都会返回 `coverage_status="unsupported"`。
</Warning>

<Warning>
  **仅使用监管披露**。基金公司的 fact-sheet PDF 暂不用于这个接口，所以 `expense_ratio` / `aum` / `nav` / `market_price` / `premium_discount_pct` 可能为 `null`。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 按日期回看 —— 取 2025-10-01 当天或以前最近一份申报
    {
      "method": "tools/call",
      "params": {
        "name": "etf_lookup",
        "arguments": { "ticker": "VTI", "as_of": "2025-10-01" }
      }
    }

    // 不支持的 ticker —— 200 OK，coverage_status="unsupported"
    {
      "method": "tools/call",
      "params": {
        "name": "etf_lookup",
        "arguments": { "ticker": "IBIT" }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    resp = requests.get(
        "https://api.llmquantdata.com/api/etf/lookup",
        headers=headers,
        params={"ticker": "VTI", "as_of": "2025-10-01"},
    ).json()
    d = resp["data"]
    if d["coverage_status"] == "unsupported":
        print(f"暂不支持: {d['coverage_notice']}")
    else:
        print(f"{d['ticker']} · {d['fund_name']} · {d['holdings_count']} 条持仓 · "
              f"申报日 {d['as_of_date']} (stale={d['stale']})")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/etf/lookup?ticker=VTI&as_of=2025-10-01" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="etf_lookup —— 请求参数" icon="sliders">
  <ParamField type="string">
    美国上市 ETF ticker（如 `SPY`、`QQQ`、`VTI`、`SOXX`、`ARKK`）。大小写不敏感；服务端会转成大写并去掉前后空格。只接受 `A-Z`、`0-9`、`.`、`-`。暂不支持的 ticker 返回 `200 OK` 和 `coverage_status="unsupported"`。
  </ParamField>

  <ParamField type="string">
    可选报告日期，格式 `YYYY-MM-DD`。返回 `as_of_date <= as_of` 的最近一份公开申报；不传则返回最新可用申报。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="ETF 持仓明细" icon="layer-group" href="/zh-CN/api/etf/holdings">
    单只 ETF 的完整持仓表，按权重从高到低返回。
  </Card>

  <Card title="美股历史日线" icon="chart-line" href="/zh-CN/api/prices/equity-historical">
    ETF 历史价格用股票日线接口查。
  </Card>

  <Card title="MCP Server 接入" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒把 Claude / Cursor 等客户端接上。
  </Card>
</Columns>


# 13F 按机构查持仓
Source: https://docs.llmquantdata.com/zh-CN/api/filings/13f-by-manager

列出某个机构投资人某季度的完整 SEC Form 13F 持仓 —— "这只基金在持什么？"的正向查询。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`sec_13f_list_manager_holdings` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>每次 1 credit</Badge>

## 它做什么

查一只基金某一季的全部 13F-HR 持仓。传 `manager_cik`（机构 SEC 编号）或 `manager_name`（机构名）+ 可选的 `year` + `quarter`，返回该机构那一季每条持仓的详细信息：股票编号（CUSIP）、ticker、持仓市值、股数、投票权、是不是期权。

`manager_name` 只是简单匹配（精确 → 别名 → 前缀模糊），**不是**自然语言搜索，不接受长句。匹配不到返回 200 OK + 空 `data` + `meta.notice`；匹配出多个返回 `400 invalid_request`，需要传 `manager_cik` 消歧。

覆盖范围是被查那一季的 Top 1000 机构（每个季度有各自的 Top 1000）；该季范围之外的 `manager_cik` 或 `(year, quarter)` 返回空数据 + `meta.notice` 说明。

## 返回值

<ResponseField name="data" type="ManagerHoldingsResult">
  <Expandable title="ManagerHoldingsResult 字段">
    <ResponseField name="ranking_period" type="string">
      本次响应数据所属的季度（YYYY-MM-DD），= 你传入的 (year, quarter) 对应的季末日期。
    </ResponseField>

    <ResponseField name="manager" type="object">
      解析后的机构身份与 AUM proxy。

      <Expandable title="manager 字段">
        <ResponseField name="manager_cik" type="string">SEC CIK。</ResponseField>
        <ResponseField name="manager_name" type="string">规范化的机构名称。</ResponseField>
        <ResponseField name="match_type" type="string">解析方式：`cik` / `exact` / `alias` / `fuzzy`。</ResponseField>
        <ResponseField name="latest_reportable_value_usd" type="number">**Manager 整体最新规模**（与请求季度无关）；最新一季 13F reportable value（AUM proxy）。</ResponseField>
        <ResponseField name="latest_reportable_value_period" type="string">上一字段对应的季度。</ResponseField>
        <ResponseField name="period_rank" type="integer">该机构在 `ranking_period` 这季的排名（无该季 ranking 时为 null）。</ResponseField>
        <ResponseField name="period_reportable_value_usd" type="number">该机构在 `ranking_period` 这季的 reportable value（USD）。</ResponseField>
        <ResponseField name="is_in_covered_manager_set" type="boolean">是否在 `ranking_period` 这季覆盖的 Top 1000 机构集合内 —— 按季判断，因为每个季度有各自的 Top 1000。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="filing" type="object">
      命中的 13F-HR filing 标识。

      <Expandable title="filing 字段">
        <ResponseField name="filing_type" type="string">`13F-HR` 或 `13F-HR/A`（修订）。</ResponseField>
        <ResponseField name="accession_number" type="string">SEC 受理号。</ResponseField>
        <ResponseField name="filed_at" type="string">提交日期（`YYYY-MM-DD`）。</ResponseField>
        <ResponseField name="period_of_report" type="string">报告期季末。</ResponseField>
        <ResponseField name="is_amendment" type="boolean">是否修订件。</ResponseField>
        <ResponseField name="table_entry_total" type="integer">原 filing 持仓总条数。</ResponseField>
        <ResponseField name="table_value_total" type="number">原 filing 持仓总市值。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="holdings" type="Holding[]">
      持仓数组，按 `value_usd` 倒序。

      <Expandable title="Holding 字段">
        <ResponseField name="cusip" type="string">CUSIP。</ResponseField>
        <ResponseField name="ticker" type="string">映射到的美股 ticker（现金、期权、未上市可能为 null）。</ResponseField>
        <ResponseField name="name_of_issuer" type="string">发行人名称（原文）。</ResponseField>
        <ResponseField name="title_of_class" type="string">证券类别（如 `COM`）。</ResponseField>
        <ResponseField name="value_usd" type="number">持仓市值（USD）。</ResponseField>
        <ResponseField name="shares" type="number">股数（或本金）。</ResponseField>
        <ResponseField name="shares_type" type="string">`SH`（股）或 `PRN`（本金）。</ResponseField>
        <ResponseField name="investment_discretion" type="string">`SOLE` / `SHARED` / `NONE` / `DFND`。</ResponseField>
        <ResponseField name="voting_sole" type="number">独立投票权股数。</ResponseField>
        <ResponseField name="voting_shared" type="number">共享投票权股数。</ResponseField>
        <ResponseField name="voting_none" type="number">无投票权股数。</ResponseField>
        <ResponseField name="put_call" type="string">`PUT` / `CALL`，非期权时为 `null`。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">本次调用后的剩余 credits。</ResponseField>
<ResponseField name="meta.notice" type="string">需要说明覆盖范围或空结果时返回的人话说明。</ResponseField>

```json title="200 OK · sec_13f_list_manager_holdings" expandable theme={null}
{
  "data": {
    "ranking_period": "2025-12-31",
    "manager": {
      "manager_cik": "1067983",
      "manager_name": "BERKSHIRE HATHAWAY INC",
      "match_type": "alias",
      "latest_reportable_value_usd": 302459211458,
      "latest_reportable_value_period": "2025-12-31",
      "period_rank": 7,
      "period_reportable_value_usd": 302459211458,
      "is_in_covered_manager_set": true
    },
    "filing": {
      "filing_type": "13F-HR",
      "accession_number": "0000950123-26-001234",
      "filed_at": "2026-02-14",
      "period_of_report": "2025-12-31",
      "is_amendment": false,
      "table_entry_total": 110,
      "table_value_total": 302459211458
    },
    "holdings": [
      {
        "cusip": "025816109",
        "ticker": "AXP",
        "name_of_issuer": "AMERICAN EXPRESS CO",
        "title_of_class": "COM",
        "value_usd": 55145133598,
        "shares": 149061045,
        "shares_type": "SH",
        "investment_discretion": "SOLE",
        "voting_sole": 149061045,
        "voting_shared": 0,
        "voting_none": 0,
        "put_call": null
      }
    ]
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 999,
    "notice": "13F coverage: Top 1,000 managers for quarter 2025-12-31 (each quarter has its own Top 1,000). Ranking data available for 4 quarters: 2025-03-31 … 2025-12-31. Reportable value is an AUM proxy excluding fixed income, options, non-U.S. holdings, and shorts."
  }
}
```

## 说明

<Tip>
  **canonical 工作流**：本工具与 `sec_13f_list_top_managers`（取 Top N 基金池）和 `sec_13f_list_ticker_holders`（"谁持有 X？"反向查询）配合使用。Consensus / overlap 分析的标准模式是：先枚举 top manager → 对每个 manager 调一次本工具 → 客户端聚合。
</Tip>

<Tip>
  **典型 agent 问法**：本工具只返回单季持仓，跨季度变化需要 agent 自己调两次再对比。下面这类问题 agent 可以自然处理：

  <Prompt description="某 manager 的某季持仓">
    Berkshire 2025 Q4 的 13F 持仓是什么？前 10 大持仓是哪些？
  </Prompt>

  <Prompt description="同 manager 跨季度持仓变化">
    Berkshire 这两季 13F 持仓对比一下，加仓最多的是哪只票？清仓了哪些？新进了哪些？
  </Prompt>
</Tip>

<Warning>
  **仅 Top 1000 范围**。超出覆盖范围的 `manager_cik` 返回 200 OK + 空 `data` + `meta.notice`。
</Warning>

<Warning>
  错误：`manager_name` 解析不到 → 200 OK + 空 `data` + `meta.notice`。`manager_name` 解析出多个候选 → `400 invalid_request`；请传 `manager_cik` 消歧。
</Warning>

<Warning>
  暂不支持 confidential / 延迟披露持仓。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_manager_holdings",
        "arguments": {
          "manager_name": "Berkshire Hathaway",
          "year": 2025,
          "quarter": 4,
          "limit": 200
        }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/filings/13f/by-manager",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"manager_name": "Berkshire Hathaway", "year": 2025, "quarter": 4},
    ).json()
    manager = resp["data"]["manager"]
    for h in resp["data"]["holdings"][:10]:
        label = h["ticker"] or h["cusip"]
        print(f"{label:<8} ${h['value_usd']:>15,}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/filings/13f/by-manager?manager_name=Berkshire%20Hathaway&year=2025&quarter=4" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="sec_13f_list_manager_holdings — 请求参数" icon="sliders">
  <ParamField type="string">
    机构 SEC CIK 号（如 Berkshire Hathaway 的 `1067983`）。两者同时传时 `manager_cik` 优先；不一致返回 `400`。
  </ParamField>

  <ParamField type="string">
    机构名称自由文本（如 `Bridgewater`、`Berkshire Hathaway`）。服务端走 `exact → alias → 轻量 fuzzy` 解析。
  </ParamField>

  <ParamField type="integer">
    要查询的季度所在年（如 `2025`）。范围 `[2013, 2030]`。**必须与 `quarter` 同传或同省**；省略则返回该机构最新已覆盖季度。
  </ParamField>

  <ParamField type="integer">
    要查询的季度 `1-4`（Q1=Jan-Mar，Q4=Oct-Dec）。**必须与 `year` 同传或同省**。
  </ParamField>

  <ParamField type="integer">
    最多返回的持仓数。默认 `200`，最大 `500`。
  </ParamField>

  <Warning>
    `manager_cik` 与 `manager_name` 至少传一个。
  </Warning>
</Accordion>

## 相关接口

<Columns>
  <Card title="13F 按 Ticker 查持有人" icon="rotate" href="/zh-CN/api/filings/13f-by-ticker">
    反向查询 —— Top 1000 中谁持有这只 ticker？
  </Card>

  <Card title="13F 头部机构枚举" icon="ranking-star" href="/zh-CN/api/filings/13f-top-managers">
    枚举覆盖的 Top 1000 机构集合，作为 fund pool 起点。
  </Card>

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


# 13F 按 Ticker 查持有人
Source: https://docs.llmquantdata.com/zh-CN/api/filings/13f-by-ticker

反向查询 Top 1000 中持有某只美股的机构列表 —— 13F 反向查询。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`sec_13f_list_ticker_holders` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>每次 1 credit</Badge>

## 它做什么

查"谁持有某只美股"。传 ticker + 可选的 `year` + `quarter`，返回那一季 Top 1000 机构里持有这只票的列表 —— 每条带这家机构当季的持仓市值、股数，加上这家机构本身在 Top 1000 里的排名和规模。默认按持仓市值倒序。

`BRK.B` 这类带点的 ticker 服务端会自动改写成 `BRK-B`；查不到的 ticker 返回空列表（不是 404）。本工具是参数化查询，不是语义搜索。覆盖范围只到那一季的 Top 1000 机构（每个季度有各自的 Top 1000），**不是**全市场所有持有该股票的 13F 申报人 —— 长尾小机构、零售投资人都不在里面。

## 返回值

<ResponseField name="data" type="TickerHoldersResult">
  <Expandable title="TickerHoldersResult 字段">
    <ResponseField name="ticker" type="string">归一化后的 ticker（如 `BRK.B → BRK-B`）。</ResponseField>
    <ResponseField name="ranking_period" type="string">所对应的季末日期（`YYYY-MM-DD`），= 你传入的 (year, quarter) 对应季末。</ResponseField>

    <ResponseField name="total_holders_in_scope" type="integer">
      Top 1000 内持有该 ticker 的机构数（≤ 1000）。用它判断 cohort 规模再决定下一步。
    </ResponseField>

    <ResponseField name="aggregate_value_usd" type="number">
      所有 in-scope 持有人的 `value_usd` 之和。
    </ResponseField>

    <ResponseField name="holders" type="HolderEntry[]">
      默认按 `value_usd` 倒序。

      <Expandable title="HolderEntry 字段">
        <ResponseField name="manager_cik" type="string">持有人 CIK。</ResponseField>
        <ResponseField name="manager_name" type="string">规范化的机构名称。</ResponseField>
        <ResponseField name="manager_period_reportable_value_usd" type="number">该 manager 在 `ranking_period` 这季的 13F reportable value（AUM proxy）。**该季排名数据暂不可用时为 null** —— 持仓仍会返回，只是缺这一项排名数值。</ResponseField>
        <ResponseField name="manager_period_of_report" type="string">上一字段对应的季度；ranking 缺失时为 null。</ResponseField>
        <ResponseField name="manager_period_rank" type="integer">该 manager 在 `ranking_period` 这季的 Top 1000 排名；ranking 缺失时为 null。</ResponseField>
        <ResponseField name="accession_number" type="string">SEC 受理号。</ResponseField>
        <ResponseField name="cusip" type="string">持仓 CUSIP。</ResponseField>
        <ResponseField name="title_of_class" type="string">证券类别。</ResponseField>
        <ResponseField name="value_usd" type="number">持仓市值（USD）。</ResponseField>
        <ResponseField name="shares" type="number">股数。</ResponseField>
        <ResponseField name="shares_type" type="string">`SH` 或 `PRN`。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">本次调用后的剩余 credits。</ResponseField>
<ResponseField name="meta.notice" type="string">需要说明覆盖范围或空结果时返回的人话说明。</ResponseField>

```json title="200 OK · sec_13f_list_ticker_holders" expandable theme={null}
{
  "data": {
    "ticker": "NVDA",
    "ranking_period": "2025-12-31",
    "total_holders_in_scope": 187,
    "aggregate_value_usd": 123456789000,
    "holders": [
      {
        "manager_cik": "1067983",
        "manager_name": "BERKSHIRE HATHAWAY INC",
        "manager_period_reportable_value_usd": 302459211458,
        "manager_period_of_report": "2025-12-31",
        "manager_period_rank": 7,
        "accession_number": "0000950123-26-001234",
        "cusip": "67066G104",
        "title_of_class": "COM",
        "value_usd": 1234567890,
        "shares": 9000000,
        "shares_type": "SH"
      }
    ]
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 999,
    "notice": "Holders list is restricted to the Top 1,000 manager set; not full-market ownership. 13F coverage: Top 1,000 managers for quarter 2025-12-31 (each quarter has its own Top 1,000). Ranking data available for 4 quarters: 2025-03-31 … 2025-12-31. Reportable value is an AUM proxy excluding fixed income, options, non-U.S. holdings, and shorts."
  }
}
```

## 说明

<Tip>
  **canonical 工作流**：本反向查询与 `sec_13f_list_top_managers`（确定 covered manager set 规模）以及 `sec_13f_list_manager_holdings`（钻进单只基金的全部持仓）配合使用。本工具回答 "谁持有 X？"，正向工具回答 "这只基金在持什么？"。
</Tip>

<Tip>
  用 `manager_period_rank` 和 `manager_period_reportable_value_usd` 在客户端做过滤 —— 比如只展示持有人中 Top 30 的机构，避免大量长尾小持仓干扰。
</Tip>

<Tip>
  **典型 agent 问法**：本工具只返回单季持有人名单，跨季度变化需要 agent 自己调两次再对比。

  <Prompt description="某 ticker 的某季持有人">
    最近一季 13F 里，NVDA 在 smart money 中有哪些机构持仓？按市值前 20 列出来。
  </Prompt>

  <Prompt description="同 ticker 跨季度持有人变化">
    NVDA 这两季的 smart money 持有人对比一下，谁新进的？谁退出的？谁加仓最多？
  </Prompt>

  注意覆盖范围仅那一季的 Top 1000 covered manager set，不是全市场持有人；某机构两季的可见性差异也可能来自"它本季掉出那季的 Top 1000"而不是真的"退出该股"，agent 解读时要小心。
</Tip>

<Warning>
  **仅 Top 1000 机构 scope**，**不是**全市场持有人。那一季 covered manager set 之外的基金（以及零售 / 直接持有人）不在结果里。
</Warning>

<Warning>
  如果被查季度的 Top 1000 里没有机构持有该 ticker，工具返回 `200 OK` + 空 `holders` + `meta.notice`。
</Warning>

<Warning>
  暂不支持 confidential / 延迟披露持仓。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_ticker_holders",
        "arguments": { "ticker": "NVDA", "year": 2025, "quarter": 4, "limit": 100 }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/filings/13f/by-ticker",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"ticker": "NVDA", "year": 2025, "quarter": 4, "limit": 50},
    ).json()
    data = resp["data"]
    print(f"{data['ticker']} {data['ranking_period']}: {data['total_holders_in_scope']} holders")
    for h in data["holders"][:10]:
        print(f"  #{h['manager_period_rank']:>4}  {h['manager_name']:<40}  ${h['value_usd']:>15,}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/filings/13f/by-ticker?ticker=NVDA&year=2025&quarter=4&limit=50" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="sec_13f_list_ticker_holders — 请求参数" icon="sliders">
  <ParamField type="string">
    美股 ticker（如 `NVDA`、`TSLA`、`AAPL`）。大小写不敏感，服务端自动归一化（`BRK.B → BRK-B`）。
  </ParamField>

  <ParamField type="integer">
    要查询的季度所在年（如 `2025`）。范围 `[2013, 2030]`。**必须与 `quarter` 同传或同省**；省略则默认 = 最新已覆盖季度。
  </ParamField>

  <ParamField type="integer">
    要查询的季度 `1-4`（Q1=Jan-Mar，Q4=Oct-Dec）。**必须与 `year` 同传或同省**。
  </ParamField>

  <ParamField type="integer">
    最多返回的持有人数。默认 `100`，最大 `1000` —— 如需 Top 1000 全量再客户端按 manager AUM proxy 裁剪，可调到上限。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="13F 按机构查持仓" icon="briefcase" href="/zh-CN/api/filings/13f-by-manager">
    正向方向 —— 列出某只基金某季度的全部持仓。
  </Card>

  <Card title="13F 头部机构枚举" icon="ranking-star" href="/zh-CN/api/filings/13f-top-managers">
    枚举覆盖的 Top 1000 机构集合，给持有人 cohort 定大小或做过滤。
  </Card>

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


# 13F 头部机构枚举
Source: https://docs.llmquantdata.com/zh-CN/api/filings/13f-top-managers

按指定季度的 13F reportable value（AUM proxy）枚举该季 SEC Form 13F Top 1000 机构集合中的 Top N 机构投资人 —— 每个季度有各自的 Top 1000，支持跨季度名单与排名对比。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`sec_13f_list_top_managers` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · ranked list</Badge>

## 它做什么

按你指定的季度，列出该季 13F 申报金额最大的前 N 家机构（最多 1000 家）。rank `1` 是那季 13F 申报金额最大的一家。每个季度有各自的 Top 1000，旧季度的结果在新季度发布后保持稳定。

### 两个"季度"字段，现在指向同一季

* **`manager_set_period`** — "这次返回的 Top 1000 是哪一季的"。**等于你查询的那一季**（`year + quarter`）；两个都不传就默认取覆盖到的最新一季。
* **`ranking_period`** — "这次返回的排名和金额是哪一季算的"。**等于 `manager_set_period`** —— 每一季都用它自己的 Top 1000 来返回。

换不同的 `(year, quarter)` 会拿到那一季各自的名单；机构跨季度有进有出，所以名单对比是真实有意义的，而且旧季度的名单在新季度发布后保持稳定。传超出覆盖范围的季度会返回 200 + 空列表 + `meta.notice` 说明。

## 返回值

<ResponseField name="data" type="TopManagersResult">
  <Expandable title="TopManagersResult 字段">
    <ResponseField name="manager_set_period" type="string">
      这次返回的 Top 1000 机构集合所属的季度（YYYY-MM-DD）；等于你查询的那一季（两个都省略时 = 覆盖到的最新一季），且 = `ranking_period`。
    </ResponseField>

    <ResponseField name="ranking_period" type="string">
      本次响应排名/数值所属的季度（YYYY-MM-DD）。等于你传入的 (year, quarter) 对应的季末日期，且 = `manager_set_period`。
    </ResponseField>

    <ResponseField name="managers" type="TopManager[]">
      机构数组，按 `period_rank` 升序。

      <Expandable title="TopManager 字段">
        <ResponseField name="manager_cik" type="string">SEC CIK。</ResponseField>
        <ResponseField name="manager_name" type="string">规范化的机构名称。</ResponseField>

        <ResponseField name="aliases" type="string[]">
          已知别名 / DBA 名称（可能为空数组）。可用于把自然语言里提到的机构名映射回 `manager_cik`。
        </ResponseField>

        <ResponseField name="period_rank" type="integer">
          在 `ranking_period` 这季内的排名（`1` = 该季度 13F reportable value 最大）。
        </ResponseField>

        <ResponseField name="period_reportable_value_usd" type="number">
          `ranking_period` 这季的 13F reportable value（USD）。**AUM proxy，不是真实的全公司 AUM** —— 不含固收、期权、海外、空头。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— 本接口免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">本次调用后的剩余 credits。</ResponseField>

<ResponseField name="meta.notice" type="string">
  数据范围说明；当传入超出覆盖范围的 (year, quarter) 时附加 "has no ranking data"。
</ResponseField>

```json title="200 OK · sec_13f_list_top_managers" expandable theme={null}
{
  "data": {
    "manager_set_period": "2025-12-31",
    "ranking_period": "2025-12-31",
    "managers": [
      {
        "manager_cik": "0001364742",
        "manager_name": "BLACKROCK INC.",
        "aliases": ["BLACKROCK", "BLACKROCK FUND ADVISORS"],
        "period_rank": 1,
        "period_reportable_value_usd": 4521893245678
      },
      {
        "manager_cik": "0000102909",
        "manager_name": "VANGUARD GROUP INC",
        "aliases": ["VANGUARD"],
        "period_rank": 2,
        "period_reportable_value_usd": 4123456789012
      }
    ]
  },
  "meta": {
    "creditsUsed": 0,
    "remainingCredits": 999,
    "notice": "13F coverage: Top 1,000 managers for quarter 2025-12-31 (each quarter has its own Top 1,000). Ranking data available for 4 quarters: 2025-03-31 … 2025-12-31. Reportable value is an AUM proxy excluding fixed income, options, non-U.S. holdings, and shorts."
  }
}
```

## 说明

<Tip>
  **Canonical 工作流 —— Smart Money Consensus 池**：

  1. `sec_13f_list_top_managers?limit=30` —— 拿 Top 30 基金池
  2. 对池里每个 `manager_cik` 调一次 `sec_13f_list_manager_holdings` 拿持仓
  3. 客户端聚合算 consensus / overlap 榜

  本工具 **不返回** 持仓数据 —— 需要扇出。
</Tip>

<Tip>
  **典型 agent 问法**：每个季度有各自的 Top 1000，排名也是按季各自算 —— agent 可以根据下面这类问题自己决定调几次本工具、对比哪几个季度。

  <Prompt description="Top 30 smart money 名单跨季度对比">
    本季和上一季的 13F Top 30 smart money manager 对比一下，谁新进了？谁掉出去了？谁排名变化最大？
  </Prompt>

  <Prompt description="某季 Top N 基金池">
    给我 2025 Q4 13F reportable value 排名前 30 的机构，按 AUM proxy 倒序。
  </Prompt>
</Tip>

<Tip>
  调 `sec_13f_list_manager_holdings` 之前，先用本工具的 `aliases` 把自然语言里提到的 "BlackRock"、"Vanguard" 映射到 canonical `manager_cik`，可以省掉一次走 `manager_name` resolver 的来回。
</Tip>

<Warning>
  **每个季度有各自的 Top 1000 机构集合**：传不同 (year, quarter) 会返回那一季自己的名单 —— 机构跨季度有进有出，所以名单对比是真实有意义的。某个机构会出现在它当季进了 Top 1000 的每一个季度的结果里，而且旧季度的名单在新季度发布后保持稳定。
</Warning>

<Warning>
  **仅 Top 1,000**，按 13F reportable value 排序（AUM proxy，**不是**真实 AUM）。不含固收、期权、海外、空头。
</Warning>

<Warning>
  **不是** semantic / keyword search —— 不支持自然语言 manager 过滤。需要按 manager 名找持仓时用 `sec_13f_list_manager_holdings` 的 `manager_name` 参数。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 取 latest 季度的 Top 30 基金池
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_top_managers",
        "arguments": { "limit": 30 }
      }
    }

    // 2) 取 prev 季度的 Top 30，做名单 diff
    {
      "method": "tools/call",
      "params": {
        "name": "sec_13f_list_top_managers",
        "arguments": { "limit": 30, "year": 2025, "quarter": 3 }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # latest 季度 Top 30
    latest = requests.get(
        f"{base}/api/filings/13f/managers",
        headers=headers,
        params={"limit": 30},
    ).json()["data"]["managers"]

    # 显式指定季度
    prev = requests.get(
        f"{base}/api/filings/13f/managers",
        headers=headers,
        params={"limit": 30, "year": 2025, "quarter": 3},
    ).json()["data"]["managers"]
    ```

    ```bash cURL theme={null}
    # latest 季度 Top 30
    curl "https://api.llmquantdata.com/api/filings/13f/managers?limit=30" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 显式指定季度
    curl "https://api.llmquantdata.com/api/filings/13f/managers?limit=30&year=2025&quarter=3" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="sec_13f_list_top_managers — 请求参数" icon="sliders">
  <ParamField type="integer">
    返回的机构数量，按 `period_rank` 升序。默认 `30`。范围 `[1, 1000]`；服务端 clamp 越界值。
  </ParamField>

  <ParamField type="integer">
    要查询的季度所在年（如 `2025`）。范围 `[2013, 2030]`。**必须与 `quarter` 同传或同省**；省略则默认 = 覆盖到的最新一季。
  </ParamField>

  <ParamField type="integer">
    要查询的季度 `1-4`（Q1=Jan-Mar，Q4=Oct-Dec）。**必须与 `year` 同传或同省**。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="13F 按机构查持仓" icon="briefcase" href="/zh-CN/api/filings/13f-by-manager">
    正向方向 —— 取出一只基金完整持仓（本工具最自然的扇出目标）。
  </Card>

  <Card title="13F 按 Ticker 查持有人" icon="rotate" href="/zh-CN/api/filings/13f-by-ticker">
    反向方向 —— Top 1000 中谁持有这只 ticker？
  </Card>

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


# SEC 申报文件浏览
Source: https://docs.llmquantdata.com/zh-CN/api/filings/browse

按 ticker 列出 SEC 10-K / 10-Q / 8-K 申报文件元数据 —— progressive disclosure 模式的第一步。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`sec_filing_browse` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · listing</Badge>

## 它为 Agent 做什么

`sec_filing_browse` 是 SEC Filing **progressive disclosure 模式的第一步**：给定美股 ticker，返回该公司可用的 10-K / 10-Q / 8-K 元数据列表（不含正文）。agent 用它先发现公司有哪些 filing，再用 `sec_filing_read` 拉取具体章节内容 —— 10-K / 10-Q 用 `year` / `quarter`，8-K 用 `accession_number`（事件驱动，一年多份）。每份 filing 还会带上 `section_keys`（该 filing 可用的章节 code），agent 不读正文就能判断某份 8-K 讲的是什么。

Browse **不是 semantic search**：只接受 ticker + 可选 `filing_type`。不做关键词匹配，不做相关性排序，不接自然语言查询。

## 返回值

<ResponseField name="data" type="Filing[]">
  按 `filing_date` 倒序排列的申报文件数组。

  <Expandable title="Filing 字段">
    <ResponseField name="sec_filing_id" type="string">
      LLMQuant 稳定 filing id，跨请求一致。
    </ResponseField>

    <ResponseField name="ticker" type="string">
      股票代码（统一大写）。
    </ResponseField>

    <ResponseField name="company_name" type="string">
      SEC 提交时记录的公司名称。
    </ResponseField>

    <ResponseField name="filing_type" type="string">
      文件类型 —— `10-K`、`10-Q` 或 `8-K`。
    </ResponseField>

    <ResponseField name="accession_number" type="string">
      SEC 受理号（如 `0000320193-25-000079`）。**把它传给 `sec_filing_read` 可精确定位 filing。**
    </ResponseField>

    <ResponseField name="filing_date" type="string">
      向 SEC 提交的日期（`YYYY-MM-DD`）。
    </ResponseField>

    <ResponseField name="report_date" type="string">
      报告期截止日期（`YYYY-MM-DD`）。SEC 未提供时为 null。
    </ResponseField>

    <ResponseField name="url" type="string">
      SEC EDGAR 原文链接。
    </ResponseField>

    <ResponseField name="section_keys" type="string[]">
      这份 filing 可以读哪些章节 —— 如 8-K `["item2.02","item9.01","ex99.1"]`、10-K `["1","1A","7", …]`。空数组 `[]` 表示暂时还没有。把其中任意 code 传给 `sec_filing_read` 就能取那段。光看 code 也能判断 8-K 是什么：`item2.02` 是财报、`item5.02` 是高管变动，不用先打开看。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— browse 免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · sec_filing_browse" expandable theme={null}
{
  "data": [
    {
      "sec_filing_id": "a1b2c3d4-...",
      "ticker": "AAPL",
      "company_name": "Apple Inc.",
      "filing_type": "10-K",
      "accession_number": "0000320193-25-000079",
      "filing_date": "2025-10-31",
      "report_date": "2025-09-27",
      "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm",
      "section_keys": ["1", "1A", "7", "7A", "8"]
    }
  ],
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## 说明

<Tip>
  **两步检索是 canonical 模式**：`sec_filing_browse` 免费拉 filing 列表，再用 `sec_filing_read`（1 credit）抽取具体章节。把 browse 返回的 `accession_number` 直接传给 read，定位最干净。
</Tip>

<Tip>
  每份 filing 都带 `section_keys` —— 它可用的章节 code 列表。对一年多份、全叫「8-K」的 8-K，这是 agent 不读正文就挑对那份的关键：`item2.02` = earnings、`item5.02` = 高管变动、`ex99.1` = press release 附件。把想要的 code 直接传给 `sec_filing_read` 的 `items`。
</Tip>

<Tip>
  SEC filing 一旦公布就不会再变，结果可长期复用。某 ticker 的首次查询可能略慢，之后秒回。
</Tip>

<Warning>
  **支持 10-K、10-Q 和 8-K**。暂不支持 20-F、proxy（DEF 14A）等其他类型。
</Warning>

<Warning>
  **不支持日期范围过滤**（`filed_at_gte` / `filed_at_lte`），**不支持按 CIK 查询**。只接 `ticker`（+ 可选 `filing_type`）。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "sec_filing_browse",
        "arguments": { "ticker": "AAPL", "filing_type": "10-K", "limit": 10 }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/filings",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"ticker": "AAPL", "filing_type": "10-K", "limit": 10},
    ).json()
    for f in resp["data"]:
        print(f"{f['filing_type']}  {f['filing_date']}  {f['accession_number']}")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/filings?ticker=AAPL&filing_type=10-K&limit=10" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="sec_filing_browse — 请求参数" icon="sliders">
  <ParamField type="string">
    美股 ticker（如 `AAPL`、`MSFT`、`BRK.B`）。
  </ParamField>

  <ParamField type="string">
    按文件类型过滤。可选值：`10-K`、`10-Q`、`8-K`。省略则全部返回。
  </ParamField>

  <ParamField type="integer">
    返回的最大 filing 数。默认 `10`，最大 `50`。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="SEC 申报文件章节读取" icon="file-lines" href="/zh-CN/api/filings/read">
    progressive disclosure 第二步 —— 从指定 filing 抽取具体 item 的完整文本。
  </Card>

  <Card title="13F 头部机构枚举" icon="ranking-star" href="/zh-CN/api/filings/13f-top-managers">
    枚举任意已覆盖季度的 Top 1000 机构集合，作为 consensus 分析的起点。
  </Card>

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


# SEC 申报文件章节读取
Source: https://docs.llmquantdata.com/zh-CN/api/filings/read

提取 SEC 10-K / 10-Q / 8-K 申报文件中具体 item 的全文 —— progressive disclosure 模式的第二步。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`sec_filing_read` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>每次 1 credit</Badge>

## 它为 Agent 做什么

`sec_filing_read` 是 SEC Filing **progressive disclosure 模式的第二步**：在 `sec_filing_browse` 拿到某 ticker 的 filing 列表之后，用本工具抽出某份 filing 中具体 item 的全文（Risk Factors、MD\&A、财务报表、earnings press release 等）。传 `accession_number`（在 browse 后推荐，且 **8-K 必传**）或 `year` / `quarter` + 章节 code，响应里会带上正文 + 该 filing 其他章节的 manifest。传 `items`（数组）可一次取多段、仍只 1 credit；请求里这份 filing 没有的 code 会被直接略过、不报错。

`sec_filing_read` **不是 semantic search**：按 `(ticker, filing_type, accession_number 或 year[+quarter], item)` 做参数化精确查询，返回精确的章节文本 —— 不做相关性排序，不做模糊匹配。

## 返回值

<ResponseField name="data" type="FilingReadResult">
  <Expandable title="FilingReadResult 字段">
    <ResponseField name="ticker" type="string">股票代码。</ResponseField>
    <ResponseField name="filing_type" type="string">文件类型 —— `10-K`、`10-Q` 或 `8-K`。</ResponseField>
    <ResponseField name="accession_number" type="string">命中的 filing 的 SEC 受理号。</ResponseField>
    <ResponseField name="year" type="integer">`period_of_report` 的日历年（8-K 为 `null` —— 事件驱动、无报告期）。</ResponseField>
    <ResponseField name="quarter" type="integer">`period_of_report` 的季度（10-Q 为 1-4；10-K 和 8-K 为 `null`）。</ResponseField>

    <ResponseField name="available_sections" type="SectionManifest[]">
      该 filing 所有可抽取章节的 manifest —— 用来探索还能读哪些 item。

      <Expandable title="SectionManifest 字段">
        <ResponseField name="section_key" type="string">Item code（`1`、`1A`、`7`、`part1item2`、`item2.02` 等）。</ResponseField>
        <ResponseField name="section_title" type="string">章节名称（`Business`、`Risk Factors` 等）。</ResponseField>
        <ResponseField name="ordinal" type="integer">该章节在 filing 内的展示顺序。</ResponseField>
        <ResponseField name="char_count" type="integer">字符数；该章节尚未被读取时为 `0`。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="items" type="Item[]">
      请求的 `items` 对应的章节内容（不指定时返回全部章节）。这份 filing 没有的 code 不会出现在这里 —— 对照 `available_sections` 核对。

      <Expandable title="Item 字段">
        <ResponseField name="number" type="string">Item code（如 `1A`、`part1item2`）。</ResponseField>
        <ResponseField name="name" type="string">章节名称（如 `Risk Factors`、`MD&A`）。</ResponseField>
        <ResponseField name="text" type="string">从 filing 抽取的纯文本正文。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · sec_filing_read" expandable theme={null}
{
  "data": {
    "ticker": "NVDA",
    "filing_type": "10-K",
    "accession_number": "0001045810-26-000021",
    "year": 2025,
    "quarter": null,
    "available_sections": [
      { "section_key": "1", "section_title": "Business", "ordinal": 1, "char_count": 48578 },
      { "section_key": "1A", "section_title": "Risk Factors", "ordinal": 2, "char_count": 32100 },
      { "section_key": "7", "section_title": "MD&A", "ordinal": 10, "char_count": 25400 }
    ],
    "items": [
      {
        "number": "1A",
        "name": "Risk Factors",
        "text": "Item 1A. Risk Factors\n\nOur business, financial condition and operating results may be materially affected by..."
      }
    ]
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  **两步检索是 canonical 模式**：先用 `sec_filing_browse`（免费）拿 filing 列表，挑出想读的 `accession_number`，再用 `sec_filing_read`（1 credit）+ 具体 `item` 抽正文。这样能避开 10-Q 的 `period_of_report` 和 `filed_at` 季度不一致问题。
</Tip>

<Tip>
  抽更多章节前先看 `available_sections[i].char_count` —— Risk Factors、MD\&A 等长 item 动辄几万字。每次只读一个章节，agent context 才不会爆。
</Tip>

<Tip>
  要同一份 filing 的多段？传 `items`（如 `["item2.02","item9.01"]`）一次取回 —— 仍只 1 credit —— 还能跳过没点名的大附件。
</Tip>

<Warning>
  **10-K、10-Q 和 8-K 使用不同的 item code 体系**，参数参考下方表格。混用会返回 `400`。
</Warning>

<Warning>
  **请求的 code 缺失时略过、不报错。** 格式合法但这份 filing 没有的 `item` / `items` code 会从结果里略过（看 `available_sections` 确认实际有哪些）。只有当请求的 code **全都**取不到时才返回 `400`；格式非法的 code（item 体系与 filing type 不匹配）仍返回 `400`。
</Warning>

<Warning>
  10-Q 时**单传 `year` 不够** —— 必须 `year + quarter` 一起传，或者直接传 `accession_number`。10-Q 只传 `year` 会返回 `400`。
</Warning>

<Warning>
  **8-K 必须用 `accession_number` 定位。** 它是事件驱动（一年多份），`year` / `quarter` 无法唯一锁定 —— 先 browse 再用 `accession_number` 读。对 8-K 传 `year` 或 `quarter` 会返回 `400`。
</Warning>

<Warning>
  仅支持纯文本输出，不返回 HTML / 结构化表格。极新 filing 可能需要稍等片刻才能读取。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) Browse 拿 filing 列表
    {
      "method": "tools/call",
      "params": {
        "name": "sec_filing_browse",
        "arguments": { "ticker": "NVDA", "filing_type": "10-K", "limit": 5 }
      }
    }

    // 2) 一次读最新 10-K 的 Risk Factors + MD&A（items 1A、7）
    {
      "method": "tools/call",
      "params": {
        "name": "sec_filing_read",
        "arguments": {
          "ticker": "NVDA",
          "filing_type": "10-K",
          "accession_number": "0001045810-26-000021",
          "items": ["1A", "7"]
        }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) Browse
    filings = requests.get(
        f"{base}/api/filings",
        headers=headers,
        params={"ticker": "NVDA", "filing_type": "10-K", "limit": 5},
    ).json()["data"]

    # 2) 一次读最近一份 10-K 的 items 1A + 7
    latest = filings[0]
    resp = requests.get(
        f"{base}/api/filings/sections",
        headers=headers,
        params={
            "ticker": "NVDA",
            "filing_type": "10-K",
            "accession_number": latest["accession_number"],
            "items": "1A,7",
        },
    ).json()
    print(resp["data"]["items"][0]["text"][:500])
    ```

    ```bash cURL theme={null}
    # 1) Browse
    curl "https://api.llmquantdata.com/api/filings?ticker=NVDA&filing_type=10-K&limit=5" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2) 一次读 items 1A + 7
    curl "https://api.llmquantdata.com/api/filings/sections?ticker=NVDA&filing_type=10-K&accession_number=0001045810-26-000021&items=1A,7" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="sec_filing_read — 请求参数" icon="sliders">
  <ParamField type="string">
    美股 ticker（如 `AAPL`、`NVDA`、`META`）。
  </ParamField>

  <ParamField type="string">
    文件类型 —— `10-K`、`10-Q` 或 `8-K`。
  </ParamField>

  <ParamField type="integer">
    `period_of_report` 的日历年。当 `accession_number` 省略时：10-K **必填**；10-Q 必须与 `quarter` 一起传。8-K 不使用（用 `accession_number` 定位）。
  </ParamField>

  <ParamField type="integer">
    `period_of_report` 的季度（1-4）。仅适用于 10-Q（10-K 和 8-K 会被拒）。10-Q 通过 `year` 查询且不传 `accession_number` 时必填。
  </ParamField>

  <ParamField type="string[]">
    一次取多段。HTTP 用逗号分隔（`items=item2.02,item9.01`），MCP 工具传数组。code 和下面 `item` 一样。最多 25 个，自动去重，仍只算 1 credit。这份 filing 没有的 code 会跳过；全都对不上才返回 `400`。不填就返回全部章节。
  </ParamField>

  <ParamField type="string">
    `items` 的单数别名（仅 HTTP；MCP 工具只暴露 `items`）—— 等价于 `items=[<item>]`。省略则返回所有可抽取章节。

    **10-K item code：** `1`、`1A`、`1B`、`1C`、`2`、`3`、`4`、`5`、`6`、`7`、`7A`、`8`、`9`、`9A`、`9B`、`10`、`11`、`12`、`13`、`14`、`15`。

    **10-Q item code：** `part1item1`、`part1item2`、`part1item3`、`part1item4`、`part2item1`、`part2item1a`、`part2item2`、`part2item3`、`part2item4`、`part2item5`、`part2item6`。

    **8-K item code：** 随 filing 变化（事件驱动）—— 如 `item2.02`（earnings / Results of Operations）、`item5.02`（高管变动）、`item1.01`（重大协议）、`item8.01`（其他事件），外加 `ex99.1`（press release）这类附件。读响应里的 `available_sections` 可看到某份 8-K 实际包含的全集。

    常用组合：10-K `1`（Business）· `1A`（Risk Factors）· `7`（MD\&A）· `8`（财务报表）· `10`（董事/高管）；10-Q `part1item1`（财务报表）· `part1item2`（MD\&A）· `part2item1a`（Risk Factors）。
  </ParamField>

  <ParamField type="string">
    精确 SEC 受理号（如 `0001045810-26-000021`）。在 `sec_filing_browse` 之后推荐用这种方式，且 **8-K 必传**。不能与 `year` / `quarter` 同时使用。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="SEC 申报文件浏览" icon="folder-open" href="/zh-CN/api/filings/browse">
    第 1 步 —— 调 read 之前先列出该 ticker 的可用 filing。
  </Card>

  <Card title="13F 按机构查持仓" icon="briefcase" href="/zh-CN/api/filings/13f-by-manager">
    机构持仓数据 —— 不同的 SEC 申报家族（Form 13F）。
  </Card>

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


# 论文搜索
Source: https://docs.llmquantdata.com/zh-CN/api/knowledge/paper-search

在 LLMQuant Quant Paper 语料上做语义检索 —— 先定位论文，再按需加载具体章节。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`paper_search` + `paper_read` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>1 credit · search</Badge>
 
<Badge>免费 · read</Badge>

## 它为 Agent 做什么

`paper_search` 接收自然语言查询，返回 Quant Paper 中最相关的 knowledge card —— 因子、异象、市场微结构、ML for finance 等研究。它是 agent 的 **文献入口**：当 agent 要把一个判断锚到学术文献上（"momentum crash 真的存在吗？"、"factor zoo 那篇到底说了什么？"），先调 `paper_search` 拿到候选 `paperCardId` + `availableSections`，再用 `paper_read` 加载真正需要的章节。

向量基于 `title + abstract + summary + tags`，所以 card 级命中是"值得继续 `paper_read`"的信号 —— `paper_search` 故意**不**返回正文。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: paper_search(query, limit=5)
  MCP-->>Agent: items[] · paperCardId · summary · availableSections
  Note over Agent: 扫描 summary + section manifest
  alt summary 已经够用
    Agent->>Agent: 用 summary + tags 直接回答
  else 需要特定章节
    Agent->>MCP: paper_read(paperCardId, sections=[keys])
    MCP-->>Agent: sections[].content (Markdown)
  else 需要全文
    Agent->>MCP: paper_read(paperCardId, sections=["all"])
    MCP-->>Agent: 按 order 返回完整 sections[]
  end
```

## 返回值

### `paper_search` 返回

<ResponseField name="data" type="PaperCard[]">
  按相关性降序排列的论文卡片数组。

  <Expandable title="PaperCard 字段">
    <ResponseField name="paperCardId" type="string">
      稳定标识符。传给 `paper_read` 加载具体章节内容。
    </ResponseField>

    <ResponseField name="sourcePaperId" type="string">
      原始来源标识（如 arXiv ID）。
    </ResponseField>

    <ResponseField name="title" type="string">
      论文标题。
    </ResponseField>

    <ResponseField name="authors" type="string[]">
      作者列表。
    </ResponseField>

    <ResponseField name="abstract" type="string">
      论文原始 abstract。
    </ResponseField>

    <ResponseField name="summary" type="string">
      LLM 生成的 2–3 句摘要。**用它判断是否值得花一次 `paper_read` 加载完整章节**。
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      研究主题标签（如 `factor`、`momentum`、`deep-learning`）。
    </ResponseField>

    <ResponseField name="availableSections" type="object[]">
      章节 manifest。每条含 `section_key`、`section_type`、`title`、`char_count`、`section_order`。调 `paper_read` 时使用其中的 `section_key`。
    </ResponseField>

    <ResponseField name="sectionCount" type="number">
      可用章节总数。
    </ResponseField>

    <ResponseField name="fullTextCharCount" type="number">
      所有章节合计字符数。
    </ResponseField>

    <ResponseField name="pdfUrl" type="string">
      论文 PDF 直链。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（搜索固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · paper_search" expandable theme={null}
{
  "data": [
    {
      "paperCardId": "card_abc123",
      "sourcePaperId": "arxiv:1404.4944",
      "title": "Momentum Crashes",
      "authors": ["Kent Daniel", "Tobias J. Moskowitz"],
      "abstract": "Despite their strong positive abnormal returns, momentum strategies experience infrequent but severe crashes...",
      "summary": "记录了动量组合在熊市反弹之后出现的剧烈崩溃，并给出可在实时操作中识别的 market-state / volatility 预测变量。",
      "tags": ["factor", "momentum", "crash"],
      "availableSections": [
        { "section_key": "introduction", "section_type": "introduction", "title": "Introduction", "char_count": 18420, "section_order": 1 },
        { "section_key": "methodology", "section_type": "method", "title": "Methodology", "char_count": 22150, "section_order": 2 }
      ],
      "sectionCount": 6,
      "fullTextCharCount": 102345,
      "pdfUrl": "https://arxiv.org/pdf/1404.4944"
    }
  ],
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

### `paper_read` 返回

<ResponseField name="data" type="PaperReadResult">
  单篇 paper 的指定章节集合。

  <Expandable title="PaperReadResult 字段">
    <ResponseField name="paperCardId" type="string">稳定标识符。</ResponseField>
    <ResponseField name="sourcePaperId" type="string">原始来源标识。</ResponseField>
    <ResponseField name="title" type="string">论文标题。</ResponseField>
    <ResponseField name="authors" type="string[]">作者列表。</ResponseField>
    <ResponseField name="abstract" type="string">原始 abstract。</ResponseField>
    <ResponseField name="summary" type="string">LLM 摘要。</ResponseField>
    <ResponseField name="tags" type="string[]">主题标签。</ResponseField>
    <ResponseField name="pdfUrl" type="string">论文 PDF 直链。</ResponseField>

    <ResponseField name="availableSections" type="object[]">
      章节 manifest（与 `paper_search` 中结构相同）。
    </ResponseField>

    <ResponseField name="sectionCount" type="number">可用章节总数。</ResponseField>
    <ResponseField name="fullTextCharCount" type="number">所有章节合计字符数。</ResponseField>

    <ResponseField name="sections" type="object[]">
      请求到的章节内容，按 `section_order` 排列。每条含 `section_key`、`section_type`、`title`、`content`（Markdown）、`char_count`、`section_order`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">读取固定 `0`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

## 说明

<Tip>
  **两步检索是 canonical 模式**：`paper_search` 用 1 credit 拿一组 ID + summary + section manifest，agent 据此判断要不要加载章节；再用 `paper_read` 免费加载真正需要的章节。建议先读 top-1 的 `introduction` + `methodology`；要核对具体结论时再加章节。
</Tip>

<Tip>
  调 `paper_read` **之前**就用 `paper_search` 返回的 `availableSections[i].char_count` 决定读哪几节。长文不要随手 `["all"]` —— 精准加载 1–2 节，agent context 会小很多。
</Tip>

<Warning>
  超过 **2,000 字符** 的查询会返回 `400`。把 agent 上下文里的长文先做摘要再调用。
</Warning>

<Warning>
  `paper_search` 的 `limit` 必须在 **1** 到 **10** 之间，超出范围会返回 `400`。
</Warning>

<Warning>
  `paper_search` **只返回 card 级元数据**，不带正文。要拿到章节内容必须调 `paper_read`。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 搜索
    {
      "method": "tools/call",
      "params": {
        "name": "paper_search",
        "arguments": { "query": "momentum crash", "limit": 5 }
      }
    }

    // 2) 读 top hit 的指定章节
    {
      "method": "tools/call",
      "params": {
        "name": "paper_read",
        "arguments": {
          "paperCardId": "card_abc123",
          "sections": ["introduction", "methodology"]
        }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {
        "Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}",
        "Content-Type": "application/json",
    }

    # 1) 搜索
    hits = requests.post(
        f"{base}/api/paper/search",
        headers=headers,
        json={"query": "momentum crash", "limit": 5},
    ).json()["data"]

    # 2) 读 top hit 的指定章节
    top = hits[0]
    paper = requests.post(
        f"{base}/api/paper/read",
        headers=headers,
        json={
            "paperCardId": top["paperCardId"],
            "sections": ["introduction", "methodology"],
        },
    ).json()["data"]

    for section in paper["sections"]:
        print(f"## {section['title']} ({section['char_count']} chars)")
        print(section["content"][:500])
    ```

    ```bash cURL theme={null}
    # 1) 搜索
    curl -X POST "https://api.llmquantdata.com/api/paper/search" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "momentum crash", "limit": 5}'

    # 2) 读指定章节
    curl -X POST "https://api.llmquantdata.com/api/paper/read" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"paperCardId": "card_abc123", "sections": ["introduction", "methodology"]}'
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="paper_search — 请求参数" icon="magnifying-glass">
    <ParamField type="string">
      自然语言查询字符串。最多 2,000 字符。
    </ParamField>

    <ParamField type="number">
      返回结果上限。范围 `1–10`。
    </ParamField>
  </Accordion>

  <Accordion title="paper_read — 请求参数" icon="book-open">
    <ParamField type="string">
      `paper_search` 返回的 `paperCardId`。
    </ParamField>

    <ParamField type="string[]">
      章节 key 数组，取自 `availableSections[].section_key`。省略或传 `["all"]` 表示读全文。
    </ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns>
  <Card title="Wiki 搜索" icon="book" href="/zh-CN/api/knowledge/wiki-search">
    同样的两步检索模式，作用在 Quant Wiki 语料（概念、公式、因子）上。
  </Card>

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


# Wiki 搜索
Source: https://docs.llmquantdata.com/zh-CN/api/knowledge/wiki-search

在 LLMQuant Quant Wiki 上做语义检索 —— 为你的 Agent 找出量化概念、公式、因子与策略。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`wiki_search` + `wiki_read` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>1 credit · search</Badge>
 
<Badge>免费 · read</Badge>

## 它为 Agent 做什么

`wiki_search` 接收自然语言查询，返回 Quant Wiki 中最相关的条目 —— 概念、公式、因子、策略。它是 agent 的 **research 入口**：当 agent 在任务过程中遇到金融术语（"Black-Scholes 的假设是什么？"、"什么是配对交易？"）时，先调 `wiki_search` 拿到 `wikiItemId`，再用 `wiki_read` 加载完整 markdown。

混合排序融合语义相似度与关键词匹配 —— 简短术语和长描述查询都能命中。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: wiki_search(query, limit=5)
  MCP-->>Agent: items[] · wikiItemId · summary · scores
  Note over Agent: scan summaries
  alt summary 已经够用
    Agent->>Agent: 用 summary 直接回答
  else 需要正文
    Agent->>MCP: wiki_read(wikiItemId, maxLength?)
    MCP-->>Agent: body_markdown
  end
```

## 返回值

### `wiki_search` 返回

<ResponseField name="data" type="WikiItem[]">
  按相关性降序排列的 wiki 条目数组。

  <Expandable title="WikiItem 字段">
    <ResponseField name="wikiItemId" type="string">
      稳定标识符。传给 `wiki_read` 加载完整文章。
    </ResponseField>

    <ResponseField name="slug" type="string">
      由标题派生的 URL 友好 slug。
    </ResponseField>

    <ResponseField name="title" type="string">
      文章标题。
    </ResponseField>

    <ResponseField name="summary" type="string">
      LLM 生成的 2–3 句摘要。**用它判断是否值得花一次 `wiki_read` 加载完整文章**。
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      主题标签（如 `equity`、`factor`、`derivatives`）。
    </ResponseField>

    <ResponseField name="scores" type="object">
      混合相关度分数。`combined` 是融合后的最终分；`semantic` 和 `lexical` 是分项（均 0–1）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（搜索固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · wiki_search" expandable theme={null}
{
  "data": [
    {
      "wikiItemId": "11111111-1111-4111-8111-111111111111",
      "slug": "momentum-factor",
      "title": "动量因子",
      "summary": "动量因子刻画近期赢家在 3–12 个月内继续跑赢的现象，是经典 Fama-French 因子之一，也是众多系统化股票策略的基础。",
      "tags": ["equity", "factor"],
      "scores": { "combined": 0.91, "semantic": 0.88, "lexical": 0.79 }
    }
  ],
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

### `wiki_read` 返回

<ResponseField name="data" type="WikiItem">
  完整的 wiki 条目。

  <Expandable title="WikiItem 字段">
    <ResponseField name="wikiItemId" type="string">稳定标识符。</ResponseField>
    <ResponseField name="title" type="string">文章标题。</ResponseField>
    <ResponseField name="summary" type="string">2–3 句摘要。</ResponseField>

    <ResponseField name="body_markdown" type="string">
      完整文章正文（Markdown）。如指定 `maxLength` 则截断到该字符数。
    </ResponseField>

    <ResponseField name="item_type" type="string">
      可选值：`concept`（概念）、`formula`（公式）、`strategy`（策略）、`factor`（因子）。
    </ResponseField>

    <ResponseField name="tags" type="string[]">主题标签。</ResponseField>
    <ResponseField name="source_url" type="string">`quant-wiki.com` 上的原文链接。</ResponseField>
    <ResponseField name="updated_at" type="datetime">ISO-8601 最后更新时间。</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">读取固定 `0`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

## 说明

<Tip>
  **两步检索是 canonical 模式**：`wiki_search` 先用 1 credit 拿一组 ID + summary，agent 据此判断要不要加载全文；再用 `wiki_read` 免费加载真正需要的那 1–2 篇。默认只读 top-1，summary 模糊时再读 top-2。
</Tip>

<Tip>
  长文用 `wiki_read` 的 `maxLength` 先做预览，避免把 agent context 烧在不必要的正文上。
</Tip>

<Warning>
  超过 **2,000 字符** 的查询会返回 `400`。把 agent 上下文里的长文先做摘要再调用。
</Warning>

<Warning>
  `wiki_search` 的 `limit` 必须在 **1** 到 **10** 之间，超出范围会返回 `400`。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 搜索
    {
      "method": "tools/call",
      "params": {
        "name": "wiki_search",
        "arguments": { "query": "动量因子", "limit": 5 }
      }
    }

    // 2) 读 top hit
    {
      "method": "tools/call",
      "params": {
        "name": "wiki_read",
        "arguments": { "wikiItemId": "11111111-1111-4111-8111-111111111111", "maxLength": 1500 }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) 搜索
    hits = requests.post(
        f"{base}/api/wiki/search",
        headers=headers,
        json={"query": "动量因子", "limit": 5},
    ).json()["data"]

    # 2) 读 top hit
    top = requests.get(
        f"{base}/api/wiki/items/{hits[0]['wikiItemId']}",
        headers=headers,
        params={"max_length": 1500},
    ).json()["data"]
    print(top["body_markdown"])
    ```

    ```bash cURL theme={null}
    # 1) 搜索
    curl -X POST "https://api.llmquantdata.com/api/wiki/search" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "动量因子", "limit": 5}'

    # 2) 读 top hit（把示例 UUID 换成第 1 步返回的 wikiItemId）
    WIKI_ITEM_ID="11111111-1111-4111-8111-111111111111"
    curl "https://api.llmquantdata.com/api/wiki/items/${WIKI_ITEM_ID}?max_length=1500" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="wiki_search — 请求参数" icon="magnifying-glass">
    <ParamField type="string">
      自然语言查询字符串。最多 2,000 字符。
    </ParamField>

    <ParamField type="number">
      返回结果上限。范围 `1–10`。
    </ParamField>
  </Accordion>

  <Accordion title="wiki_read — 请求参数" icon="book-open">
    <ParamField type="string">
      `wiki_search` 返回的 `wikiItemId`。
    </ParamField>

    <ParamField type="number">
      `body_markdown` 的最大字符数。预览长文档时使用。
    </ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns>
  <Card title="论文搜索" icon="file-lines" href="/zh-CN/api/knowledge/paper-search">
    同样的两步检索模式，作用在学术论文语料上。
  </Card>

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


# 宏观历史时间序列
Source: https://docs.llmquantdata.com/zh-CN/api/macro/historical

单个美国宏观指标的 latest-vintage 历史时间序列。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`macro_indicator_search` + `macro_indicator_history` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>1 credit · history</Badge>
 
<Badge>免费 · search</Badge>

## 它为 Agent 做什么

`macro_indicator_history` 返回单个支持的美国宏观指标（CPI、UNRATE、Fed Funds、10Y 收益率、GDP 等）的 **latest-vintage 历史时间序列** —— 一组 `{ date, value, realtime_start, realtime_end }` observation。它是 agent 的 **宏观时间序列拉取器**：要把过去 5 年通胀画图、要算收益率曲线斜率、要把 observation 喂下游模型时调它。

canonical 的 agent 流程是两步：先调 `macro_indicator_search`（免费）找到正确的 `indicator` alias，再调 `macro_indicator_history` 拉序列。时间边界可选：用 `start_date` 和/或 `end_date` 先过滤候选窗口，再用 `limit` 和 `take_from` 决定保留哪一端。返回顺序始终是旧到新。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: macro_indicator_search(query?, category?, frequency?)
  MCP-->>Agent: items[] · indicator · series_id · frequency · units
  Note over Agent: 选出正确的 alias
  alt 问题是"近期趋势"
    Agent->>MCP: macro_indicator_history(indicator, limit=60)
    MCP-->>Agent: observations[] · date · value · realtime_start
  else 问题是"窗口开头"
    Agent->>MCP: macro_indicator_history(indicator, start_date, end_date, limit=12, take_from=earliest)
    MCP-->>Agent: observations[] · 窗口内最早 12 条
  end
  Note over Agent: 画图 / 对比 / 喂下游
```

## 返回值

<ResponseField name="data" type="MacroHistorical">
  指标元信息 + observations 数组。

  <Expandable title="MacroHistorical 字段">
    <ResponseField name="indicator" type="string">
      回显的平台稳定 alias（如 `us.cpi.headline`）。
    </ResponseField>

    <ResponseField name="series_id" type="string">
      Raw series ID（如 `CPIAUCSL`）。
    </ResponseField>

    <ResponseField name="title" type="string">
      指标的可读标题。
    </ResponseField>

    <ResponseField name="frequency" type="string">
      原生发布频率：`Daily`、`Weekly`、`Monthly`、`Quarterly`、`Annual`。
    </ResponseField>

    <ResponseField name="units" type="string">
      单位字符串（如 `Index 1982-1984=100`、`Percent`）。
    </ResponseField>

    <ResponseField name="observations" type="MacroObservation[]">
      时间升序的 observation（旧 → 新）。

      <Expandable title="MacroObservation 字段">
        <ResponseField name="date" type="string">
          观测期起始日（YYYY-MM-DD）。
        </ResponseField>

        <ResponseField name="value" type="number">
          上报值。该周期缺失时为 `null`。
        </ResponseField>

        <ResponseField name="realtime_start" type="string">
          该值首次发布日（YYYY-MM-DD）。用来识别 revision。
        </ResponseField>

        <ResponseField name="realtime_end" type="string">
          该值的有效结束日。当前 latest vintage 通常等于 `realtime_start`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="attribution" type="string">
      展示数据时必须保留的署名字符串。
    </ResponseField>

    <ResponseField name="stale" type="boolean">
      刷新失败、返回较旧可用数据时为 `true`。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `1`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>
<ResponseField name="meta.notice" type="string">仅在候选窗口内的数据多于实际返回条数时出现 —— 也就是结果被 `limit` 截断了。这句话提示 agent 缩小窗口或把查询拆成多次：`More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · macro_indicator_history" expandable theme={null}
{
  "data": {
    "indicator": "us.cpi.headline",
    "series_id": "CPIAUCSL",
    "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
    "frequency": "Monthly",
    "units": "Index 1982-1984=100",
    "observations": [
      {
        "date": "2026-01-01",
        "value": 318.412,
        "realtime_start": "2026-02-12",
        "realtime_end": "2026-02-12"
      },
      {
        "date": "2026-02-01",
        "value": 319.082,
        "realtime_start": "2026-03-12",
        "realtime_end": "2026-03-12"
      },
      {
        "date": "2026-03-01",
        "value": 319.799,
        "realtime_start": "2026-04-10",
        "realtime_end": "2026-04-10"
      }
    ],
    "attribution": "Source: U.S. Bureau of Labor Statistics via FRED",
    "stale": false
  },
  "meta": {
    "creditsUsed": 1,
    "remainingCredits": 99
  }
}
```

<Note>
  每条 series 在 `data` 下都带有自己的 `attribution` 字符串（FRED 来源说明）—— 展示数据时请一并呈现。本产品使用 FRED® API，但未经 Federal Reserve Bank of St. Louis 背书或认证。
</Note>

## 说明

<Tip>
  **Revision-aware**：宏观 observation 会被修订。我们返回的是**当前 latest vintage**，不一定是当初首发的值。用 `realtime_start` / `realtime_end` 判断你是不是看到了修订后的版本。暂不支持 as-of vintage 历史回放。
</Tip>

<Tip>
  默认 `limit=60` 大致覆盖月频最近 5 年、周频最近 1 年、日频最近 3 个月。用 `start_date` / `end_date` 限定窗口；需要窗口开头的 N 条时传 `take_from=earliest`。
</Tip>

<Warning>
  `take_from=earliest` 需要 `start_date`。如果同时传两个日期边界，`start_date` 不能晚于 `end_date`。
</Warning>

<Warning>
  **仅支持目录内。** 约 50 个精选美国指标，目录之外返回 `404`。用 `macro_indicator_search` 浏览可用列表。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 找 alias
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_search",
        "arguments": { "query": "cpi", "category": "Inflation" }
      }
    }

    // 2) 取最近的 history（默认 60）
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_history",
        "arguments": { "indicator": "us.cpi.headline", "limit": 60 }
      }
    }

    // 2b) 或取一个日期窗口内最早的 12 条
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_history",
        "arguments": {
          "indicator": "us.cpi.headline",
          "start_date": "2020-01-01",
          "end_date": "2026-03-01",
          "limit": 12,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 1) 找 alias
    catalog = requests.get(
        f"{base}/api/macro/indicators",
        headers=headers,
        params={"query": "cpi", "category": "Inflation"},
    ).json()["data"]

    alias = catalog[0]["indicator"]  # 例如 us.cpi.headline

    # 2) 取最近的 history
    hist = requests.get(
        f"{base}/api/macro/historical",
        headers=headers,
        params={"indicator": alias, "limit": 60},
    ).json()
    for obs in hist["data"]["observations"][-3:]:
        print(obs["date"], obs["value"])
    ```

    ```bash cURL theme={null}
    # 1) 找 alias
    curl "https://api.llmquantdata.com/api/macro/indicators?query=cpi&category=Inflation" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2) 不传日期边界 —— 最近的观测
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&limit=60" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 2b) 窗口内最早的 12 条
    curl "https://api.llmquantdata.com/api/macro/historical?indicator=us.cpi.headline&start_date=2020-01-01&end_date=2026-03-01&limit=12&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="macro_indicator_search — 请求参数" icon="magnifying-glass">
    <ParamField type="string">
      自由文本关键词，匹配 indicator alias、指标标题、`series_id`。
    </ParamField>

    <ParamField type="string">
      按主题过滤（`Inflation`、`Rates`、`Labor`、`Growth`、`Housing`、`Liquidity`、`Conditions`、`FX`、`Credit`、`Sentiment`、`Energy`、`Inflation Expectations`、`Consumption`）。
    </ParamField>

    <ParamField type="string">
      按发布频率过滤（`Daily`、`Weekly`、`Monthly`、`Quarterly`、`Annual`）。
    </ParamField>

    <ParamField type="number">
      返回上限。范围 `1–100`。
    </ParamField>
  </Accordion>

  <Accordion title="macro_indicator_history — 请求参数" icon="chart-line">
    <ParamField type="string">
      平台 alias（如 `us.cpi.headline`、`us.rates.fed_funds`）。与 `series_id` **二选一**。
    </ParamField>

    <ParamField type="string">
      Raw series ID（如 `CPIAUCSL`）。与 `indicator` **二选一**。必须在支持目录内。
    </ParamField>

    <ParamField type="string">
      可选 inclusive 下边界，ISO 日期 `YYYY-MM-DD`。
    </ParamField>

    <ParamField type="string">
      可选 inclusive 上边界，ISO 日期 `YYYY-MM-DD`。
    </ParamField>

    <ParamField type="number">
      边界过滤后最多返回多少条 observation。范围 `1–500`。
    </ParamField>

    <ParamField type="string">
      当过滤后候选超过 `limit` 时保留哪一端：`latest` 或 `earliest`。输出仍按时间正序。
    </ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns>
  <Card title="宏观指标目录" icon="landmark" href="/zh-CN/api/macro/indicators">
    浏览约 50 个精选指标目录（免费）。
  </Card>

  <Card title="宏观指标快照" icon="gauge-high" href="/zh-CN/api/macro/snapshot">
    只看最新值 + 涨跌（不返回完整序列）。
  </Card>
</Columns>


# 宏观指标目录
Source: https://docs.llmquantdata.com/zh-CN/api/macro/indicators

浏览或搜索支持的美国宏观指标目录（约 50 个）。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`macro_indicator_search` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · 0 credits</Badge>

## 它为 Agent 做什么

`macro_indicator_search` 返回 LLMQuant Data **支持的约 50 个美国宏观指标目录** —— 通胀（CPI / PCE）、利率（联邦基金利率、国债收益率）、就业（失业率、非农）、增长（GDP）、住房、流动性（M2、Fed 资产负债表）、金融条件、汇率等。它是 agent 的 **catalog discovery 入口**：在调用 `macro_indicator_history` / `macro_indicator_snapshot` 之前，先用它通过 `category`、`frequency` 或自由文本关键词浏览目录，确定要用哪个 `indicator` alias 或 `series_id`。

它**不**暴露所有可能的宏观 series —— 只返回精选、已澄清署名的支持目录。不传任何参数 = 列出全部。

## 返回值

<ResponseField name="data" type="MacroIndicatorCatalogItem[]">
  Curated catalog 条目，每条对应一个支持的指标。

  <Expandable title="MacroIndicatorCatalogItem 字段">
    <ResponseField name="indicator" type="string">
      平台稳定 alias。传给 `macro_indicator_history` / `macro_indicator_snapshot`（如 `us.cpi.headline`、`us.rates.fed_funds`）。
    </ResponseField>

    <ResponseField name="series_id" type="string">
      Raw series ID（如 `CPIAUCSL`、`FEDFUNDS`）。history/snapshot 工具同样接收。
    </ResponseField>

    <ResponseField name="title" type="string">
      指标的可读标题。
    </ResponseField>

    <ResponseField name="category" type="string">
      主题分类：`Growth`、`Consumption`、`Inflation`、`Labor`、`Housing`、`Rates`、`Inflation Expectations`、`Liquidity`、`Conditions`、`FX`、`Credit`、`Sentiment`、`Energy`。
    </ResponseField>

    <ResponseField name="frequency" type="string">
      原生发布频率：`Daily`、`Weekly`、`Monthly`、`Quarterly`、`Annual`。
    </ResponseField>

    <ResponseField name="units" type="string">
      单位字符串（如 `Index 1982-1984=100`、`Percent`、`Thousands of Persons`）。
    </ResponseField>

    <ResponseField name="observation_start" type="string">
      当前可用的最早 observation 日期（YYYY-MM-DD）。
    </ResponseField>

    <ResponseField name="observation_end" type="string">
      当前可用的最近 observation 日期（YYYY-MM-DD）。
    </ResponseField>

    <ResponseField name="copyright_status" type="string">
      `Public Domain: Citation requested` 或 `Copyrighted: Citation required`。`Pre-approval required` 的 series 不会出现。
    </ResponseField>

    <ResponseField name="attribution" type="string">
      展示数据时必须保留的署名字符串。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0`，catalog 浏览免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">本次调用后余额剩余的 credits。</ResponseField>

```json title="200 OK · macro_indicator_search" expandable theme={null}
{
  "data": [
    {
      "indicator": "us.cpi.headline",
      "series_id": "CPIAUCSL",
      "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
      "category": "Inflation",
      "frequency": "Monthly",
      "units": "Index 1982-1984=100",
      "observation_start": "1947-01-01",
      "observation_end": "2026-03-01",
      "copyright_status": "Public Domain: Citation requested",
      "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
    },
    {
      "indicator": "us.unemployment_rate",
      "series_id": "UNRATE",
      "title": "Unemployment Rate",
      "category": "Labor",
      "frequency": "Monthly",
      "units": "Percent",
      "observation_start": "1948-01-01",
      "observation_end": "2026-03-01",
      "copyright_status": "Public Domain: Citation requested",
      "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
    }
  ],
  "meta": {
    "creditsUsed": 0,
    "remainingCredits": 500
  }
}
```

<Note>
  每条 catalog 条目在 `data` 里自带 `attribution` 来源说明（FRED 署名）—— 展示数据时一并显示。本目录使用 FRED® API，但未获 Federal Reserve Bank of St. Louis 背书或认证。
</Note>

## 说明

<Tip>
  **两步检索**：先调 `macro_indicator_search`（免费）确定 alias，再调 `macro_indicator_history`（1 credit）取时间序列，或 `macro_indicator_snapshot`（免费）取最新值。catalog 不消耗 credit，可以放心多调几次。
</Tip>

<Tip>
  优先用平台 `indicator` alias（`us.cpi.headline`），不要用裸 `series_id`（`CPIAUCSL`）—— alias 在 raw series 命名变化时仍然稳定，agent trace 里也更清晰。
</Tip>

<Warning>
  **仅支持目录内。** 大约 50 个美国宏观 series。目录之外的 `series_id` 返回 `404`。需要的指标不在列表里，请提 issue。
</Warning>

<Warning>
  catalog 行**不是实时**：`observation_end` 反映 LLMQuant Data 当前可用的最后已知发布时间，不一定是今天。
</Warning>

## 直接调用

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

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/macro/indicators",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"category": "Inflation", "limit": 10},
    ).json()
    for item in resp["data"]:
        print(f"{item['indicator']}  ({item['series_id']})  {item['frequency']}")
    ```

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

## 完整参数参考

<Accordion title="macro_indicator_search — 请求参数" icon="sliders">
  <ParamField type="string">
    自由文本关键词，匹配 indicator alias、指标标题、`series_id`。
  </ParamField>

  <ParamField type="string">
    按主题过滤：`Growth`、`Consumption`、`Inflation`、`Labor`、`Housing`、`Rates`、`Inflation Expectations`、`Liquidity`、`Conditions`、`FX`、`Credit`、`Sentiment`、`Energy`。
  </ParamField>

  <ParamField type="string">
    按发布频率过滤：`Daily`、`Weekly`、`Monthly`、`Quarterly`、`Annual`。
  </ParamField>

  <ParamField type="number">
    返回上限。范围 `1–100`。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="宏观历史时间序列" icon="chart-line" href="/zh-CN/api/macro/historical">
    单个指标的时间序列，按日期窗口筛选、由 `limit` / `take_from` 收敛条数。
  </Card>

  <Card title="宏观指标快照" icon="gauge-high" href="/zh-CN/api/macro/snapshot">
    最新值 + 前值 + 涨跌（不返回完整序列）。
  </Card>
</Columns>


# 宏观指标快照
Source: https://docs.llmquantdata.com/zh-CN/api/macro/snapshot

单个美国宏观指标的最新值 + 前值 + 涨跌。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`macro_indicator_snapshot` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · latest</Badge>

## 它为 Agent 做什么

`macro_indicator_snapshot` 返回某个美国宏观指标的**最新 observation**，加上**前值**和两者的**差值**。它是 agent 的 **宏观 checkpoint**：要回答 "现在联邦基金利率多少？"、"失业率比上月升了还是降了？"、"当前宏观 regime 是什么？" 时，不需要拉完整序列，调它一次就够。

`macro_indicator_snapshot({ indicator })` → `latest`、`previous`、`delta_abs`、`delta_pct`。仅此而已。要完整时间序列，请用 [`macro_indicator_history`](/zh-CN/api/macro/historical)。

## 返回值

<ResponseField name="data" type="MacroSnapshot">
  <Expandable title="MacroSnapshot 字段">
    <ResponseField name="indicator" type="string">
      平台稳定 alias（如 `us.rates.fed_funds`）。
    </ResponseField>

    <ResponseField name="series_id" type="string">
      Raw series ID（如 `FEDFUNDS`）。
    </ResponseField>

    <ResponseField name="title" type="string">
      指标的可读标题。
    </ResponseField>

    <ResponseField name="frequency" type="string">
      原生发布频率（`Daily`、`Weekly`、`Monthly`、`Quarterly`、`Annual`）。
    </ResponseField>

    <ResponseField name="units" type="string">
      单位字符串（如 `Percent`、`Index 1982-1984=100`）。
    </ResponseField>

    <ResponseField name="latest" type="object">
      最新 observation。还没有可用数据时为 `null`。

      <Expandable title="latest 字段">
        <ResponseField name="date" type="string">观测日期（YYYY-MM-DD）。</ResponseField>
        <ResponseField name="value" type="number">上报值，可能为 `null`。</ResponseField>
        <ResponseField name="realtime_start" type="string">该值首次发布日。</ResponseField>
        <ResponseField name="realtime_end" type="string">该值有效结束日。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="previous" type="object">
      前一笔 observation。只有一笔时为 `null`。

      <Expandable title="previous 字段">
        <ResponseField name="date" type="string">前值观测日期。</ResponseField>
        <ResponseField name="value" type="number">前值。</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="delta_abs" type="number">
      `latest.value − previous.value`。任何一边缺失时为 `null`。
    </ResponseField>

    <ResponseField name="delta_pct" type="number">
      相对前值的百分比变化（即 `delta_abs / previous.value * 100`）。任一边缺失或前值为 `0` 时为 `null`。
    </ResponseField>

    <ResponseField name="attribution" type="string">
      展示数据时必须保留的署名字符串。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— 本接口免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · macro_indicator_snapshot" expandable theme={null}
{
  "data": {
    "indicator": "us.unemployment_rate",
    "series_id": "UNRATE",
    "title": "Unemployment Rate",
    "frequency": "Monthly",
    "units": "Percent",
    "latest": {
      "date": "2026-03-01",
      "value": 4.1,
      "realtime_start": "2026-04-04",
      "realtime_end": "2026-04-04"
    },
    "previous": {
      "date": "2026-02-01",
      "value": 4.0
    },
    "delta_abs": 0.1,
    "delta_pct": 2.5,
    "attribution": "Source: U.S. Bureau of Labor Statistics via FRED"
  },
  "meta": {
    "creditsUsed": 0,
    "remainingCredits": 99
  }
}
```

<Note>
  snapshot 在 `data` 下带有自己的 `attribution` 字符串（FRED 来源说明）—— 展示数据时请一并呈现。本产品使用 FRED® API，但未经 Federal Reserve Bank of St. Louis 背书或认证。
</Note>

## 说明

<Tip>
  **Revision-aware**：snapshot 返回的是**当前 latest vintage** —— 不是当初首发的值。如果最近一笔被修订，你看到的是修订后的值。看 `latest.realtime_start` 可以判断该值最后发布于哪天。
</Tip>

<Tip>
  snapshot 比 `macro_indicator_history` 返回的 token 体量小得多，而且本接口免费。当 agent 只关心 "当前是多少" 时用 snapshot，不需要序列。
</Tip>

<Warning>
  **仅支持目录内。** 约 50 个精选美国指标。先用 `macro_indicator_search` 浏览可用列表；目录之外的 ID 返回 `404`。
</Warning>

<Warning>
  按频率刷新：日频/周频指标 24h 内更新；月频/季频 7 天内更新。snapshot 可能比当前最新发布滞后几个小时。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "macro_indicator_snapshot",
        "arguments": { "indicator": "us.unemployment_rate" }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/macro/snapshot",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"indicator": "us.unemployment_rate"},
    ).json()
    d = resp["data"]
    print(f"{d['indicator']}: {d['latest']['value']}{d['units'][:1]} "
          f"({d['delta_abs']:+.2f} vs prev)")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/macro/snapshot?indicator=us.unemployment_rate" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="macro_indicator_snapshot — 请求参数" icon="sliders">
  <ParamField type="string">
    平台 alias（如 `us.cpi.headline`、`us.rates.fed_funds`、`us.unemployment_rate`）。与 `series_id` **二选一**。
  </ParamField>

  <ParamField type="string">
    Raw series ID（如 `UNRATE`、`FEDFUNDS`）。与 `indicator` **二选一**。必须在支持目录内。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="宏观历史时间序列" icon="chart-line" href="/zh-CN/api/macro/historical">
    同一指标的完整 latest-vintage 时间序列，按日期窗口筛选、由 `limit` / `take_from` 收敛条数。
  </Card>

  <Card title="宏观指标目录" icon="landmark" href="/zh-CN/api/macro/indicators">
    浏览约 50 个精选指标目录（免费）。
  </Card>
</Columns>


# 新闻浏览
Source: https://docs.llmquantdata.com/zh-CN/api/news/browse

按 ticker、事件、主题或日期浏览持续更新的公司新闻。

<Note icon="sparkles">
  **已提供 MCP 工具**：`news_browse` —— 可在 Claude、Cursor 或任意 MCP 客户端中直接调用。配置方法见 [MCP Server](/zh-CN/integration/mcp-server)。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>每次调用 2 credits</Badge>

## 它为 Agent 做什么

`news_browse` 给 Agent 返回近期公司新闻，包含精炼标题、摘要和详细总结。你可以精确筛选市场动态、跟踪公司，或查找特定事件与主题组合。

可用范围会随公司和日期变化。先查近期新闻，再用精确筛选缩小结果范围。

## 返回值

<ResponseField name="data" type="object">
  匹配的新闻条目和返回数量。

  <Expandable title="data 字段">
    <ResponseField name="items" type="NewsArticle[]">
      按 `published_at` 倒序返回，最新的排在最前。

      <Expandable title="NewsArticle 字段">
        <ResponseField name="title" type="string">
          便于快速浏览结果列表的短标题。
        </ResponseField>

        <ResponseField name="abstract" type="string">
          一到两句话，帮助 Agent 决定是否继续读完整总结。
        </ResponseField>

        <ResponseField name="summary" type="string">
          保留重要事实和限定信息的详细总结。
        </ResponseField>

        <ResponseField name="events" type="string[]">
          按字母排序的受控事件值。请忽略未来新增的未知值。
        </ResponseField>

        <ResponseField name="topics" type="string[]">
          按字母排序的受控主题值。请忽略未来新增的未知值。
        </ResponseField>

        <ResponseField name="tickers" type="string[]">
          与新闻相关的美股 symbol。
        </ResponseField>

        <ResponseField name="published_at" type="string">
          UTC 发布日期，精度到日。
        </ResponseField>

        <ResponseField name="source_url" type="string">
          原始公告链接。Agent 需要原文时可以顺着它取。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number">
      本次响应返回的条目数量。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">合法查询执行后固定为 `2`，空结果也会扣。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>
<ResponseField name="meta.notice" type="string">无匹配数据或 `limit` 之外还有更多条目时返回。</ResponseField>

```json title="200 OK · news_browse" expandable theme={null}
{
  "data": {
    "items": [
      {
        "title": "NVIDIA Announces Q1 Results",
        "abstract": "NVIDIA reported quarterly results and described demand across its major businesses.",
        "summary": "NVIDIA reported quarterly performance and provided updated guidance for the next period.",
        "events": ["earnings", "guidance"],
        "topics": ["artificial_intelligence", "semiconductors"],
        "tickers": ["NVDA"],
        "published_at": "2026-06-01",
        "source_url": "https://www.sec.gov/Archives/edgar/data/1045810/000104581026000123/nvda-ex99_1.htm"
      }
    ],
    "count": 1
  },
  "meta": { "creditsUsed": 2, "remainingCredits": 98 }
}
```

## 说明

<Tip>
  不传筛选条件可先看近期市场动态，再组合 `tickers`、`events` 和 `topics` 缩小范围。
</Tip>

<Warning>
  可用范围会随公司、日期和类别变化。所选筛选条件没有匹配内容时，合法查询可能返回空结果。
</Warning>

<Warning>
  每次合法查询消耗 2 credits，空结果也会扣。无效请求和服务错误不扣 credit。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "news_browse",
        "arguments": {
          "tickers": ["NVDA"],
          "events": ["earnings", "guidance"],
          "limit": 5
        }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/news/browse",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"tickers": "NVDA", "events": "earnings,guidance", "limit": 5},
    ).json()

    for item in resp["data"]["items"]:
        print(item["published_at"], item["title"])
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/news/browse?tickers=NVDA&events=earnings,guidance&limit=5" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="news_browse — 请求参数" icon="sliders">
  <ParamField type="string">
    逗号分隔的美股 symbol，值之间按 OR 组合，最多 5 个。
  </ParamField>

  <ParamField type="string">
    逗号分隔的事件值，值之间按 OR 组合。支持：`earnings`、`guidance`、`m_and_a`、`partnership`、`product`、`regulatory_approval`、`regulatory`、`legal`、`leadership_change`、`workforce`、`restructuring`、`bankruptcy`、`capital_action`、`credit_rating`、`analyst_rating`、`accounting_audit`、`operational_incident`、`shareholder_meeting`、`strategic_update`、`other`。
  </ParamField>

  <ParamField type="string">
    逗号分隔的主题值，值之间按 OR 组合。支持：`semiconductors`、`software`、`cloud_computing`、`cybersecurity`、`artificial_intelligence`、`consumer_electronics`、`it_hardware_networking`、`telecommunications`、`media_entertainment`、`internet_services`、`biotech_pharma`、`medical_devices`、`life_sciences_tools`、`healthcare_services`、`banking`、`capital_markets`、`insurance`、`fintech`、`crypto_digital_assets`、`real_estate`、`automotive`、`retail`、`consumer_packaged_goods`、`apparel_luxury`、`restaurants_leisure`、`aerospace_defense`、`industrial_machinery`、`transportation_logistics`、`construction_engineering`、`business_services`、`oil_gas`、`renewable_energy`、`utilities`、`metals_mining`、`chemicals`、`agriculture_food_production`、`paper_packaging_forestry`、`environmental_services`、`space_economy`、`quantum_computing`、`data_centers`、`macroeconomics_policy`、`geopolitics_trade`。
  </ParamField>

  <ParamField type="string">
    UTC 起始日期，`YYYY-MM-DD` 格式，包含当天，必须与 `end_date` 一起使用。
  </ParamField>

  <ParamField type="string">
    UTC 结束日期，`YYYY-MM-DD` 格式，包含当天，必须与 `start_date` 一起使用。
  </ParamField>

  <ParamField type="number">
    最多返回多少条，范围 1–25。
  </ParamField>
</Accordion>

不同参数之间按 AND 组合；`tickers`、`events`、`topics` 各自内部按 OR 组合。所有参数都可省略，此时返回近期市场动态。

## 相关接口

<Columns>
  <Card title="认证" icon="key" href="/zh-CN/authentication">
    创建 API key，并用它认证 HTTP 请求。
  </Card>

  <Card title="MCP Server 配置" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒接入 Claude、Cursor 或其他 Agent harness。
  </Card>
</Columns>


# 个人持仓
Source: https://docs.llmquantdata.com/zh-CN/api/personal/holdings

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

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

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · 0 credits</Badge>

## 它为 Agent 做什么

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

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

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

## 返回值

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

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

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

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

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

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

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

    <ResponseField name="currency" type="string">币种代码，通常为 `USD`。</ResponseField>
    <ResponseField name="as_of_date" type="string">这条保存值对应的日期（`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 type="string">
    可选过滤条件。取值为 `equity`、`etf`、`crypto`、`cash`、`fund`、`bond` 或 `other`。
  </ParamField>

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

## 相关接口

<Columns>
  <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>


# 个人 Profile
Source: https://docs.llmquantdata.com/zh-CN/api/personal/profile

读取你在 Dashboard Profile 保存的财务背景，作为 Agent 的个性化上下文。

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

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · 0 credits</Badge>

## 它为 Agent 做什么

`personal_profile` 返回你在 **Dashboard → Profile** 保存的财务背景：风险偏好、投资期限、基准币种和备注。Agent 需要按你的个人约束调整措辞、假设或组合分析时调用它。

这个工具只读。它不会修改你的 Profile，不会下单，也不会替你推断没填写的答案。如果你还没有保存 Profile，接口会返回 `data: null` 和 `200 OK`。

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

## 返回值

<ResponseField name="data" type="PersonalProfile | null">
  当前调用者自己账号的已保存 Profile；没有保存时为 `null`。

  <Expandable title="PersonalProfile fields">
    <ResponseField name="risk_preference" type="string">
      保存的风险偏好，例如 conservative 或 aggressive。
    </ResponseField>

    <ResponseField name="investment_horizon" type="string">
      保存的投资期限。
    </ResponseField>

    <ResponseField name="base_currency" type="string">
      Profile 使用的基准币种代码。默认 `USD`。
    </ResponseField>

    <ResponseField name="extra_notes" type="string">
      用来描述个人约束或偏好的备注。较长备注会缩短到 1,000 个字符。
    </ResponseField>
  </Expandable>
</ResponseField>

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

```json title="200 OK · personal_profile" expandable theme={null}
{
  "data": {
    "risk_preference": "moderate",
    "investment_horizon": "5-10 years",
    "base_currency": "USD",
    "extra_notes": "Prefer diversified ETFs and avoid concentrated single-stock positions."
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

```json title="200 OK · 未保存 Profile" expandable theme={null}
{
  "data": null,
  "meta": { "creditsUsed": 0, "remainingCredits": 100 }
}
```

## 说明

<Tip>
  用户问需要个人背景的问题时，先调用 `personal_profile`，如果还需要持仓上下文，再结合 [`personal_holdings`](/zh-CN/api/personal/holdings)。
</Tip>

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

<Warning>
  Profile 值是用户保存的偏好和备注，是给 Agent 使用的上下文，不是经过核验的财务建议。
</Warning>

## 直接调用

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

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

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

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/personal/profile" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="全部请求参数" icon="sliders">
  这个接口不接受请求参数。
</Accordion>

## 相关接口

<Columns>
  <Card title="个人持仓" icon="wallet" href="/zh-CN/api/personal/holdings">
    读取 Dashboard Profile 中保存的持仓。
  </Card>

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


# 预测市场事件
Source: https://docs.llmquantdata.com/zh-CN/api/prediction-markets/events

为 Agent 浏览、语义搜索并读取金融范围内的预测市场事件卡片。

<Note icon="sparkles">
  **可作为 MCP 工具调用**：`polymarket_event_browse` + `polymarket_event_search` + `polymarket_event_read` —— 可在 Claude / Cursor / 任意 MCP 客户端中直接使用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>1 credit · browse</Badge>
 
<Badge>2 credits · search</Badge>
 
<Badge>免费 · read</Badge>

## 它为 Agent 做什么

预测市场 event 会把相关 market question 归到一张 agent 可读的卡片里。自然语言问题优先用 `polymarket_event_search`，例如“Bitcoin ETF approval”或“Fed rate cut odds”；只有用户要 list 或给了精确过滤条件时才用 `polymarket_event_browse`，例如 `query=ETF`、`tag=policy` 或 `min_volume=10000`。

Event card 是入口，不是终点。Browse 或 search 返回 `event_card_id` 后，继续调用 `polymarket_event_read`，让 agent 先看到事件说明、生命周期状态、标签和子 market 预览，再决定读哪个 market。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  alt 用户给出过滤条件
    Agent->>MCP: polymarket_event_browse(status, query, tag, asset, limit)
    MCP-->>Agent: events[] · eventCardId · title · markets[]
  else 用户用自然语言提问
    Agent->>MCP: polymarket_event_search(query, status, limit)
    MCP-->>Agent: events[] · semanticScore · eventCardId
  end
  Note over Agent: 选择 markets 最贴近任务的 event
  Agent->>MCP: polymarket_event_read(event_card_id)
  MCP-->>Agent: event card · market previews · coverage status
```

## 返回值

### Browse 和 search 返回

<ResponseField name="data.events" type="PolymarketEvent[]">
  Browse 按生命周期和流动性排序。Search 按语义相关性排序。

  <Expandable title="PolymarketEvent 字段">
    <ResponseField name="event_card_id" type="string">
      稳定的 LLMQuant event id。传给 `polymarket_event_read` 继续读取。
    </ResponseField>

    <ResponseField name="title" type="string">
      可读的事件标题。
    </ResponseField>

    <ResponseField name="description" type="string">
      有数据时返回事件层面的说明。
    </ResponseField>

    <ResponseField name="market_count" type="number">
      这张 event card 下的子 markets 数量。
    </ResponseField>

    <ResponseField name="markets" type="PolymarketMarketPreview[]">
      Market 预览，包含 `market_card_id`、`market_question`、outcomes、状态、流动性和成交量。
    </ResponseField>

    <ResponseField name="tags" type="string[]">
      金融标签，例如 `crypto`、`policy` 或 `macro`。
    </ResponseField>

    <ResponseField name="status" type="string">
      Event 状态：`active`、`inactive` 或 `closed`。
    </ResponseField>

    <ResponseField name="coverage_status" type="string">
      这张规范化 event card 的覆盖状态。
    </ResponseField>

    <ResponseField name="semantic_score" type="number">
      语义搜索结果中会返回。分数越高，越贴近 query。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">本次返回的 events 数量。</ResponseField>
<ResponseField name="data.nextCursor" type="string">Browse 有更多结果时返回的分页 cursor。</ResponseField>
<ResponseField name="data.scope" type="string">本产品固定为 `finance`。</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Browse 为 `1`，search 为 `2`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · event search" expandable theme={null}
{
  "data": {
    "events": [
      {
        "event_card_id": "4b8f35c6-4781-4f3c-9237-142fc16467cd",
        "title": "Bitcoin ETF approved by Jan 15?",
        "description": "Markets related to whether a spot Bitcoin ETF is approved.",
        "market_count": 1,
        "markets": [
          {
            "market_card_id": "e370488a-33b5-4abd-8c5c-37c7ad8a60fc",
            "market_question": "Bitcoin ETF approved by Jan 15?",
            "outcomes": [
              { "label": "Yes", "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658", "current_probability": 0.51 }
            ],
            "status": "closed",
            "volume": 1250000,
            "liquidity": 48000
          }
        ],
        "tags": ["crypto", "etf"],
        "status": "closed",
        "coverage_status": "partial",
        "semantic_score": 0.91
      }
    ],
    "count": 1,
    "scope": "finance"
  },
  "meta": { "creditsUsed": 2, "remainingCredits": 98 }
}
```

### Event read 返回

<ResponseField name="data" type="PolymarketEvent">
  单张 event card，包含 browse/search 返回的字段，以及更完整的事件信息。
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Event read 固定为 `0`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

## 说明

<Tip>
  用户自然语言问题优先用 search。只有明确 list 或 exact lexical filters 时才用 browse（`status=active`、`query=ETF`、`min_volume=10000`）。选择 event 后先 read，让 agent 一次看到所有子问题。
</Tip>

<Tip>
  如果需要 market 层面的 outcomes 和概率历史，带着 event card 里的 `market_card_id` 继续看 [`预测市场 Market 详情`](/zh-CN/api/prediction-markets/markets)。
</Tip>

<Warning>
  这个产品面向金融范围。它不覆盖体育、娱乐、钱包状态、订单簿或交易动作。
</Warning>

<Warning>
  需要精确时间窗口时，用 `polymarket_event_browse`。`start_time` 和 `end_time` 必须同时传入，且 `start_time` 不得晚于 `end_time`。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 搜索 event
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_event_search",
        "arguments": { "query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5 }
      }
    }

    // 2) 读取选中的 event
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_event_read",
        "arguments": { "event_card_id": "pme_902959" }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    events = requests.post(
        f"{base}/api/polymarket/events/search",
        headers=headers,
        json={"query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5},
    ).json()["data"]["events"]

    event = requests.get(
        f"{base}/api/polymarket/events/{events[0]['event_card_id']}",
        headers=headers,
    ).json()["data"]
    print(event["title"], event["market_count"])
    ```

    ```bash cURL theme={null}
    curl -X POST "https://api.llmquantdata.com/api/polymarket/events/search" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5}'

    curl "https://api.llmquantdata.com/api/polymarket/events/pme_902959" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="polymarket_event_browse — 请求参数" icon="sliders">
    <ParamField type="string">
      `active`、`inactive`、`closed` 或 `active_or_recently_closed` 之一。
    </ParamField>

    <ParamField type="string">可选 exact lexical filter，匹配 event title、slug、tags、child market questions 和 outcome labels。最多 200 字符。</ParamField>
    <ParamField type="string">可选金融标签，例如 `crypto` 或 `policy`。</ParamField>
    <ParamField type="string">可选资产或实体过滤，例如 `BTC`。</ParamField>
    <ParamField type="string">ISO 8601 UTC 起始时间。必须和 `end_time` 一起使用。</ParamField>
    <ParamField type="string">ISO 8601 UTC 结束时间。必须和 `start_time` 一起使用。</ParamField>
    <ParamField type="number">可选的 event 级别市场成交量下限。</ParamField>
    <ParamField type="number">可选的 event 级别市场流动性下限。</ParamField>
    <ParamField type="number">返回 events 上限。范围 `1-100`。</ParamField>
    <ParamField type="string">来自 `data.nextCursor` 的分页 cursor。</ParamField>
  </Accordion>

  <Accordion title="polymarket_event_search — 请求参数" icon="magnifying-glass">
    <ParamField type="string">自然语言 query。最多 2,000 字符。</ParamField>

    <ParamField type="string">
      `active`、`inactive`、`closed` 或 `active_or_recently_closed` 之一。
    </ParamField>

    <ParamField type="string">可选金融标签。</ParamField>
    <ParamField type="number">返回 events 上限。范围 `1-20`。</ParamField>
  </Accordion>

  <Accordion title="polymarket_event_read — 请求参数" icon="file-lines">
    <ParamField type="string">
      Browse 或 search 返回的 event id；也接受 alias `pme_902959`。
    </ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns>
  <Card title="预测市场 Market 详情" icon="gauge-high" href="/zh-CN/api/prediction-markets/markets">
    读取 market outcomes 和隐含概率历史。
  </Card>

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


# 预测市场 Market 详情
Source: https://docs.llmquantdata.com/zh-CN/api/prediction-markets/markets

读取预测市场 market 卡片，并查询 outcome token 的小时或日度概率历史。

<Note icon="sparkles">
  **可作为 MCP 工具调用**：`polymarket_market_read` + `polymarket_price_history` —— 可在 Claude / Cursor / 任意 MCP 客户端中直接使用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · market read</Badge>
 
<Badge>免费 · price history</Badge>

## 它为 Agent 做什么

`polymarket_market_read` 用来读取从预测市场 event card 里选中的单个 market。它返回 market 问题、状态、outcomes、outcome token ids、标签、流动性、成交量和所属 event 信息，帮助 agent 判断下一步应该看哪个 outcome。

`polymarket_price_history` 接收这个 market 里的一个 `outcome_token_id`，返回 `1h` 或 `1d` 粒度的隐含概率点。用它展示市场概率如何随时间变化；不要把它当成 OHLCV K 线、订单簿深度或可成交报价。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: polymarket_market_read(market_card_id)
  MCP-->>Agent: market card · outcomes[] · outcomeTokenId
  alt outcome token 存在
    Agent->>MCP: polymarket_price_history(outcome_token_id, interval, range)
    MCP-->>Agent: points[] · probability · coverage status
  else outcome token 缺失
    Agent->>Agent: 只根据 market card 回答
  end
```

## 返回值

### Market read 返回

<ResponseField name="data" type="PolymarketMarket">
  单张 market card。

  <Expandable title="PolymarketMarket 字段">
    <ResponseField name="market_card_id" type="string">
      稳定的 LLMQuant market id。先读取 event card，再用它选择 market。
    </ResponseField>

    <ResponseField name="event_card_id" type="string">
      父级 event id。
    </ResponseField>

    <ResponseField name="market_question" type="string">
      Agent 应该引用或总结的 market 问题。
    </ResponseField>

    <ResponseField name="outcomes" type="PolymarketOutcome[]">
      Market 的不同结果。每个 outcome 可包含 `label`、`outcome_token_id`、`current_probability` 和最近的概率信息。
    </ResponseField>

    <ResponseField name="status" type="string">
      Market 状态：`active`、`inactive` 或 `closed`。
    </ResponseField>

    <ResponseField name="volume" type="number">有数据时返回 market 成交量。</ResponseField>
    <ResponseField name="liquidity" type="number">有数据时返回 market 流动性。</ResponseField>
    <ResponseField name="coverage_status" type="string">这张 market card 的数据可用状态。</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Market read 固定为 `0`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · market read" expandable theme={null}
{
  "data": {
    "market_card_id": "e370488a-33b5-4abd-8c5c-37c7ad8a60fc",
    "event_card_id": "4b8f35c6-4781-4f3c-9237-142fc16467cd",
    "market_question": "Bitcoin ETF approved by Jan 15?",
    "outcomes": [
      {
        "label": "Yes",
        "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
        "current_probability": 0.51,
        "last_price_time": "2024-01-10T00:00:00Z",
        "coverage_status": "partial"
      },
      { "label": "No", "outcome_token_id": null, "current_probability": 0.49 }
    ],
    "status": "closed",
    "volume": 1250000,
    "liquidity": 48000,
    "coverage_status": "partial"
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

### Price history 返回

<ResponseField name="data" type="PolymarketPriceHistory">
  单个 outcome token 的概率历史。

  <Expandable title="PolymarketPriceHistory 字段">
    <ResponseField name="outcome_token_id" type="string">请求的 outcome token。</ResponseField>
    <ResponseField name="interval" type="string">`1h` 或 `1d`。</ResponseField>

    <ResponseField name="points" type="PolymarketPricePoint[]">
      按时间排列的概率点。
    </ResponseField>

    <ResponseField name="coverage_status" type="string">
      这个 token 和时间范围的数据可用状态。
    </ResponseField>

    <ResponseField name="coverage_notice" type="string">
      面向用户和 agent 的可用性说明。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">返回的数据点数量。</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Price history 固定为 `0`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · price history" expandable theme={null}
{
  "data": {
    "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
    "interval": "1d",
    "points": [
      { "time": "2024-01-01T00:00:00Z", "probability": 0.39, "price": 0.39 },
      { "time": "2024-01-02T00:00:00Z", "probability": 0.42, "price": 0.42 }
    ],
    "coverage_status": "partial",
    "coverage_notice": "Partial probability history is available for the requested window.",
    "count": 2
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  从 [`预测市场事件`](/zh-CN/api/prediction-markets/events) 开始。Market id 和 outcome token id 都应该从 event card 里选，不要靠猜。
</Tip>

<Tip>
  叙事时间线优先用 `1d`；如果 agent 需要看某个事件日前后的日内变化，再用 `1h`。
</Tip>

<Warning>
  `interval` 只接受 `1h` 和 `1d`。`interval=15m` 这类请求会在扣 credit 前返回 `400`。
</Warning>

<Warning>
  Price history 返回的是单个 outcome token 的隐含概率点。它不是 OHLCV、订单簿数据、成交历史或投资建议。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 读取 market
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_market_read",
        "arguments": { "market_card_id": "pmm_253254" }
      }
    }

    // 2) 读取 Yes outcome 的日度概率历史
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_price_history",
        "arguments": {
          "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
          "interval": "1d",
          "start_time": "2024-01-01T00:00:00Z",
          "end_time": "2024-01-15T00:00:00Z"
        }
      }
    }
    ```

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

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    market = requests.get(
        f"{base}/api/polymarket/markets/pmm_253254",
        headers=headers,
    ).json()["data"]
    token = market["outcomes"][0]["outcome_token_id"]

    history = requests.get(
        f"{base}/api/polymarket/price-history",
        headers=headers,
        params={
            "outcome_token_id": token,
            "interval": "1d",
            "start_time": "2024-01-01T00:00:00Z",
            "end_time": "2024-01-15T00:00:00Z",
        },
    ).json()["data"]
    print(history["points"][:2])
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/polymarket/markets/pmm_253254" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    curl "https://api.llmquantdata.com/api/polymarket/price-history?outcome_token_id=98787006152320761811798607481686168525551752574583108841982899511109091268658&interval=1d&start_time=2024-01-01T00%3A00%3A00Z&end_time=2024-01-15T00%3A00%3A00Z" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="polymarket_market_read — 请求参数" icon="file-lines">
    <ParamField type="string">
      Event card 返回的 market id；也接受 alias `pmm_253254`。
    </ParamField>
  </Accordion>

  <Accordion title="polymarket_price_history — 请求参数" icon="chart-line">
    <ParamField type="string">
      `polymarket_market_read` 返回的 outcome token id。
    </ParamField>

    <ParamField type="string">
      `1h` 或 `1d`。
    </ParamField>

    <ParamField type="string">可选 inclusive ISO 8601 UTC 下边界。</ParamField>
    <ParamField type="string">可选 inclusive ISO 8601 UTC 上边界。</ParamField>
    <ParamField type="number">边界过滤后最多返回多少个点。`1h` 默认 `720`，`1d` 默认 `365`；最大 `20000`。</ParamField>
    <ParamField type="string">`latest` 或 `earliest`；输出仍按时间正序。</ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns>
  <Card title="预测市场事件" icon="gauge-high" href="/zh-CN/api/prediction-markets/events">
    先浏览、搜索并读取 event card，再选择 market。
  </Card>

  <Card title="预测市场概率历史" icon="chart-line" href="/zh-CN/api/prediction-markets/price-history">
    选好 outcome token 后，查询它的概率历史。
  </Card>
</Columns>


# 预测市场概率历史
Source: https://docs.llmquantdata.com/zh-CN/api/prediction-markets/price-history

查询单个预测市场 outcome token 的小时或日度隐含概率历史。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`polymarket_price_history` - 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费</Badge>

## 它为 Agent 做什么

`polymarket_price_history` 返回某个 outcome 的隐含概率如何随时间变化。Agent 选好 market outcome 后，如果要画时间线、复盘事件、或解释概率变化，就调用它。

传入 `outcome_token_id`，选择 `1h` 或 `1d`，也可以指定一个或两个 UTC 时间边界，再用 `limit` 和 `take_from` 决定保留哪一端。返回值会按时间给出 `time`、`probability` 和 `price`。

## 返回值

<ResponseField name="data" type="PolymarketPriceHistory">
  单个 outcome token 的概率历史。

  <Expandable title="PolymarketPriceHistory 字段">
    <ResponseField name="outcome_token_id" type="string">
      你请求的 outcome token。
    </ResponseField>

    <ResponseField name="interval" type="string">
      `1h` 或 `1d`。
    </ResponseField>

    <ResponseField name="points" type="PolymarketPricePoint[]">
      按时间排列的概率点。每个点包含 `time`、`probability` 和 `price`。
    </ResponseField>

    <ResponseField name="coverage_status" type="string">
      这个 token 和时间范围的数据可用状态。
    </ResponseField>

    <ResponseField name="coverage_notice" type="string">
      简短说明这次查到了哪些数据。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">返回的数据点数量。</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用固定为 `0`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>
<ResponseField name="meta.notice" type="string">仅在候选窗口内的数据多于实际返回条数时出现 —— 也就是结果被 `limit` 截断了。这句话提示 agent 缩小窗口或把查询拆成多次：`More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · polymarket_price_history" expandable theme={null}
{
  "data": {
    "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
    "interval": "1d",
    "points": [
      { "time": "2024-01-01T00:00:00Z", "probability": 0.39, "price": 0.39 },
      { "time": "2024-01-02T00:00:00Z", "probability": 0.42, "price": 0.42 }
    ],
    "coverage_status": "partial",
    "coverage_notice": "Partial probability history is available for the requested window.",
    "count": 2
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  先从 [`预测市场事件`](/zh-CN/api/prediction-markets/events) 开始，读取选中的 market，再把返回的某个 `outcome_token_id` 传到这里。
</Tip>

<Tip>
  看长期变化时用 `1d`。如果 agent 需要解释某一天或某条消息附近的变化，再用 `1h`。
</Tip>

<Warning>
  `interval` 只接受 `1h` 和 `1d`。`interval=15m` 这类请求会在扣 credit 前返回 `400`。
</Warning>

<Warning>
  这里返回的是单个 outcome 的隐含概率点。它不是 OHLCV 数据、订单簿、成交历史或投资建议。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_price_history",
        "arguments": {
          "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
          "interval": "1d",
          "start_time": "2024-01-01T00:00:00Z",
          "end_time": "2024-01-15T00:00:00Z",
          "limit": 10,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/polymarket/price-history",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={
            "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
            "interval": "1d",
            "start_time": "2024-01-01T00:00:00Z",
            "end_time": "2024-01-15T00:00:00Z",
            "limit": 10,
            "take_from": "earliest",
        },
    ).json()
    print(resp["data"]["points"][:2])
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/polymarket/price-history?outcome_token_id=98787006152320761811798607481686168525551752574583108841982899511109091268658&interval=1d&start_time=2024-01-01T00%3A00%3A00Z&end_time=2024-01-15T00%3A00%3A00Z&limit=10&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="polymarket_price_history — 请求参数" icon="chart-line">
  <ParamField type="string">
    `polymarket_market_read` 返回的 outcome token id。
  </ParamField>

  <ParamField type="string">
    `1h` 或 `1d`。
  </ParamField>

  <ParamField type="string">可选 inclusive ISO 8601 UTC 下边界。</ParamField>
  <ParamField type="string">可选 inclusive ISO 8601 UTC 上边界。</ParamField>
  <ParamField type="number">边界过滤后最多返回多少个点。`1h` 默认 `720`，`1d` 默认 `365`；最大 `20000`。</ParamField>
  <ParamField type="string">当过滤后候选超过 `limit` 时保留哪一端：`latest` 或 `earliest`。输出仍按时间正序。</ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="预测市场事件" icon="gauge-high" href="/zh-CN/api/prediction-markets/events">
    先浏览、搜索并读取 event card，再选择 market。
  </Card>

  <Card title="预测市场 Market 详情" icon="file-lines" href="/zh-CN/api/prediction-markets/markets">
    读取 market outcomes，并复制需要的 `outcome_token_id`。
  </Card>
</Columns>


# 加密货币历史 K 线
Source: https://docs.llmquantdata.com/zh-CN/api/prices/crypto-historical

加密货币交易对的 OHLCV K 线 —— 支持 limit/take_from 选择，含 1h / 4h / 1d / 1w 周期。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`crypto_historical_klines` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>每次 1 credit</Badge>

## 它为 Agent 做什么

`crypto_historical_klines` 返回单个加密货币交易对的 OHLCV K 线。它是 agent 拿历史价格做收益率、回撤、技术指标、回测的 **历史价格 primitive** —— 不是用来取最新报价的工具（取最新价用 `crypto_snapshot`）。

用 `start_time` 和/或 `end_time` 先过滤候选窗口，再用 `limit` 和 `take_from` 决定保留哪一端。返回顺序始终是旧到新。**只返回已收盘的 candle**，当前未收盘的 bar 永远不在结果里。

## 返回值

<ResponseField name="data" type="CryptoHistoricalResult">
  <Expandable title="CryptoHistoricalResult 字段">
    <ResponseField name="ticker" type="string">
      交易对，`BASE-QUOTE` 格式（如 `BTC-USD`）。
    </ResponseField>

    <ResponseField name="interval" type="string">
      K 线周期（`1h` / `4h` / `1d` / `1w`）。
    </ResponseField>

    <ResponseField name="prices" type="CryptoKlineBar[]">
      按时间正序返回的 K 线数组。仅含已收盘 candle。

      <Expandable title="CryptoKlineBar 字段">
        <ResponseField name="open" type="number">开盘价。</ResponseField>
        <ResponseField name="high" type="number">最高价。</ResponseField>
        <ResponseField name="low" type="number">最低价。</ResponseField>
        <ResponseField name="close" type="number">收盘价。</ResponseField>
        <ResponseField name="volume" type="number">基础资产成交量。</ResponseField>
        <ResponseField name="time" type="string">K 线开盘时间（ISO 8601 UTC）。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>
<ResponseField name="meta.notice" type="string">仅在候选窗口内的数据多于实际返回条数时出现 —— 也就是结果被 `limit` 截断了。这句话提示 agent 缩小窗口或把查询拆成多次：`More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · crypto_historical_klines" expandable theme={null}
{
  "data": {
    "ticker": "BTC-USD",
    "interval": "1d",
    "prices": [
      {
        "open": 87000.50,
        "high": 87500.00,
        "low": 86800.00,
        "close": 87200.00,
        "volume": 1234.56,
        "time": "2026-03-01T00:00:00Z"
      },
      {
        "open": 87200.00,
        "high": 88100.00,
        "low": 87000.00,
        "close": 87950.00,
        "volume": 1456.78,
        "time": "2026-03-02T00:00:00Z"
      }
    ]
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  要 **最新行情**（价格 + 24h 涨跌）用 `crypto_snapshot`，那是另一个 primitive，不需要拉一串 K 线。`crypto_historical_klines` 只在你需要一系列 bar 时才用。
</Tip>

<Tip>
  首次查询某个 ticker + interval + range 可能较慢。同一窗口的后续查询通常更快。
</Tip>

<Tip>
  需要返回的 bar 数时直接读 `data.prices.length`；`meta` 只保留 credit 和可选 notice。
</Tip>

<Warning>
  **仅现货市场**。合约、永续、资金费率、持仓量都不暴露。
</Warning>

<Warning>
  **不支持分钟级**。`1m`、`5m`、`15m` 都不行 —— 只能用 `1h`、`4h`、`1d`、`1w`。
</Warning>

<Warning>
  **仅返回已收盘 candle**。当前未收盘的 bar 永远不在结果里。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 不传时间边界 —— 最近 30 根日线
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_historical_klines",
        "arguments": { "ticker": "BTC-USD", "interval": "1d", "limit": 30 }
      }
    }

    // 时间窗口内最早 12 根
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_historical_klines",
        "arguments": {
          "ticker": "ETH-USD",
          "interval": "1h",
          "start_time": "2026-03-01T00:00:00Z",
          "end_time": "2026-03-02T00:00:00Z",
          "limit": 12,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 不传时间边界 —— 最近的若干根
    resp = requests.get(
        "https://api.llmquantdata.com/api/crypto/historical",
        headers=headers,
        params={"ticker": "BTC-USD", "interval": "1d", "limit": 30},
    ).json()
    for bar in resp["data"]["prices"]:
        print(f"{bar['time']}  C={bar['close']}  V={bar['volume']}")

    # 时间窗口内最早 12 根
    resp = requests.get(
        "https://api.llmquantdata.com/api/crypto/historical",
        headers=headers,
        params={
            "ticker": "ETH-USD",
            "interval": "1h",
            "start_time": "2026-03-01T00:00:00Z",
            "end_time": "2026-03-02T00:00:00Z",
            "limit": 12,
            "take_from": "earliest",
        },
    ).json()
    print(f"Bounded query returned {len(resp['data']['prices'])} 根 bar")
    ```

    ```bash cURL theme={null}
    # 不传时间边界 —— 最近的若干根
    curl "https://api.llmquantdata.com/api/crypto/historical?ticker=BTC-USD&interval=1d&limit=30" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 时间窗口内最早 12 根
    curl "https://api.llmquantdata.com/api/crypto/historical?ticker=ETH-USD&interval=1h&start_time=2026-03-01T00:00:00Z&end_time=2026-03-02T00:00:00Z&limit=12&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="crypto_historical_klines — 请求参数" icon="sliders">
  <ParamField type="string">
    交易对，`BASE-QUOTE` 格式。例：`BTC-USD`、`ETH-USD`、`SOL-USD`。
  </ParamField>

  <ParamField type="string">
    K 线周期。可选值：`1h`、`4h`、`1d`、`1w`。不支持分钟级。
  </ParamField>

  <ParamField type="string">
    可选 inclusive 下边界，ISO 8601 UTC（如 `2026-03-01T00:00:00Z`）。
  </ParamField>

  <ParamField type="string">
    可选 inclusive 上边界，ISO 8601 UTC。
  </ParamField>

  <ParamField type="integer">
    边界过滤后最多返回多少根 candle。按 interval 自适应默认：`1h` = 24，`4h` = 42，`1d` = 30，`1w` = 12。最大 `200`。
  </ParamField>

  <ParamField type="string">
    当过滤后候选超过 `limit` 时保留哪一端：`latest` 或 `earliest`。输出仍按时间正序。
  </ParamField>

  <Warning>
    `take_from=earliest` 需要 `start_time`。如果同时传两个时间边界，`start_time` 不能晚于 `end_time`。
  </Warning>
</Accordion>

## 相关接口

<Columns>
  <Card title="加密货币实时快照" icon="bolt" href="/zh-CN/api/prices/crypto-snapshot">
    交易对的当前价格 + 24h 涨跌 —— 只关心"现在"时用这个。
  </Card>

  <Card title="美股历史日线" icon="square-chart-gantt" href="/zh-CN/api/prices/equity-historical">
    同样的有界 historical-series 形状，作用在美股标的（日线）。
  </Card>
</Columns>


# 加密货币实时快照
Source: https://docs.llmquantdata.com/zh-CN/api/prices/crypto-snapshot

加密货币交易对的当前价格 + 24h 行情。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`crypto_snapshot` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · snapshot</Badge>

## 它为 Agent 做什么

`crypto_snapshot` 返回单个加密货币交易对的当前现货价格 + 24 小时涨跌与成交量。它是 agent 的 **价格 checkpoint**——任务过程中要验证当前价位、比较资产、或给市场打一个 regime tag 时，不需要拉完整 K 线，调它一次就够。

`crypto_snapshot({ ticker })` → `price`、`dayChange`、`dayChangePercent`、`volume24h`、`time`。仅此而已。

## 返回值

<ResponseField name="data" type="CryptoSnapshot">
  <Expandable title="CryptoSnapshot 字段">
    <ResponseField name="ticker" type="string">
      交易对，`BASE-QUOTE` 格式（如 `BTC-USD`）。
    </ResponseField>

    <ResponseField name="price" type="number">
      最新成交价。
    </ResponseField>

    <ResponseField name="dayChange" type="number">
      24 小时绝对涨跌。
    </ResponseField>

    <ResponseField name="dayChangePercent" type="number">
      24 小时涨跌幅（%）。
    </ResponseField>

    <ResponseField name="volume24h" type="number">
      24 小时基础资产成交量。
    </ResponseField>

    <ResponseField name="time" type="string">
      快照时间戳（ISO-8601 UTC）。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— 本接口免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · crypto_snapshot" expandable theme={null}
{
  "data": {
    "ticker": "BTC-USD",
    "price": 87200.00,
    "dayChange": 1200.50,
    "dayChangePercent": 1.26,
    "volume24h": 12345678,
    "time": "2026-04-29T12:30:00Z"
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  需要**历史 K 线**用 `crypto_historical_klines` —— 返回 `1h`、`4h`、`1d` 或 `1w` 周期的 OHLCV 蜡烛。`crypto_snapshot` 只关心"现在"。
</Tip>

<Warning>
  **仅现货市场**。合约、永续、资金费率、持仓量都不通过这个工具暴露。
</Warning>

<Warning>
  非交易级实时。可能比最新市场成交滞后最多 30 秒，**不要拿来交易**。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    {
      "method": "tools/call",
      "params": {
        "name": "crypto_snapshot",
        "arguments": { "ticker": "BTC-USD" }
      }
    }
    ```

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

    resp = requests.get(
        "https://api.llmquantdata.com/api/crypto/snapshot",
        headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
        params={"ticker": "BTC-USD"},
    ).json()
    d = resp["data"]
    print(f"{d['ticker']}: ${d['price']:,.2f} ({d['dayChangePercent']:+.2f}%)")
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/crypto/snapshot?ticker=BTC-USD" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="crypto_snapshot — 请求参数" icon="sliders">
  <ParamField type="string">
    交易对，`BASE-QUOTE` 格式。例：`BTC-USD`、`ETH-USD`、`SOL-USD`。
  </ParamField>
</Accordion>

## 相关接口

<Columns>
  <Card title="加密货币历史 K 线" icon="chart-line" href="/zh-CN/api/prices/crypto-historical">
    `1h`、`4h`、`1d` 或 `1w` 周期的 OHLCV 蜡烛。
  </Card>

  <Card title="美股价格快照" icon="square-chart-gantt" href="/zh-CN/api/prices/equity-historical">
    同样的形态用在美股标的（不同 endpoint）。
  </Card>
</Columns>


# 美股历史日线
Source: https://docs.llmquantdata.com/zh-CN/api/prices/equity-historical

美股历史 OHLCV 日线 —— 用日期窗口筛选，再用 limit/take_from 取有界的一段，含 adjusted close、分红、拆股。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`equity_historical_prices` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>免费 · daily bars</Badge>

## 它为 Agent 做什么

`equity_historical_prices` 返回单个美股标的（NYSE / NASDAQ）的历史 OHLCV 日线，附 `adjusted_close`、`dividend`、`stock_split`。它是 agent 拿历史价格做收益率、回撤、回测的 **历史价格 primitive** —— 不是用来取最新报价的工具。

用 `start_date` 和/或 `end_date` 先过滤候选窗口，再用 `limit` 和 `take_from` 决定保留哪一端。返回顺序始终是旧到新。**只返回已收盘的交易日**，当日未收盘的 bar 永远不在结果里。

## 返回值

<ResponseField name="data" type="EquityHistoricalResult">
  <Expandable title="EquityHistoricalResult 字段">
    <ResponseField name="ticker" type="string">
      美股 ticker（如 `AAPL`）。
    </ResponseField>

    <ResponseField name="interval" type="string">
      固定 `"1d"`，仅支持日线。
    </ResponseField>

    <ResponseField name="prices" type="EquityDailyBar[]">
      按时间正序返回的日线数组。仅含已收盘交易日。

      <Expandable title="EquityDailyBar 字段">
        <ResponseField name="open" type="number">开盘价。</ResponseField>
        <ResponseField name="high" type="number">最高价。</ResponseField>
        <ResponseField name="low" type="number">最低价。</ResponseField>
        <ResponseField name="close" type="number">收盘价。</ResponseField>
        <ResponseField name="volume" type="number">成交量。</ResponseField>
        <ResponseField name="adjusted_close" type="number">分红/拆股复权后收盘价。算收益率统一用这个字段。</ResponseField>
        <ResponseField name="dividend" type="number">当日分红金额（无分红为 `0`）。</ResponseField>
        <ResponseField name="stock_split" type="number">当日拆股比例（无拆股为 `0`）。</ResponseField>
        <ResponseField name="time" type="string">交易日（`YYYY-MM-DD`）。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">固定 `0` —— 本接口免费。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>
<ResponseField name="meta.notice" type="string">仅在候选窗口内的数据多于实际返回条数时出现 —— 也就是结果被 `limit` 截断了。这句话提示 agent 缩小窗口或把查询拆成多次：`More data exists in the requested window than the items returned; narrow the window or split the query to see more.`</ResponseField>

```json title="200 OK · equity_historical_prices" expandable theme={null}
{
  "data": {
    "ticker": "AAPL",
    "interval": "1d",
    "prices": [
      {
        "open": 178.50,
        "high": 182.30,
        "low": 177.80,
        "close": 181.20,
        "volume": 52340000,
        "adjusted_close": 181.20,
        "dividend": 0.24,
        "stock_split": 0,
        "time": "2025-03-28"
      },
      {
        "open": 181.00,
        "high": 183.50,
        "low": 180.20,
        "close": 182.90,
        "volume": 48120000,
        "adjusted_close": 182.90,
        "dividend": 0,
        "stock_split": 0,
        "time": "2025-03-31"
      }
    ]
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  **算收益率统一用 `adjusted_close`** —— 它已经处理了分红和拆股。原始 `close` 只在画 K 线图等纯展示场景才适合。
</Tip>

<Tip>
  首次查询某个 ticker + range 可能较慢。同一窗口的后续查询通常更快。
</Tip>

<Tip>
  需要返回的 bar 数时直接读 `data.prices.length`；`meta` 只保留 credit 和可选 notice。
</Tip>

<Warning>
  **仅美股**（NYSE / NASDAQ）。不含非美股 ADR，不含国际市场。
</Warning>

<Warning>
  **仅日线**。分钟级（`1m`、`5m`、`15m`）不支持。需要 `1h` 常规交易时段 bar，请用 [`equity_intraday_prices`](/zh-CN/api/prices/equity-intraday)。
</Warning>

<Warning>
  **没有实时报价**。当日未收盘的 bar 不在结果里。要拿"最新价"用别的工具。
</Warning>

<Warning>
  覆盖范围很广，但不保证所有标的都有数据。少数流动性差的 ticker 偶尔会返回空。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 不传日期边界 —— 最近 30 个交易日
    {
      "method": "tools/call",
      "params": {
        "name": "equity_historical_prices",
        "arguments": { "ticker": "AAPL", "limit": 30 }
      }
    }

    // 日期窗口内最早 10 根
    {
      "method": "tools/call",
      "params": {
        "name": "equity_historical_prices",
        "arguments": {
          "ticker": "MSFT",
          "start_date": "2025-04-01",
          "end_date": "2025-04-30",
          "limit": 10,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # 不传日期边界 —— 最近的若干根
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/historical",
        headers=headers,
        params={"ticker": "AAPL", "limit": 30},
    ).json()
    for bar in resp["data"]["prices"]:
        print(f"{bar['time']}  C={bar['close']:.2f}  V={bar['volume']}")

    # 日期窗口内最早 10 根
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/historical",
        headers=headers,
        params={
            "ticker": "MSFT",
            "start_date": "2025-04-01",
            "end_date": "2025-04-30",
            "limit": 10,
            "take_from": "earliest",
        },
    ).json()
    print(f"Bounded query returned {len(resp['data']['prices'])} bars")
    ```

    ```bash cURL theme={null}
    # 不传日期边界 —— 最近的若干根
    curl "https://api.llmquantdata.com/api/equity/historical?ticker=AAPL&limit=30" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 日期窗口内最早 10 根
    curl "https://api.llmquantdata.com/api/equity/historical?ticker=MSFT&start_date=2025-04-01&end_date=2025-04-30&limit=10&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="equity_historical_prices — 请求参数" icon="sliders">
  <ParamField type="string">
    美股 ticker（如 `AAPL`、`MSFT`、`BRK.B`、`^GSPC`（S\&P 500 指数））。
  </ParamField>

  <ParamField type="string">
    可选 inclusive 下边界，`YYYY-MM-DD`（如 `2025-04-01`）。
  </ParamField>

  <ParamField type="string">
    可选 inclusive 上边界，`YYYY-MM-DD`。
  </ParamField>

  <ParamField type="integer">
    边界过滤后最多返回多少个交易日。默认 `30`，最大 `200`。
  </ParamField>

  <ParamField type="string">
    当过滤后候选超过 `limit` 时保留哪一端：`latest` 或 `earliest`。输出仍按时间正序。
  </ParamField>

  <Warning>
    `take_from=earliest` 需要 `start_date`。如果同时传两个日期边界，`start_date` 不能晚于 `end_date`。
  </Warning>
</Accordion>

## 相关接口

<Columns>
  <Card title="美股盘中行情" icon="clock" href="/zh-CN/api/prices/equity-intraday">
    同一批美股的 `1h` 常规交易时段 bar —— 短窗口搭档。
  </Card>

  <Card title="加密货币历史 K 线" icon="chart-line" href="/zh-CN/api/prices/crypto-historical">
    同样的有界 historical-series 形状，作用在加密货币交易对（含小时级）。
  </Card>

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


# 美股盘中行情
Source: https://docs.llmquantdata.com/zh-CN/api/prices/equity-intraday

美股 1h 盘中 OHLCV —— 最近 N 根，或一段不超过 14 个自然日的日期窗口，仅含常规交易时段。

<Note icon="sparkles">
  **已暴露为 MCP 工具**：`equity_intraday_prices` —— 在 Claude / Cursor / 任意 MCP 客户端中直接调用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>每次 1 credit</Badge>

## 它为 Agent 做什么

`equity_intraday_prices` 返回单个美股标的（NYSE / NASDAQ）在 **常规交易时段** 的 **1h** OHLCV 盘中 bar。它是 agent 回答"今天 / 最近几天盘中怎么走、有没有跳空、有没有反转、收盘前怎么动"这类问题的 **盘中价格 primitive** —— 不用拉过细的分钟级数据。

它是 [`equity_historical_prices`](/zh-CN/api/prices/equity-historical) 的短窗口搭档：同属 equity bars 家族、同一套返回信封，但返回的是盘中 bar。用 `start_date` 和/或 `end_date` 先过滤候选窗口，再用 `limit` 和 `take_from` 决定保留哪一端。查询窗口最多 **14 个自然日**。**只返回已收盘的 bar**，当前未走完的 bar 永远不在结果里。

## 返回值

<ResponseField name="data" type="EquityIntradayResult">
  <Expandable title="EquityIntradayResult 字段">
    <ResponseField name="ticker" type="string">
      美股 ticker（如 `AAPL`）。
    </ResponseField>

    <ResponseField name="interval" type="string">
      固定 `"1h"`，仅支持小时线。
    </ResponseField>

    <ResponseField name="prices" type="EquityIntradayBar[]">
      按时间正序返回的小时线数组。仅含常规交易时段、已收盘的 bar。

      <Expandable title="EquityIntradayBar 字段">
        <ResponseField name="open" type="number">该 bar 的开盘价。</ResponseField>
        <ResponseField name="high" type="number">该 bar 的最高价。</ResponseField>
        <ResponseField name="low" type="number">该 bar 的最低价。</ResponseField>
        <ResponseField name="close" type="number">该 bar 的收盘价。</ResponseField>
        <ResponseField name="volume" type="number">该 bar 内的成交量。</ResponseField>
        <ResponseField name="time" type="string">bar 起始时间，ISO 8601 UTC 时间戳（如 `2026-06-18T14:30:00Z`）。</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">本次调用消耗的 credit（固定 `1`）。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · equity_intraday_prices" expandable theme={null}
{
  "data": {
    "ticker": "AAPL",
    "interval": "1h",
    "prices": [
      {
        "open": 181.20,
        "high": 181.95,
        "low": 180.85,
        "close": 181.60,
        "volume": 4821000,
        "time": "2026-06-18T13:30:00Z"
      },
      {
        "open": 181.60,
        "high": 182.40,
        "low": 181.40,
        "close": 182.10,
        "volume": 3950000,
        "time": "2026-06-18T14:30:00Z"
      }
    ]
  },
  "meta": { "creditsUsed": 1, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  `time` 是 ISO 8601 **UTC** 时间戳，标记每根 bar 的起始时刻。bar 覆盖美股常规交易时段，需要交易所本地时间时请转换到 `America/New_York`。
</Tip>

<Tip>
  需要本次返回 bar 数时，用 `data.prices.length`；`meta` 只放 credit 和可选 notice。
</Tip>

<Warning>
  **仅小时线**。分钟级（`1m`、`5m`、`15m`）和 `30m` 都不支持。传 `interval=1h` 或省略；传其他值会返回 `400`。
</Warning>

<Warning>
  **仅常规交易时段**。不含盘前 / 盘后 bar。需要完整交易日请用 [`equity_historical_prices`](/zh-CN/api/prices/equity-historical)。
</Warning>

<Warning>
  **没有实时报价**。当前正在形成、未收盘的 bar 不在结果里。要拿"最新价"用别的工具。
</Warning>

<Warning>
  **最多 14 个自然日**。查询窗口（含两端）不能超过 14 个自然日，更宽的窗口返回 `400`，且不扣 credit。判据看**有效窗口**：`end_date` 省略时按当前美东日期算，所以只传 `start_date=2015-01-01` 一样会被拒。请缩小窗口，或改用 [`equity_historical_prices`](/zh-CN/api/prices/equity-historical) 拉更长区间的日线。
</Warning>

<Warning>
  返回始终由 `limit` 收敛（默认 `35`，最大 `70`）。要看长期历史请用日线。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // Recent 模式 —— 最近 35 根（约 5 个交易日）
    {
      "method": "tools/call",
      "params": {
        "name": "equity_intraday_prices",
        "arguments": { "ticker": "AAPL", "limit": 35 }
      }
    }

    // 日期窗口内最早 10 根
    {
      "method": "tools/call",
      "params": {
        "name": "equity_intraday_prices",
        "arguments": {
          "ticker": "MSFT",
          "start_date": "2026-06-08",
          "end_date": "2026-06-18",
          "limit": 10,
          "take_from": "earliest"
        }
      }
    }
    ```

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

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    # Recent 模式
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/intraday",
        headers=headers,
        params={"ticker": "AAPL", "limit": 35},
    ).json()
    for bar in resp["data"]["prices"]:
        print(f"{bar['time']}  C={bar['close']:.2f}  V={bar['volume']}")

    # 日期窗口内最早 10 根
    resp = requests.get(
        "https://api.llmquantdata.com/api/equity/intraday",
        headers=headers,
        params={
            "ticker": "MSFT",
            "start_date": "2026-06-08",
            "end_date": "2026-06-18",
            "limit": 10,
            "take_from": "earliest",
        },
    ).json()
    print(f"Bounded query returned {len(resp['data']['prices'])} bars")
    ```

    ```bash cURL theme={null}
    # Recent 模式
    curl "https://api.llmquantdata.com/api/equity/intraday?ticker=AAPL&limit=35" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    # 日期窗口内最早 10 根
    curl "https://api.llmquantdata.com/api/equity/intraday?ticker=MSFT&start_date=2026-06-08&end_date=2026-06-18&limit=10&take_from=earliest" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<Accordion title="equity_intraday_prices — 请求参数" icon="sliders">
  <ParamField type="string">
    美股 ticker（如 `AAPL`、`MSFT`、`BRK.B`、`^GSPC`（S\&P 500 指数））。
  </ParamField>

  <ParamField type="string">
    bar 周期。仅支持 `1h`；传其他值会返回 `400`。
  </ParamField>

  <ParamField type="string">
    可选 inclusive 交易日下边界，`YYYY-MM-DD`（按 `America/New_York` 解释）。它开出的窗口必须落在 `end_date` 之前 14 个自然日内；`end_date` 省略时按当前美东日期算。
  </ParamField>

  <ParamField type="string">
    可选 inclusive 交易日上边界，`YYYY-MM-DD`（按 `America/New_York` 解释）。省略时默认取当前美东日期。
  </ParamField>

  <ParamField type="integer">
    边界过滤后最多返回多少根 `1h` bar。默认 `35`，最大 `70`。
  </ParamField>

  <ParamField type="string">
    当过滤后候选超过 `limit` 时保留哪一端：`latest` 或 `earliest`。输出仍按时间正序。
  </ParamField>

  <Warning>
    `take_from=earliest` 需要 `start_date`。如果同时传两个日期边界，`start_date` 不能晚于 `end_date`。无论哪种情况，最终窗口都不能超过 14 个自然日，否则返回 `400` 且不扣 credit。
  </Warning>
</Accordion>

## 相关接口

<Columns>
  <Card title="美股历史日线" icon="chart-line" href="/zh-CN/api/prices/equity-historical">
    日线 OHLCV，含复权价、分红、拆股 —— 长窗口搭档。
  </Card>

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


# 认证
Source: https://docs.llmquantdata.com/zh-CN/authentication

一把 API Key —— 给 MCP 客户端做环境变量，或直接做 HTTP 请求头。

<Note icon="key">
  在 [Dashboard → API Keys](https://llmquantdata.com/dashboard) 生成 Key。
</Note>

<Warning>
  请像对待密码一样保护 API Key —— **不要**提交到源码、**不要**暴露在前端代码、**不要**贴进 chat 会话。
</Warning>

## 获取 API Key

<Steps>
  <Step title="登录" icon="user">
    打开 [llmquantdata.com](https://llmquantdata.com) 注册或登录。
  </Step>

  <Step title="创建 API Key" icon="key">
    进入 [Dashboard](https://llmquantdata.com/dashboard) → **API Keys** → **Create API key**。**只显示一次，请立即复制保存**。
  </Step>

  <Step title="保存为环境变量" icon="terminal">
    ```bash theme={null}
    export LLMQUANT_API_KEY=your_api_key_here
    ```

    加进 shell profile（`~/.zshrc` / `~/.bashrc`）让它持久化。下面 MCP 与 HTTP 两种用法都从这一份环境变量读取。
  </Step>
</Steps>

## 怎么用

<Tabs>
  <Tab title="MCP runtime（推荐）">
    所有支持的 MCP 客户端（Claude Code / Cursor / Codex / Gemini CLI / Claude Desktop）都从 `LLMQUANT_API_KEY` 读取。写 JSON 配置文件时，请在 `env` 块里填真实 key。

    详见 [MCP Server 接入](/zh-CN/integration/mcp-server#%E5%BF%AB%E9%80%9F%E6%8E%A5%E5%85%A5) 的逐客户端命令。

    ```json title="例：Cursor / Claude Desktop 配置片段" theme={null}
    {
      "mcpServers": {
        "llmquant-data": {
          "command": "npx",
          "args": ["-y", "@llmquant/data-mcp"],
          "env": {
            "LLMQUANT_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="HTTP（直调）">
    每个请求在 `Authorization` 请求头传 key：

    <CodeGroup>
      ```bash cURL theme={null}
      curl "https://api.llmquantdata.com/api/equity/historical?ticker=AAPL&limit=5" \
        -H "Authorization: Bearer $LLMQUANT_API_KEY"
      ```

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

      response = requests.get(
          "https://api.llmquantdata.com/api/equity/historical",
          headers={"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"},
          params={"ticker": "AAPL", "limit": 5},
      )
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 错误码

| 状态码                | 含义                  |
| ------------------ | ------------------- |
| <Badge>200</Badge> | 请求成功                |
| <Badge>400</Badge> | 请求错误 — 参数无效或缺失      |
| <Badge>401</Badge> | 未授权 — API Key 无效或缺失 |
| <Badge>402</Badge> | Credits 不足 — 需要充值余额 |
| <Badge>404</Badge> | 未找到 — Ticker 或资源不存在 |
| <Badge>429</Badge> | 请求频率超限              |

## 频率限制

频率限制根据套餐不同而异。超出限制返回 `429`。如需更高限额，请联系我们。

<Tip>
  在 `429` 时静默重试的 MCP runtime 会快速烧 credit。排查异常账单时记得查 agent 的 tool-call log。
</Tip>

## 更换或撤销 Key

需要更换 Key 时，先在 [Dashboard → API Keys](https://llmquantdata.com/dashboard) 创建新 Key，更新各个环境，再撤销旧 Key。继续使用已撤销 Key 的请求会返回 `401`。

<Warning>
  撤销旧 Key 前，**所有**用 MCP 的环境都要更新 `LLMQUANT_API_KEY` —— shell profile、CI secrets、团队 onboarding 模板都不能漏。
</Warning>


# MCP Server
Source: https://docs.llmquantdata.com/zh-CN/integration/mcp-server

AI-native 金融数据的 knowledge harness —— 一次配置，所有 agent 自动接入。

<Note icon="sparkles">
  **`@llmquant/data-mcp`** —— 一份配置，让所有 MCP 客户端获得 26 个金融数据与个人 context 工具。源码：[`LLMQuant/data-mcp`](https://github.com/LLMQuant/data-mcp)。
</Note>

<Badge icon="circle-check">已上线</Badge>
 
<Badge>npm · @llmquant/data-mcp</Badge>

## 为什么是 MCP

LLMQuant Data 是 **agent-first** 设计。REST API 是 fallback；规范接口是 [Model Context Protocol](https://modelcontextprotocol.io) —— 这套标准让所有 agent runtime（Claude / Cursor / Codex / Gemini CLI / OpenClaw / ChatGPT custom GPT…）以**结构化参数 + 类型化结果**的方式直接调用我们的数据工具，**不需要任何 glue code**。

<Tip>
  **配置一次，下面所有环境自动接入。**
</Tip>

## 在哪里能用

<Columns>
  <Card title="Chatbot" icon="message">
    ChatGPT · Claude · Cursor
  </Card>

  <Card title="Agent CLI" icon="terminal">
    Claude Code · Codex · Gemini CLI · OpenClaw
  </Card>

  <Card title="SDK" icon="code">
    LangGraph · Google ADK · Vercel AI SDK
  </Card>
</Columns>

只要你的 runtime 支持 MCP，LLMQuant Data 就只差一份配置。

## Remote connectors

Claude web、Claude iOS 和其他云端 agent 不能运行本地 `npx` stdio server。改用 hosted Streamable HTTP endpoint：

<Steps>
  <Step title="生成 Remote MCP URL" icon="link">
    登录 [Dashboard](https://llmquantdata.com/dashboard) → **Connect** → **Remote MCP URL**。创建时复制一次 URL。

    ```text theme={null}
    https://mcp.llmquantdata.com/u/lqd_mcp_.../mcp
    ```
  </Step>

  <Step title="粘到 Claude custom connectors" icon="plug">
    选择 Claude 的 **No Authentication** connector mode，粘贴完整 URL。token 放在 URL path 里，LLMQuant Data 只存 hash，可在 Dashboard 独立吊销，不需要轮换 API key。
  </Step>

  <Step title="验证 credit 和 revoke" icon="circle-check">
    跑一次付费 search 或 read tool，确认 Dashboard 余额变化；再 revoke 一条测试 URL，确认它立即失败。
  </Step>
</Steps>

<Note>
  本地桌面端和 CLI 客户端可以继续用下面的 stdio 配置。Remote URL 面向需要公网 HTTPS MCP endpoint 的云端客户端和通过 Claude 同步的 connector。
</Note>

## 快速接入

<Steps>
  <Step title="获取 API key" icon="key">
    登录 [Dashboard](https://llmquantdata.com/dashboard) → **API Keys** → **Create API key**。保存为环境变量 `LLMQUANT_API_KEY`。
  </Step>

  <Step title="把 data-mcp 加进客户端" icon="plug">
    **把下面这段 prompt 丢进 agent —— 它会从 GitHub 读 canonical 配置：**

    ```text theme={null}
    Install the LLMQuant data-mcp server in this environment by following https://github.com/LLMQuant/data-mcp
    ```

    <Accordion title="或者手动安装" icon="terminal">
      选你的 runtime，下面是 canonical 配置 —— 直接复制粘贴，保存，重启客户端。

      <Tabs>
        <Tab title="Claude Code">
          ```bash theme={null}
          claude mcp add llmquant-data \
            -e LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
            -- npx -y @llmquant/data-mcp
          ```
        </Tab>

        <Tab title="Cursor">
          添加到 `.cursor/mcp.json`（项目级）或 `~/.cursor/mcp.json`（全局）：
          JSON 配置文件通常不会展开 shell 变量，请直接填真实 API key。

          ```json title=".cursor/mcp.json" theme={null}
          {
            "mcpServers": {
              "llmquant-data": {
                "command": "npx",
                "args": ["-y", "@llmquant/data-mcp"],
                "env": {
                  "LLMQUANT_API_KEY": "your_api_key_here"
                }
              }
            }
          }
          ```
        </Tab>

        <Tab title="Codex CLI">
          ```bash theme={null}
          codex mcp add llmquant-data \
            --env LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
            -- npx -y @llmquant/data-mcp
          ```
        </Tab>

        <Tab title="Gemini CLI">
          ```bash theme={null}
          gemini mcp add -s user \
            -e LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
            llmquant-data \
            npx -y @llmquant/data-mcp
          ```
        </Tab>

        <Tab title="Claude Desktop">
          编辑 `claude_desktop_config.json`（macOS：`~/Library/Application Support/Claude/`）：
          JSON 配置文件通常不会展开 shell 变量，请直接填真实 API key。

          ```json title="claude_desktop_config.json" theme={null}
          {
            "mcpServers": {
              "llmquant-data": {
                "command": "npx",
                "args": ["-y", "@llmquant/data-mcp"],
                "env": {
                  "LLMQUANT_API_KEY": "your_api_key_here"
                }
              }
            }
          }
          ```
        </Tab>

        <Tab title="其他 (stdio)">
          任何支持 stdio transport 的 MCP 客户端都接受这份通用配置：
          JSON 配置文件通常不会展开 shell 变量，请直接填真实 API key。

          ```json theme={null}
          {
            "mcpServers": {
              "llmquant-data": {
                "command": "npx",
                "args": ["-y", "@llmquant/data-mcp"],
                "env": {
                  "LLMQUANT_API_KEY": "your_api_key_here"
                }
              }
            }
          }
          ```

          没看到你的客户端？[提个 issue](https://github.com/LLMQuant/data-mcp/issues) 我们补。
        </Tab>
      </Tabs>
    </Accordion>
  </Step>

  <Step title="问 agent 一个它现在该会的问题" icon="sparkles">
    重启客户端。把下面任意一句丢进 chat / agent session —— agent 会自动发现新工具、选对工具、返回结构化结果。

    <Prompt description="Wiki 两步检索">
      在 Quant Wiki 搜一下"动量因子"，把 top hit 完整读出来。
    </Prompt>

    <Prompt description="实时加密行情">
      BTC 现在多少？24 小时涨跌多少？
    </Prompt>

    <Prompt description="研究发现">
      找最近关于 transformer-based factor model 的论文。
    </Prompt>
  </Step>
</Steps>

## 可用工具

每个 tool 是 agent 可调用的一个 MCP 能力。按调用次数计费（credit）。

| Tool                            | 它做什么                                                                        | Credits |
| ------------------------------- | --------------------------------------------------------------------------- | :-----: |
| `wiki_search`                   | 在 50,000+ 篇 Quant Wiki 上做语义检索                                               |    1    |
| `wiki_read`                     | 按 ID 加载完整 markdown 正文                                                       |    0    |
| `paper_search`                  | 在 1,200+ 篇研究论文摘要上做语义检索                                                      |    1    |
| `paper_read`                    | 按章节读取论文（intro / methods / conclusion…）                                      |    0    |
| `crypto_historical_klines`      | 加密货币 OHLCV 蜡烛，可配置周期                                                         |    1    |
| `crypto_snapshot`               | 加密货币交易对当前价 + 24h 行情                                                         |    0    |
| `polymarket_event_browse`       | 列举或精确筛选金融范围内的预测市场事件                                                         |    1    |
| `polymarket_event_search`       | 语义搜索金融范围内的预测市场事件                                                            |    2    |
| `polymarket_event_read`         | 读取一个预测市场事件卡片和它下面的 market 预览                                                 |    0    |
| `polymarket_market_read`        | 读取一个预测市场 market 卡片、outcomes 和 outcome token ids                             |    0    |
| `polymarket_price_history`      | 查询一个 outcome token 的小时或日度隐含概率历史                                             |    0    |
| `equity_historical_prices`      | 美股日线 OHLCV + 分红 / 拆股复权。ETF 价格历史也走这里。                                        |    0    |
| `equity_intraday_prices`        | 美股 `1h` 常规交易时段 OHLCV bar（按交易日窗口筛选；有效窗口最多 14 自然日；省略 `end_date` 时以当前美东日期作为结束） |    1    |
| `etf_lookup`                    | ETF 基本信息 + top holdings 摘要 + 行业 / 国家 / 资产类型分布                               |    0    |
| `etf_holdings`                  | 单只 ETF 完整持仓（来自 SEC 官方监管披露的最近一份快照，按权重降序）。覆盖不到的 ticker 仍返回 `200`，不扣 credit。   |    1    |
| `macro_indicator_search`        | 浏览 50+ 精选宏观指标                                                               |    0    |
| `macro_indicator_history`       | 宏观指标历史观测序列                                                                  |    1    |
| `macro_indicator_snapshot`      | 宏观指标最新一期数值                                                                  |    0    |
| `sec_filing_browse`             | 浏览 SEC 10-K / 10-Q / 8-K 申报文件元信息                                            |    0    |
| `sec_filing_read`               | 读取 SEC 申报文件指定章节                                                             |    1    |
| `sec_13f_list_manager_holdings` | 某机构 13F 持仓（Top 1,000 × 至少最近 4 季度）                                           |    1    |
| `sec_13f_list_ticker_holders`   | 某 ticker 的机构持有人（Top 1,000 × 至少最近 4 季度）                                      |    1    |
| `sec_13f_list_top_managers`     | 按 13F 申报市值排名的 top N smart money                                             |    0    |
| `news_browse`                   | 按 ticker、事件、主题或日期浏览近期公司新闻                                                   |    2    |
| `personal_holdings`             | 读取你在 Dashboard → Profile 保存的持仓（仅限你自己的账号）                                    |    0    |
| `personal_profile`              | 读取你在 Dashboard → Profile 保存的财务背景（仅限你自己的账号）                                  |    0    |

<Tip>
  更多数据产品（包括基本面和财报会议纪要）见 [roadmap](https://github.com/LLMQuant/data-mcp#roadmap)。
</Tip>

## 环境变量

<ParamField type="string">
  你的 LLMQuant Data API key。在 [Dashboard → API Keys](https://llmquantdata.com/dashboard) 生成。
</ParamField>

<ParamField type="string">
  覆盖 API base URL。自托管代理或其他兼容的 LLMQuant Data 部署可使用。
</ParamField>

<ParamField type="number">
  请求超时（毫秒）。最大 `120000`。
</ParamField>

## 下一步

<Columns>
  <Card title="浏览所有数据工具" icon="book-open" href="/zh-CN/api/knowledge/wiki-search">
    每个 tool 都有对应的 endpoint 页面，含 Agent flow 流程图与字段定义。
  </Card>

  <Card title="GitHub 源码" icon="github" href="https://github.com/LLMQuant/data-mcp">
    读源码、提 issue、看 roadmap。
  </Card>
</Columns>


# 简介
Source: https://docs.llmquantdata.com/zh-CN/introduction

面向开发者和 AI Agent 的 AI 原生金融数据平台

# LLMQuant Data API

LLMQuant Data 提供金融数据与量化知识的统一访问接口 —— 专为开发者和 AI Agent 设计。

<CardGroup>
  <Card title="专有知识数据" icon="book-open" href="/zh-CN/api/knowledge/wiki-search">
    50,000+ 篇 Quant Wiki + 1,200+ 篇研究论文摘要 —— 语义检索 + 全文读取。
  </Card>

  <Card title="市场行情" icon="chart-line" href="/zh-CN/market-coverage">
    美股 30+ 年日线 OHLCV、加密货币 K 线与快照、50+ 精选宏观指标。
  </Card>

  <Card title="SEC 与机构持仓" icon="file-invoice" href="/zh-CN/api/filings/13f-top-managers">
    10-K / 10-Q / 8-K 申报文件浏览与读取。Form 13F：Top 1,000 机构管理人 × 至少最近 4 季度。
  </Card>

  <Card title="MCP Server" icon="plug" href="/zh-CN/integration/mcp-server">
    `@llmquant/data-mcp` 一份配置接入 Claude / Cursor / Codex / Gemini CLI —— 全部 tool 一次到位。
  </Card>
</CardGroup>

## 快速开始

<Steps>
  <Step title="获取 API Key" icon="key">
    登录 [控制台](https://llmquantdata.com/dashboard)，在 **API Keys** 页面复制一个 Key，存为环境变量：

    ```bash theme={null}
    export LLMQUANT_API_KEY=your_api_key_here
    ```

    <Tip>
      不要硬编码在源码里。详见 [认证](/zh-CN/authentication)。
    </Tip>
  </Step>

  <Step title="通过 MCP 接入（推荐）" icon="plug">
    原生 MCP 接入 —— 你的 agent 直接调用 26 个数据与个人 context 工具，**不需要任何 glue code**。

    **把下面这段 prompt 丢进 agent —— 它会从 GitHub 读 canonical 配置：**

    ```text theme={null}
    Install the LLMQuant data-mcp server in this environment by following https://github.com/LLMQuant/data-mcp
    ```

    <Accordion title="或者手动安装" icon="terminal">
      <CodeGroup>
        ```bash Claude Code theme={null}
        claude mcp add llmquant-data \
          -e LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
          -- npx -y @llmquant/data-mcp
        ```

        ```bash Codex CLI theme={null}
        codex mcp add llmquant-data \
          --env LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
          -- npx -y @llmquant/data-mcp
        ```

        ```bash Gemini CLI theme={null}
        gemini mcp add -s user \
          -e LLMQUANT_API_KEY=$LLMQUANT_API_KEY \
          llmquant-data \
          npx -y @llmquant/data-mcp
        ```
      </CodeGroup>

      用 Cursor / Claude Desktop / 其他 MCP runtime？看完整 [MCP Server 接入](/zh-CN/integration/mcp-server)。
    </Accordion>
  </Step>

  <Step title="从 agent 试一下" icon="sparkles">
    重启客户端，把下面任意一句丢进 chat：

    <Prompt description="Wiki 研究">
      在 Quant Wiki 搜一下"动量因子"，把 top hit 完整读出来。
    </Prompt>

    <Prompt description="实时行情">
      BTC 现在多少？
    </Prompt>
  </Step>

  <Step title="或直接用 HTTP API" icon="terminal">
    不在 MCP runtime 上？直接打 REST API（base URL: `https://api.llmquantdata.com`）：

    ```python theme={null}
    import os, requests

    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}
    url = "https://api.llmquantdata.com/api/equity/historical?ticker=AAPL&limit=5"
    print(requests.get(url, headers=headers).json())
    ```

    左侧导航有所有 endpoint 的参考文档。
  </Step>
</Steps>


# 市场覆盖
Source: https://docs.llmquantdata.com/zh-CN/market-coverage

LLMQuant Data 当前覆盖的市场、资产、参考数据集一览。

LLMQuant Data 当前提供 **10 个数据产品 universe**，更多在 [roadmap](https://github.com/LLMQuant/data-mcp#roadmap)。每个 universe 都暴露为 MCP tool（详见 [MCP Server](/zh-CN/integration/mcp-server)），同时也有对应的 REST endpoint。

## <Icon icon="book-open" /> 专有知识数据

<Badge icon="circle-check">已上线</Badge>

| 数据集         | 说明              | 数量        |
| ----------- | --------------- | --------- |
| Quant Wiki  | 量化金融概念、公式、因子、策略 | 50,000+ 条 |
| Quant Paper | 学术金融论文精选摘要      | 1,200+ 篇  |

两步检索模式（`*_search` → `*_read`），节省 agent context。

## <Icon icon="chart-line" /> 美股

<Badge icon="circle-check">已上线</Badge>

* **交易所**：NYSE · NASDAQ · AMEX
* **历史数据**：最长 30 年以上日线 OHLCV
* **盘中数据**：`1h` 常规交易时段 bar（短窗口），见 [`equity_intraday_prices`](/zh-CN/api/prices/equity-intraday)
* **标的范围**：10,000+ Ticker（含活跃与已退市）
* **调整**：分红与拆股复权

## <Icon icon="layer-group" /> ETF

<Badge icon="circle-check">已上线</Badge>

* **披露基础**：美国 SEC 官方监管披露的最近一份持仓快照（**不是** issuer 当日底仓，发布有几十天延迟）
* **目前覆盖**：`SPY` · `QQQ` · `VTI` · `SOXX` · `ARKK`（以及陆续扩展的精选热门 ETF）
* **不覆盖的 ticker** 仍返回 `200 OK`，`coverage_status="unsupported"` + 明确说明，**不**静默返回空 —— 当前不覆盖的有 `IBIT` · `DRAM`
* **两个接口**：
  * `etf_lookup` —— ETF 基本信息 + top holdings 摘要 + 行业 / 国家 / 资产类型分布（免费）
  * `etf_holdings` —— 完整持仓列表，按权重降序（1 credit；不覆盖的 ticker 0 credit）
* **价格**：ETF 历史 OHLCV 用 [`equity_historical_prices`](/zh-CN/api/prices/equity-historical) —— ETF 价格走和股票一样的日线接口
* **覆盖状态**：每次响应都带 `coverage_status`（`full` / `partial` / `stale` / `unsupported`）、`as_of_date`、`coverage_notice`，agent 应该先按 `coverage_status` 分支再消费数据

## <Icon icon="bitcoin-sign" /> 加密货币

<Badge icon="circle-check">已上线</Badge>

* **交易对**：500+ 现货交易对（BTC、ETH、SOL、主流 USDT 配对、长尾标的）
* **粒度**：1h / 4h / 1d / 1w K 线 + 最近成交快照

## <Icon icon="gauge-high" /> 预测市场

<Badge icon="circle-check">已上线</Badge>

* **范围**：金融范围内的 event cards 和 market cards
* **工作流**：`polymarket_event_search` / `polymarket_event_browse` → `polymarket_event_read` → `polymarket_market_read` → `polymarket_price_history`
* **历史数据**：按返回的 `outcome_token_id` 查询小时或日度隐含概率历史
* **文档**：见 [预测市场事件](/zh-CN/api/prediction-markets/events)

## <Icon icon="landmark" /> 宏观指标

<Badge icon="circle-check">已上线</Badge>

* **覆盖范围**：支持目录内的美国宏观指标
* **范围**：50+ 指标，覆盖 8 个类别 —— 经济活动、就业、通胀、利率、货币、对外、市场、情绪
* **示例 series**：`CPIAUCSL` · `UNRATE` · `FEDFUNDS` · `GDPC1` · `DGS10`
* **频率**：日 · 周 · 月 · 季（视 series 而定）
* **修订**：返回最新发布的 vintage；如果数据已修订，agent 看到的可能是修订值，而不是首次发布值

## <Icon icon="file-invoice" /> SEC 申报文件（10-K / 10-Q / 8-K）

<Badge icon="circle-check">已上线</Badge>

* **申报系统**：SEC EDGAR
* **表单类型**：10-K（年报）、10-Q（季报）、8-K（重大事件报告）
* **范围**：全部美股公开发行人
* **工作流**：`sec_filing_browse`（元信息，免费）→ `sec_filing_read`（具体 item / 章节）

## <Icon icon="users" /> SEC Form 13F（机构持仓）

<Badge icon="circle-check">已上线</Badge>

* **范围**：每季各自的 Top 1,000 机构管理人（每个季度有各自的 Top 1,000）× 至少最近 4 季度（实际覆盖的季度见 response `meta.notice`）
* **三个视角**：
  * `sec_13f_list_top_managers` —— 按 13F 申报市值排名
  * `sec_13f_list_manager_holdings` —— 某机构持仓什么？
  * `sec_13f_list_ticker_holders` —— 谁在持仓某 ticker？
* **典型用途**：consensus / overlap 榜、smart money 动量、regime tagging

## <Icon icon="gauge-high" /> Prediction Markets

<Badge icon="circle-check">已上线</Badge>

* **覆盖范围**：金融范围内的预测市场 event 与 market 卡片
* **工作流**：`polymarket_event_search` 适合自然语言发现，`polymarket_event_browse` 适合列表或精确筛选，然后继续调用 `polymarket_event_read` / `polymarket_market_read` / `polymarket_price_history`
* **典型用途**：概率跟踪、事件风险简报、市场隐含情景检查

## <Icon icon="newspaper" /> 公司新闻

<Badge icon="circle-check">已上线</Badge>

* **覆盖范围**：自 2026 年 4 月 11 日起持续更新的公司新闻
* **工作流**：先用 `news_browse` 查看近期新闻，再按 ticker、事件、主题或日期缩小范围
* **典型用途**：公司动态跟踪、财报复盘和事件驱动研究

## <Icon icon="file-invoice-dollar" /> 财务报表

<Badge icon="clock">即将推出</Badge>

跨美股公开发行人的标准化财务科目，将包含：

* 利润表、资产负债表、现金流量表
* 年报（10-K）+ 季报（10-Q）
* 滚动十二个月汇总（TTM）

## <Icon icon="compass" /> Roadmap

<Badge>规划中</Badge>

财报会议纪要 · 公司基本面。最新进度在 [data-mcp roadmap](https://github.com/LLMQuant/data-mcp#roadmap)。