thsdk-stock

name	thsdk-stock
description	Fetch stock market data via thsdk: realtime quotes, intraday data, historical K-lines for A-shares, HK/US stocks, futures, forex.

thsdk Stock Skill

Use this skill when a task requires fetching market data with thsdk. The current thsdk PyPI package exposes THS, not Tdx.

Activation Keywords

• thsdk
• 通达信
• 股票数据
• 实时行情
• 历史K线

Tools Used

• exec
• read
• write

Installation

Prefer a project-local virtual environment:

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install thsdk

If pip is blocked by the system Python, do not force-install globally. Use the virtualenv.

When to use which script

• Realtime order-book style quote or intraday snapshot: scripts/fetch_realtime.py
• Historical K-line bars: scripts/fetch_history.py
• Offline validation in restricted environments: scripts/test_thsdk.py
• Runnable examples: examples/example_usage.py

Usage Patterns

1. Fetch realtime data

.venv/bin/python scripts/fetch_realtime.py --code SZ300033 --mode depth --pretty

If the environment cannot import thsdk, validate with mock data:

python3 scripts/fetch_realtime.py --code SZ300033 --mock --pretty

2. Fetch intraday timeline

.venv/bin/python scripts/fetch_realtime.py --code SZ300033 --mode intraday --pretty

3. Fetch historical K-line data

.venv/bin/python scripts/fetch_history.py \
  --code SZ300033 \
  --interval day \
  --count 30 \
  --adjust forward \
  --pretty

4. Fetch a bounded time range

.venv/bin/python scripts/fetch_history.py \
  --code SZ300033 \
  --interval 60m \
  --start 2026-03-01 \
  --end 2026-03-18T15:00:00 \
  --pretty

5. Run the offline test suite

python3 scripts/test_thsdk.py

Instructions for Agents

1. Confirm whether the user wants realtime data or historical K-line data.
2. Prefer a local virtualenv and install thsdk there. Do not modify the system Python.
3. Use THS() as the client entrypoint. If login credentials exist, inject them:

export THS_USERNAME=your_username
export THS_PASSWORD=your_password
export THS_MAC=your_mac

4. For historical K-line queries, use ths.klines(...).
5. For realtime data, prefer:
   • ths.depth(...) for 5-level order book
   • ths.intraday_data(...) for minute timeline
6. Treat SDK responses as success/error/data/extra objects.
7. Normalize output to plain JSON-serializable dictionaries before returning.
8. If runtime cannot import thsdk, suggest --mock for local validation only.
9. For code lookup, use ths.search_symbols(...) then feed THSCODE into queries.

Examples

Example 1: Fetch realtime depth data

from thsdk import THS

with THS() as ths:
    response = ths.depth("SZ300033")
    if response.success:
        print(response.data)

Example 2: Fetch historical K-lines

from thsdk import THS

with THS() as ths:
    response = ths.klines(
        "SZ300033",
        interval="day",
        count=30,
        adjust="forward"
    )
    if response.success:
        for bar in response.data:
            print(f"{bar['时间']}: {bar['收盘价']}")

Example 3: Search for a stock code

from thsdk import THS

with THS() as ths:
    response = ths.search_symbols("同花顺")
    if response.success:
        for item in response.data:
            print(f"{item['THSCODE']}: {item['名称']}")

Notes

• thsdk on PyPI requires Python 3.9+.
• Guest accounts may exist but can be limited in permission or latency.
• In restricted environments without network access, use --mock for testing.