# CNEquity: a local Parquet data lake for China A-share research

> CNEquity is a Python project that pulls Chinese market data from many public sources into a local Parquet lake, with row-level provenance, point-in-time query options and read-only MCP access. It targets individual researchers and AI agents who want their own copy of the data rather than a hosted API.

**rootSunc/CNEquity** — 中国 A 股数据基础设施。55个日更数据集：股票行情、基本面、期货数据、资金面、公告事件、指数行业、宏观与风险。行级溯源、PIT 语义、复权与历史成分内置，MCP 原生。自托管，零注册、零 API Token

- Repository: https://github.com/rootSunc/CNEquity
- Website: https://rootsunc.github.io/CNEquity/
- Stars: 838 · Forks: 95
- Language: Python
- License: Apache-2.0
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/rootsunc-cnequity

## Why a local lake for China market data instead of an API

CNEquity answers a problem that shows up as soon as you start doing repeated research on Chinese equities. Market prices, financial statements, index constituents, fund flows and corporate events come from separate public endpoints, each with its own shape, its own coverage limits and its own failure modes. Re-fetching that for every backtest is slow, and keeping the raw responses around is messy. CNEquity collects the sources into local Parquet files, one dataset per table, and layers incremental collection, resume after failure and quality auditing on top. The stated audience is individual researchers and AI agents that need a durable local dataset. Nothing here asks for an account or an API token, and the package runs on macOS, Linux and Windows with Python 3.10 or newer. The CLI and the console are bilingual, defaulting to the system language, with CNE_LANG=zh_CN forcing Chinese output.

## Fifty-five datasets spread across ten research layers

The registry is the heart of the project, and its size is the point. The current development tree registers 55 datasets, split into 47 curated and 8 derived ones, grouped into layers L0 to L9. L0 holds reference data such as the security master, the trading calendar and trading status. L1 is market data: daily bars, index bars, adjustment factors and, when enabled, minute bars and tick data. L2 covers corporate events, L3 fundamentals and consensus estimates, L4 fund flows such as northbound holdings, margin trading and block trades, L5 index and industry structure, L6 macro indicators and market breadth, L7 news, sentiment and sector rotation, L8 risk items like unlock schedules and regulatory events, and L9 derivatives including futures contracts, options and Greeks. Every dataset registers a primary source and often a backup, with providers such as tdx_protocol, eastmoney, sina, baostock, cninfo, ths, exchange, futures_exchange and pboc appearing across the table. Minute bars, tick data and the futures and options sets are off by default and must be enabled deliberately.

## Installing the package and running the demo profile

The shortest path to a working lake is one install and two commands. Installation is a standard pip install of the package published on PyPI as cnequity:

```bash
pip install cnequity
```

The demo profile pulls five stocks over roughly the last 30 trading days into a separate directory, so it does not interfere with a later production lake. It is described as taking about a minute, and it prints the market table, a query example and the command needed to connect an AI client when it finishes. The next command starts the console, and the browser console is where the lake status, coverage heat map, daily detail view and quality audit are shown:

The demo profile is then built with `cne init --profile demo`, and the console is served with the demo configuration file, which is the fastest way to see what the collector actually captured rather than inferring it from log output. The full production path starts with `cne init`, which can take hours on the first run, and `cne check`, which reports whether the collected data is complete and usable.

## Building a real lake with cne init and resuming after a break

The full lake covers the Shanghai, Shenzhen and Beijing markets for roughly the last three years. The documentation is explicit that the first run can take hours, and that a second run resumes where the first stopped: already downloaded parts are not fetched again. A network pre-check runs in the seconds before the job starts, and errors in non-critical steps such as corporate actions do not abort the build. When the run ends it lists the steps that did not finish, which is the piece of information you need in order to decide whether the lake is usable. After the build, cne check verifies completeness and usability. From Python the data is read back through the query helper, which returns a frame you can inspect directly:

```python
from cnequity.query import load
bars = load("daily_bars", symbols=["600519.SH"])
print(bars.tail())
```

Keeping the lake current afterwards means running the daily update once a day, which the documentation gives as cne run daily.

## Row-level source, data_version and fetched_at on every row

Results are meant to be checkable, and the mechanism for that is written into the rows themselves. Each row carries source, data_version and fetched_at, and the project pairs those with immutable data versions and research snapshots so a past result can be reproduced. Two design decisions follow from this. Raw prices and adjustment factors are stored separately, so a price series is never silently rewritten, and the query layer exposes an adjust="hfq" option together with a strict_adj flag for studies that need adjusted history, which the documentation shows as adjust="hfq" with strict_adj=True. Second, financial statement queries distinguish strict point-in-time data from after-the-fact rebuilds. A query that uses an explicit as_of value with pit_mode="strict" returns only what was visible at that date, and the project warns that a newly backfilled figure does not mean the information was available then. Twenty-two source probe routes exist to diagnose reachability, and endpoints with high collection cost have to be chosen explicitly rather than run by default.

## Survivorship bias handled in the data layer, not in the strategy

The documentation singles out one failure mode as serious enough to warrant a section of its own. A backtest that selects stocks from today's still-trading list and looks back over the same window silently drops every company that later delisted, which biases the result upward. The project illustrates the difference with a historical sample that compares an equal-weight buy-and-hold over a universe including delisted stocks against one that keeps only survivors, and it states plainly that the returns and counts in that chart do not represent the current lake coverage or future performance. The engineering response is that delisting identity is retained in the data layer, with delisting_events registered as a dataset, and that adjustment factors, historical constituents and point-in-time semantics are part of the query contract rather than something each downstream script has to remember. Universe history still needs checking: past ST status, delisting records and price coverage have to be verified for the period you care about.

## Read-only MCP access and a container that ships sample data

The same lake can be handed to an AI client through MCP, in read-only mode, which is the feature that sets CNEquity apart from a simple downloader. Clients such as Claude, ChatGPT, Codex, Gemini CLI, Cursor and VS Code are listed as targets, and the registration for Claude Code looks like this:

```bash
claude mcp add cnequity -- cne mcp --config /abs/path/to/configs/cnequity.demo.toml
```

The config path has to be absolute. ChatGPT only accepts a public URL, so the server can be exposed with cne mcp --http --token behind a tunnel. The container image takes the same idea further for evaluation: it installs the package, builds a sample lake at build time and starts the MCP server over stdio.

```dockerfile
FROM python:3.12-slim
RUN pip install cnequity \
    && cne init --profile sample --data-root /opt/cnequity/sample \
        --config-out /opt/cnequity/sample.toml
ENTRYPOINT ["cne"]
CMD ["mcp", "--config", "/opt/cnequity/sample.toml"]
```

That sample lake is synthetic, with rows marked source=mock, and the file comments state plainly that it exists so the server starts and lists its tools without network access, not for research. For real data the image expects your own lake and config to be mounted, with the server started against your config file rather than the sample one.

Parquet files stay open format and can be read with Python, DuckDB, Polars, the console or MCP.

## Apache-2.0, alpha status, and releases every few days

The package metadata describes the project as an open, self-hosted financial data infrastructure for China markets, starting with A-shares, licensed under Apache-2.0 with the LICENSE and NOTICE files shipped alongside it. The classifier marks the release as Development Status :: 3 - Alpha, which is the honest way to read the versioning. The version in the build metadata is 0.18.0, matching the v0.18.0 tag published on 2026-10-18, with v0.17.1 and v0.17.0 both published on 2026-10-17. The last push was on 2026-10-18. Releases are frequent and version numbers move quickly, so pinning a version matters for anything you run on a schedule. The CHANGELOG.md file, the dataset catalog under docs and the source notes under docs are where change details live, and the documentation set is served as a site with Chinese and English variants. Costs of adoption are mostly operational rather than financial: collection time on the first full run, disk space for Parquet files, and the need to keep source endpoints reachable.

## Conclusion

CNEquity fits a researcher or agent builder who needs a private, versioned copy of Chinese market data, who is comfortable running a long collection job and reading Parquet through Python, DuckDB or Polars, and who needs survivorship-aware universes and point-in-time financial data. It does not fit someone who wants a five minute setup, a hosted endpoint, or minute bars and futures data turned on by default. Before committing, run cne init --profile demo to see the collection path, then confirm that cne check passes on your own machine, that the source endpoints you rely on are reachable through the 22 registered probes, and that the datasets you need are enabled before you assume their history exists.

## FAQ

### Does CNEquity require an account or an API token?

No. The project states that installation needs Python 3.10 or newer on macOS, Linux or Windows, with no account and no token, and the sources are public market data endpoints. The one exception is the HTTP transport for MCP, which is started with cne mcp --http --token when a client such as ChatGPT needs a public URL.

### How do I connect CNEquity to an AI client such as Claude Code?

Register the MCP server with claude mcp add cnequity -- cne mcp --config /abs/path/to/configs/cnequity.demo.toml, using an absolute config path. The lake is exposed read-only, and each client has its own configuration syntax documented in the MCP guide.

### Which datasets are available and how are they organised?

The development tree registers 55 datasets, 47 curated and 8 derived, grouped into layers L0 to L9 covering reference data, market data, corporate events, fundamentals, fund flows, index and industry structure, macro data, news and sentiment, risk items, and derivatives. Minute bars, tick data and futures and options sets are disabled by default and must be enabled on purpose.

### What happens if a full lake build is interrupted?

Running the init command again resumes from where it stopped, and already downloaded parts are not fetched a second time. Non-critical step failures do not abort the build, and the run lists the steps that did not complete, after which cne check verifies whether the data is complete and usable.

## Sources

- [License: Apache-2.0](https://github.com/rootSunc/CNEquity/blob/main/LICENSE)
- [Project website](https://rootsunc.github.io/CNEquity/)
- [README](https://github.com/rootSunc/CNEquity/blob/main/README.md)
- [Releases](https://github.com/rootSunc/CNEquity/releases)
- [rootSunc/CNEquity on GitHub](https://github.com/rootSunc/CNEquity)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rootsunc-cnequity