hithink finance

This is the unified Agent entry and main router for "Hithink Finance Data Service". It is responsible for identifying requirements, detecting current capabilities, handling configuration boundaries and selecting access methods; after selecting a method, it only reads the corresponding primary entry, which then discloses detailed contracts on demand.

Directly Describe Requirements

Users are allowed to start with natural language, no need to understand commands, interfaces,

thscode

or adjustment parameters first. For example:

"Check today's price of Kweichow Moutai."
"Compare the trends of Moutai and Ping An Bank in the past year."
"Check the current constituent stocks of CSI 300."
"See which stocks hit the daily limit today."
"Export the historical market data of the entire market to a file."
"Check if my local market database needs to be updated."

First convert natural language into clear data tasks, then select the access method according to the current environment. Do not pass command selection, code suffixes or parameter enumeration to users.

Task and Capability Routing

User Intent	Task Category	Processing Focus
Confirmation of stock name, abbreviation, code or asset category	Target Disambiguation	Retrieve data after converting to unique `thscode`
Latest price, historical market, corporate actions, price adjustment	Market Data	Clarify time window and adjustment caliber
Income statement, balance sheet, cash flow, financial indicators	Financial Data	Clarify reporting period and frequency
P/E ratio, P/B ratio, P/S ratio, P/CF ratio	Valuation Data	Batch query latest snapshots, retain null and negative values
Indices, concept sectors, industry sectors, constituent stocks	Indices & Sectors	Distinguish between stocks, standard indices and `.TI` sectors
Fund information, net value, returns, holdings, holders, ETF/LOF market data	Public Funds	First distinguish between `fund-otc/fund-etf/fund-lof/fund-reits` and capability boundaries
Daily limit, consecutive limits, abnormal movements, hot lists, dragon and tiger lists	Featured Data	First confirm if it is a today-only capability
Full-market data, local database, SQL, synchronization, export	Data Management	Check data freshness and store large results in files

Routing Process

Identify the task category from the user's original expression, clarify data, asset category, time range, freshness, adjustment caliber, result scale and output format; only make a brief confirmation when missing information will significantly change the result.
Process user inputs such as names, codes and calibers, do not require users to provide technical parameters first.
Only perform side-effect-free current environment detection, do not require users to reinstall repeatedly:
- Whether unified credentials are configured: first check
```
HITHINK_FINANCE_API_KEY
```
  , then check user-level
```
credentials.env
```
  , only report the source and existence status, do not display the value.
- Whether the current session is connected to
```
hithink-finance-a-share
```
  ,
```
hithink-finance-a-share-index
```
  or
```
hithink-finance-meta
```
  MCP.
- Whether
```
hithink-finance
```
  exists in PATH; if exists, read
```
hithink-finance --version
```
  , do not upgrade first.
- Whether the user is working on a Python/Notebook project, has
```
marketdb
```
  , or explicitly requires Python.
- Whether only HTTP/curl environment is available, or the user explicitly requires self-integration.
Select one main path according to tasks and capability boundaries; do not install or detect all tools simultaneously for "completeness".
Only read one corresponding primary reference in the table below, then route to its subdirectory contracts via this entry.
After execution, report data source, time range, caliber, number of rows, output path and online verification boundaries.

Access Method Decision

Scenario	Preferred Method	Primary Entry
Human terminal, Agent execution, automation, integrated remote and local data	CLI	cli.md
Chat/IDE session has connected managed services	MCP	mcp.md
Zero-dependency HTTP, custom scripts, server-side integration	REST API	api.md
Python, Notebook, research workflow or existing marketdb	Python SDK	python-sdk.md

CLI is highly encapsulated with remote data retrieval, local DuckDB, structured output and large result file storage, friendly to both humans and Agents. MCP is most suitable for Chat scenarios. REST API has the highest plasticity. Python SDK is suitable for secondary development and research.

Unified API Key

All remote methods share the API Key obtained from https://fuyao.aicubes.cn/admin.

Unified credentials do not require CLI installation. Each time the Skill is triggered, check in the following order, reuse directly once found, no longer prompt the user for configuration:

Key temporarily provided via secure input during current operation.
```
HITHINK_FINANCE_API_KEY
```
.

User-level

credentials.env

: Windows

%APPDATA%\hithink-finance\credentials.env

, macOS

~/Library/Application Support/hithink-finance/credentials.env

, Linux

${XDG_CONFIG_HOME:-~/.config}/hithink-finance/credentials.env

Compatible with old sources:
```
FUYAO_TOKEN
```
,
```
API_KEY
```
or existing CLI system credentials; old names are no longer used for new configurations.

When all are missing, provide the global environment variable guidance from CLI Installation and Configuration Entry according to the current platform, and use the following instructions:

Please first go to https://fuyao.aicubes.cn/admin to register and obtain the unified API Key. After obtaining it, you can configure the global environment variable for the current user according to the commands below; you can also send it directly to me and I will complete the configuration for you. API Key is sensitive credentials, and chat platforms may retain message records, so it is more recommended to use hidden input or environment variable methods.

Do not require users to send the Key to the conversation; accept and complete configuration when users actively provide it, do not repeat the Key.
Do not write the Key into command parameters, code, Prompt products, logs, public configurations, outputs, project files or Git; Agents use stdin, current process environment, client Secret or restricted user credential files.
When the current Agent environment cannot avoid the Key appearing in tool parameters or logs, return to the platform's hidden input command and explain the restrictions, do not pretend the configuration is successful.
MCP uses client Secret or
```
HITHINK_FINANCE_API_KEY
```
interpolation; REST/Python reads unified credential sources.
Only re-guide when missing or confirmed invalid; do not request the Key again when switching access methods.

CLI Recommendation and Linkage

Do not install CLI when users explicitly select MCP, REST or Python.
When users directly propose financial tasks, do not specify access methods and CLI does not exist, briefly inform that the official CLI will be installed and continue; follow the authorization mechanism when the platform requires authorization. If installation fails, fall back to existing MCP, REST or Python paths.
When CLI is just installed, unified credentials are just configured or updated, or CLI authentication fails but unified credentials are valid, log in securely via
```
--api-key-stdin
```
according to CLI setup; use
```
--replace
```
when existing CLI credentials need to be synchronized, do not logout first.
CLI system credentials are secure copies of unified credentials, enabling CLI to run independently; do not rewrite system credentials for ordinary calls.
After confirming to use CLI, first locate the current Agent's Skills directory and verify that it contains 10 CLI supporting Skills (each directory must contain
```
SKILL.md
```
).
```
hithink-finance skills status --format json
```
only provides the package's
```
canonical
```
source, which cannot prove that the current Agent has discovered or loaded these Skills.
When the current Agent lacks supporting Skills, first run
```
hithink-finance skills sync --format json
```
and recheck the same directory. This command may not recognize all Agent tools; if still missing and the current Agent's writable Skills directory is known, the Agent must actively copy the missing complete Skill directories from
```
canonical
```
, then recheck and restart the session for rediscovery if needed. Only copy the official missing directories, do not overwrite unrelated Skills, do not copy package sources to project directories or unknown Agent directories; report this blocking item only when the path is unknown or there is no write permission.
Remote full download, import and adjustment reconstruction of
```
data init
```
are long tasks, must be executed in a foreground manner that can wait for all child processes, and set the execution host timeout to no less than 15 minutes. Only when the exit code is 0 and the structured envelope
```
ok=true
```
can the next command for the same database start; timeout or non-0 exit does not mean completion. First check if there is still a living PID holding the DB; if exists, wait for it to exit, do not continue executing on the DB, and do not delete locks still held by living PIDs. Only when the user explicitly requests to abort, explain the impact first and then terminate the corresponding process.
Installation, upgrade, uninstallation and data cleaning still belong to environment changes. When users directly request financial tasks and do not select other access methods, the aforementioned "inform then install and continue" constitutes authorization for this CLI installation; other environment changes still require explicit authorization.

General Execution Contracts

Do not require users to provide complete
```
thscode
```
first. When users provide names, abbreviations, incomplete codes or uncertain asset categories, first search and disambiguate to unique
```
thscode
```
; only ask users to confirm when multiple credible candidates will change the result, do not guess
```
.SH
```
,
```
.SZ
```
,
```
.BJ
```
or index types.
When showing
```
thscode
```
to users for the first time, explain in one sentence that it is a unique security code with exchange or index suffix; do not repeat the explanation later.
No need to ask about adjustment for latest snapshots, financial reports and index tasks. When no adjustment is specified for A-share historical market data, use the default value declared in the current contract of the selected access method (currently
```
forward
```
, i.e., forward adjustment) and clearly indicate it in the result; use
```
none
```
when users require original transaction prices. When the caliber will significantly affect the conclusion and the user's intent is still unclear, briefly explain "forward adjustment maintains current prices, backward adjustment maintains starting prices, none retains original prices", then confirm once.
Latest market data, financial reports, valuations, indices and featured data are retrieved remotely; locally available and sufficiently up-to-date historical OHLCV, adjustment, panel and SQL data are prioritized from the local database.
Success condition for REST/MCP is business envelope
```
code=0
```
; success condition for CLI is exit code 0 and JSON structured envelope
```
ok=true
```
.
Results of full-market, pagination full set, long time window or multiple targets must be stored in files, only report path, number of rows, window and summary.
Report the reason when real data is unavailable; do not use similar data, static examples or simulated data as substitutes.
Mark data source, time, reporting period, adjustment caliber and "Not Investment Advice" on analysis results.
Offline contracts can only prove the scope of support, cannot prove that the current session is connected or the account has permissions; online availability must be verified through actual authorization requests.

Failure Output Contracts

When failing, report to users in fixed order: failure stage, original error summary, whether to retry and reason, unique next action, unfinished verification. Do not only return error codes or generalize as "service unavailable".

Missing or invalid authentication: first recheck unified credential sources; provide initial guidance once when missing, only require updating the same unified source when invalid, do not repeatedly request according to access methods.
Unsupported parameters, targets or capabilities: correct determinable inputs; ask users to confirm only when multiple valid semantics exist, do not retry blindly.
Network errors,
```
4001
```
or
```
5xxx
```
: only retry with bounded backoff; report the number of attempts and last error if still failed.
Empty data: first determine whether non-trading days, today-only, reporting period or filtering conditions cause expected empty results, do not directly claim service failure.
Missing or outdated local data: report database path and latest date, give initialization or synchronization suggestions, do not silently switch to full-market remote per-stock requests.

Fault Routing

CLI does not exist, version is abnormal, authentication is not configured or built-in Skills are incomplete: enter CLI Entry.
MCP is not connected, authentication fails or tool intent needs to be identified: enter MCP Entry.
REST parameters, fields or error codes are unclear: enter API Entry.
Python installation, remote toolkit or local marketdb issues: enter Python SDK Entry.

Applicable Objects and Result Preferences

Ordinary users directly mention stock names and questions they want to know; Skill is responsible for code, tool and parameter conversion.
Agents/automation use structured output, stable error semantics and clear exit status by default.
Python/research users can specify time window, adjustment caliber, fields, file format and local database path.
Users can specify "only provide summary / return table / save as CSV or Parquet / provide reproducible command"; when not specified, display summary for small results, store large results in files.

Common Error Avoidance

Wrong: Require users to provide complete
```
thscode
```
first; Correct: First search and disambiguate using names or codes.
Wrong: Request Key again after switching MCP, CLI or Python; Correct: Recheck and reuse unified credential sources.
Wrong: Download full-market data to verify authentication; Correct: Use the smallest bounded real request of the target capability.
Wrong: Treat CLI installation as a prerequisite for all tasks; Correct: Directly use other entries when users explicitly select them.

Frequently Asked Questions

Where to get the Key for the first use? Go to https://fuyao.aicubes.cn/admin; you can configure it according to platform commands later, or choose to have the Agent configure it for you.
Why am I still prompted after configuring the Key? First check if the current process inherits user environment variables, then check user-level credential files; do not directly request again.
Can other methods be used directly after CLI login? Unified environment variables or credential files can be reused across methods; migrate from old CLI Keyring to unified source first if only old CLI Keyring exists.
What to do with CLI after unified Key is updated? Execute
```
auth login --api-key-stdin --replace
```
via stdin, do not logout first.
What if the client does not read global environment variables? Configure client Secret from unified source, then reconnect, do not let users re-register or input.
Can I check funds? Supports public fund information, disclosure, net value, returns, holder structure, ETF/LOF snapshots and ETF daily data; does not support subscription/redemption transactions, risk indicators or fund recommendations.
Can I check valuations? Supports batch query of the latest five valuation snapshots of A-shares; currently does not provide historical valuations, custom indicators or index/fund valuations.
Can I check Hong Kong stocks or minute-level market data? Not currently; clearly explain the boundaries, only provide alternative entries when data meanings are equivalent.

Capability Boundaries

Good at handling: A-share market data and adjustment, financial reports and indicators, latest valuations, indices/sectors/featured data, public fund information and on-exchange market data, local DuckDB synchronization and export.
Requires user materials or confirmation: Multiple targets with the same name cannot be uniquely disambiguated, investment portfolios or self-owned lists, non-default time/adjustment/output requirements.
Out of scope: Minute K/tick/Level-2, Hong Kong/US stocks, fund subscription/redemption transactions/risk indicators/recommendations, futures/options, macro data/news announcement originals/research reports/backtesting engines.
Clearly explain when out of scope; only provide alternative paths when data meanings are equivalent, do not use approximate data, static examples or simulated data as substitutes for real results.

hithink-finance

NPX Install

Tags

SKILL.md Content (Chinese)