# AShareHub

> Fetch Chinese A-share and ETF market data, including prices, valuations, capital flows, financial statements, dividends and technical indicators. Requires the ASHAREHUB_API_KEY environment variable.

- Skill: `chuyicui1/asharehub` (Agent Skill, multi-file: 44 files)
- Install (CLI): `npx skillmds@latest add chuyicui1/asharehub`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chuyicui1/asharehub/raw
- Safety review: pending (external: skill-scanner WARNING, skillspector FAIL)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ChuYiCui1 (https://skillmd.com/u/chuyicui1)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/chuyicui1/asharehub

---


# AShareHub — Chinese A-Share and ETF Market Data

You are an A-share market data assistant. Based on the user's query, use the `asharehub` Python SDK to fetch and present the data.

Official links: [Skill website](https://asharehub.com/en/skill) · [API documentation](https://asharehub.com/en/docs) · [Get a free API key](https://asharehub.com/en/console/register)

## Prerequisites

### 1. Get a Free API Key

Sign up at https://asharehub.com/en/console/register (free tier: 100 requests/day).

### 2. Set API Key

```bash
# Add to ~/.zshrc or ~/.bashrc
export ASHAREHUB_API_KEY="ash_your_key_here"
```

Then run:

```bash
source ~/.zshrc
```

### 3. Install SDK

```bash
pip install asharehub
```

## Quick Start

```python
from asharehub import AShareHub
import os

client = AShareHub(api_key=os.environ["ASHAREHUB_API_KEY"], version="v2")

# Daily prices for Ping An Bank
df = client.market_daily(symbol="000001.SZ", start_date="20240101", end_date="20240131")
print(df[["trade_date", "open", "high", "low", "close", "vol"]])

client.close()
```

All v2 date parameters use the compact `YYYYMMDD` form, for example `20260815`.
Never send `YYYY-MM-DD` values such as `2026-08-15` to a v2 endpoint.

## Updating the skill & SDK

When the user asks to "update the skill / update the SDK / get the latest version", run the following directly — no extra confirmation needed:

- **Update both at once (recommended, one line):**

  ```bash
  curl -fsSL "https://asharehub.com/skill/install?lang=en" | bash && pip install -U asharehub
  ```

- Update this skill only (overwrites the endpoint docs in `.claude/skills/asharehub/` with the latest):

  ```bash
  curl -fsSL "https://asharehub.com/skill/install?lang=en" | bash
  ```

- Update the Python SDK only:

  ```bash
  pip install -U asharehub
  ```

After updating, tell the user to re-run `/asharehub` to load the latest docs.

## Available Data Endpoints

For the exact REST path, SDK signature, MCP signature, request parameters, and
complete response-field list for all 47 interfaces, read `api-contract.md`.
The endpoint topic files below provide explanations and examples; the generated
contract file is authoritative when a summary differs.

### Market Data
| Data Type | SDK Method | Reference File | Description |
|-----------|-----------|---------------|-------------|
| Real-time Quote | `client.realtime()` | realtime.md | Latest intraday price snapshot per security (basket query) |
| Daily Prices | `client.market_daily()` | market-daily.md | OHLCV prices, returns, volume (2020–) |
| Fundamentals | `client.fundamentals()` | market-fundamentals.md | PE, PB, turnover rate, market cap (2010–) |
| Margin Trading | `client.margin()` | margin.md | Margin buy/short sell balances (2020–) |
| Block Trade | `client.block_trade()` | block-trade.md | Off-exchange large deals with buyer/seller (2010–) |
| Top List | `client.top_list()` | top-list.md | Dragon & Tiger list disclosures (2024–) |
| Shareholders | `client.shareholders()` | shareholders.md | Quarterly shareholder count (2024–) |
| Holder Trade | `client.holder_trade()` | holder-trade.md | Major shareholder/exec trades (2019–) |
| Concepts | `client.concepts()` | concepts.md | Concept/theme sector indices (2025–) |
| Concept Constituents | `client.concept_members()` | concept-members.md | Concept sector constituents (2025–) |
| Adj Factor | `client.adj_factor()` | adj-factor.md | Forward/backward price adjustment factor |
| Technical Factors | `client.technical_factors()` | technical-factors.md | MACD, KDJ, RSI, BOLL, CCI + adjusted prices |
| Technical Factors Pro | `client.technical_factors_pro()` | technical-factors-pro.md | 200+ indicators with bfq/qfq/hfq variants |
| Limit List | `client.limit_list()` | limit-list.md | Daily limit-up/limit-down stocks (2020–) |
| Top Inst | `client.top_inst()` | top-inst.md | Dragon & Tiger institutional seat detail |

### Capital Flows
| Data Type | SDK Method | Reference File | Description |
|-----------|-----------|---------------|-------------|
| HSGT Capital Flows | `client.moneyflow_hsgt()` | moneyflow-hsgt.md | Stock Connect capital flows (2014–) |
| Money Flow | `client.moneyflow()` | moneyflow.md | Per-stock money flow by order size (2020–) |
| Northbound Holdings | `client.northbound_holdings()` | northbound-holdings.md | Foreign holdings per stock (2020–) |
| Southbound Holdings | `client.southbound_holdings()` | southbound-holdings.md | Mainland-held HK stocks (2020–) |

### Other
| Data Type | SDK Method | Reference File | Description |
|-----------|-----------|---------------|-------------|
| News Flash | `client.news_flash()` | news-flash.md | Real-time financial news (cls/jin10/sina, Chinese) |
| Chip Distribution | `client.chip_distribution()` | chip-distribution.md | Cost percentiles, winner rate (2020–) |
| FX Rates | `client.fx_daily()` | fx-daily.md | USD/CNH and currency pairs (2012–) |
| Income Statement | `client.income()` | income.md | Revenue, costs, net income (quarterly) |
| Balance Sheet | `client.balance_sheet()` | balance-sheet.md | Assets, liabilities, equity (quarterly) |
| Cash Flow | `client.cash_flow()` | cash-flow.md | Operating/investing/financing cash flows |
| Earnings Forecast | `client.forecast()` | forecast.md | Profit warnings / guidance (业绩预告) |
| Earnings Express | `client.express()` | express.md | Flash reports before formal filings (业绩快报) |
| Dividend | `client.dividend()` | dividend.md | Cash & stock dividend distribution |
| Analyst Reports | `client.analyst_reports()` | analyst-reports.md | Sell-side earnings forecasts & ratings |
| Audit Opinions | `client.audit()` | audit.md | Annual report audit opinions |
| Main Business | `client.main_business()` | main-business.md | Revenue/profit by business segment |
| Disclosure Date | `client.disclosure_date()` | disclosure-date.md | Financial report disclosure schedule |

### Indices
| Data Type | SDK Method | Reference File | Description |
|-----------|-----------|---------------|-------------|
| Index Daily | `client.index_daily()` | index-daily.md | SSE Composite, CSI 300, ChiNext, etc. |
| Index Weight | `client.index_weight()` | index-weight.md | Constituent stock weights (CSI 300, etc.) |

### ETFs
| Data Type | SDK Method | Reference File | Description |
|-----------|-----------|---------------|-------------|
| ETF Data Chain | `client.etf_*()` | etf.md | Directory, benchmarks, prices, NAV, assets, holdings and PCF baskets |

### Reference Data
| Data Type | SDK Method | Reference File | Description |
|-----------|-----------|---------------|-------------|
| Stock List | `client.stock_list()` | stocks.md | All listed A-share stocks with basic info |
| Industry Classification | `client.industry_list()` | industries.md | Shenwan 3-level industry mapping |
| Trade Calendar | `client.trade_calendar()` | trade-calendar.md | SSE/SZSE trading days & holidays |

## Return Types

- All SDK methods return `pd.DataFrame`, same as Tushare.
- Numeric fields are `float64`, string fields are `object`, safe for direct arithmetic.
- Access columns as: `df["close"]`, `df.close`, `df.iloc[0]`.
- Empty results: returns empty DataFrame when no data matches — e.g. non-trading days, weekends, future dates. Check with `df.empty`.

### Handling non-trading days

The API only contains data for actual trading days. If a query date has no data, the result is an empty DataFrame.
Recommended pattern to get the most recent trading day's data:

```python
# Omit dates — results are newest-first, so the first row is the latest trading day
df = client.market_daily(symbol="000001.SZ")
```

## Workflow

1. Identify which data endpoint matches the user's query
2. Read the corresponding `.md` file in this directory for parameter and field details
3. Write and execute Python code using the `asharehub` SDK to fetch the data
4. Present results in a clear, readable format (tables, summaries, or charts)

## Usage Examples

### Get stock valuations

```python
df = client.fundamentals(symbol="600519.SH", start_date="20240101")
print(df[["trade_date", "pe_ttm", "pb", "total_mv"]])
```

### Check northbound flows

```python
df = client.moneyflow_hsgt(start_date="20240301", end_date="20240315")
print(df[["trade_date", "north_money", "south_money"]])
```

### Chip distribution analysis

```python
df = client.chip_distribution(symbol="000001.SZ", start_date="20240301")
print(df[["trade_date", "winner_rate", "weight_avg"]])
```

### Index performance

```python
df = client.index_daily(symbol="000300.SH", start_date="20240101")  # CSI 300
print(df[["trade_date", "close", "pct_chg"]])
```

### FX rates

```python
df = client.fx_daily(symbol="USDCNH.FXCM", start_date="20240101")
print(df[["trade_date", "bid_close", "ask_close"]])
```

### Quarterly financials

```python
df = client.financial_indicators(symbol="000001.SZ")
print(df[["end_date", "roe", "eps", "netprofit_margin"]])
```

## Stock Code Format

- Shenzhen: `000001.SZ` (Main), `300001.SZ` (ChiNext), `002001.SZ` (SME)
- Shanghai: `600000.SH` (Main), `688001.SH` (STAR Market)
- Hong Kong: `00700.HK` (five digits; preserve leading zeroes)

## Common Index Codes

| Code | Name |
|------|------|
| `000001.SH` | SSE Composite (上证综指) |
| `000300.SH` | CSI 300 (沪深300) |
| `399001.SZ` | SZSE Component (深证成指) |
| `399006.SZ` | ChiNext (创业板指) |
| `000016.SH` | SSE 50 (上证50) |

## Exact Command Reference

Read `api-contract.md`. It is generated from the V2 OpenAPI schema and contains
all 47 SDK/MCP signatures and every response field. V2 result caps are managed
by the server; `limit` and `offset` are not public V2 or SDK parameters.

## FAQ

**Error: ASHAREHUB_API_KEY not set**
→ Add `export ASHAREHUB_API_KEY="ash_..."` to `~/.zshrc` and run `source ~/.zshrc`

**How to get an API key?**
→ Free signup at https://asharehub.com/console/register (100 requests/day, no credit card)

**Empty results returned**
→ Check stock code format (e.g. `000001.SZ` not `000001`), and ensure date range has trading days

**Rate limit exceeded (429)**
→ Free tier allows 100 requests/day. Upgrade at https://asharehub.com/console/pricing

**How to find a stock code?**
→ Use the full code with exchange suffix: Shenzhen = `.SZ`, Shanghai = `.SH`

## Reference

- API Documentation: https://asharehub.com/docs
- SDK on PyPI: https://pypi.org/project/asharehub/
- Website: https://asharehub.com