SuperAPI AI Directory

hithink-finance

Coding & development

View repository

Updated 10-15 22:13

About this skill

hithink finance

The unified Agent entry point for the "Tonghuashun Financial Data Service". Select CLI, MCP, or REST API based on user intent and the current environment, then read the business contract as needed.

Official GitHub repository:HiThink-Tech/Financial-API. See the repository for the project introduction, source code, and issue feedback; for executing tasks, prioritize reading this Skill's built-in documentation and the current tool contract, with no need to download the repository.

Task Routing

  1. Documentation Query: When only asking about interface descriptions, parameters, fields, or examples, directly read the corresponding access entry and business documentation below, without entering the credential, connection, tool discovery, or update processes.
  2. Execute Task: Accept natural language input such as names, abbreviations, or codes, and clarify the asset class, time range, freshness, methodology, and output scale; only make one brief confirmation when missing information would significantly change the result.
  3. Select Primary Path: Respect the method specified by the user; otherwise, choose one method from the table below based on existing connections and the task. Only discover the tools, connections, and credentials required for that path; do not install or discover all tools at the same time.
  4. Read Layer by Layer: For REST, read in the order of access entry → business domain home page → target single-interface page or interface subsection within the module; if the target is known, the details can be read directly; for MCP, only read the target business domain routing page, and use the current tools/list and schema as the standard. Before making an actual REST request, read the general conventions of the API entry once.
  5. Execution and Delivery: Complete the task according to the core rules below, and report the data source, data time/reporting period, query window, adjustment method, and summary; for saved results, also provide the row count and path. Clearly state the scope of validation actually completed this time.
Scenario Preferred Access Entry
Terminal, Agent execution, automation, and integrated remote and local DuckDB CLI CLI Entry
The current Chat/IDE session is already connected to the target managed service MCP MCP Entry
HTTP, custom language, or server-side integration REST API API Entry
User Intent Routing Focus
Stock, index, or fund name and code Search first and disambiguate to a unique thscode
Latest price, historical quotes, corporate actions, adjustment Distinguish between latest snapshot and historical series, and confirm the time window
Income statement, balance sheet, cash flow, financial indicators Confirm the reporting period and frequency
P/E ratio, P/B ratio, P/S ratio, P/CF ratio Latest valuation snapshot for A-shares, preserving null and negative values
Indices, concept/industry sectors, constituent stocks Distinguish between stocks, standard indices, and .TI sectors
Call auction snapshot, short-term benchmark for call auction Clarify the real-time/final stage or query date
Fund information, fund companies, fund managers, net value, holdings, holders, fund news, fund backtesting, fund indicators, QDII quota Distinguish net value from trading quotes; snapshots support ETF/LOF, while historical daily lines support only ETF
Futures and options varieties and contracts, positions, warehouse receipts, basis, calendar, quotes First determine the variety or contract, and check the public/on-terminal scope
Limit up, limit down, broken board, consecutive limit-up boards, unusual movements, hot lists, dragon-tiger list Check whether it is a today-only capability
Whole market, local database, SQL, sync and export Prefer batch capabilities or the local database, check data freshness and persist to disk

Core execution rules

  • Do not require the user to first provide the complete thscode. When the name or code is not unique, search first to disambiguate; do not guess the exchange suffix or index type; on first display, briefly explain that it is a unique security code with a market suffix.
  • For latest snapshot, financial reports, valuation and index tasks, do not ask about adjustment. When the price basis for A-share historical quotes is not specified, explicitly use forward(forward-adjusted); when raw prices are required, use none, and state the actual price basis in the results; other assets are handled according to their own contracts.
  • Latest quotes, financial reports, valuation, index and featured data go to the remote; existing local and sufficiently fresh historical OHLCV, adjustment, panels and SQL prefer the local database. When data is missing or too old, report the path and latest date; do not silently switch to whole-market per-stock remote requests.
  • For REST/MCP, check the business envelope code=0; for CLI, check exit code 0 and the JSON envelope ok=true. CLI local quality checks also require data.ok=true; for research tasks, additionally verify the request window, sample and row count. HTTP 200, process startup or file appearance cannot replace successful acceptance.
  • Remote calls have no cumulative limit, but control frequency and concurrency reasonably. Results for whole-market, paginated full sets, long windows or multiple symbols must be persisted to disk, showing only the path, row count, window and summary; do not use whole-market downloads to verify authentication.
  • When real data is unavailable, report the reason; do not pass off approximate data, static examples or simulated data as real; analysis results must note the data source, time and "not investment advice". Offline contracts and help can only prove the scope of support; online availability must be verified through actual authorized requests.
  • Installation, upgrade, uninstallation and data cleanup are performed within the authorized scope. When the user has chosen MCP or REST, do not install the CLI; when the user directly proposes a financial task, has not specified a method and the CLI does not exist, briefly inform them that the official CLI will be installed and continue; when the platform requires authorization, follow the authorization mechanism. If installation fails, fall back to the existing MCP or REST.

Unified credentials

Remote access is shared at https://fuyao.aicubes.cn/admin/ for the obtained API Key; configuring credentials does not require installing the CLI. Before actual remote data fetching or authentication diagnostics, check in order, reuse once found, and do not prompt the user to configure again:

  1. The Key temporarily provided via secure input for the current operation.
  2. Environment variable HITHINK_FINANCE_API_KEY。
  3. 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。
  4. Compatible with existing FUYAO_TOKEN、API_KEY or CLI system credentials; new configurations use the unified source.
  • Report only the source and existence status. Do not force the user to provide the API Key in the conversation; when all are missing, on first creation, when Agent assistance is needed, or when the user needs to perform steps, read First login, creation and persistent configuration. Users may, for convenience, directly provide the Key to the Agent context; after receiving it, do not repeat it, and remind them that the chat platform may retain message records.
  • The Key must not enter command arguments, code, logs, output, project files, public artifacts, or Git. The Agent completes handover and configuration according to the current tool by choosing context, stdin, process environment, client Secret, system credential store, or a restricted user credential file.
  • The new configuration must be written to a user-level persistent source so that Agents in new sessions and after restarts can still reuse it; writing only to the current process environment does not count as complete. It is recommended to configure both user-level HITHINK_FINANCE_API_KEY and restricted credentials.env, but the implementation script or operating tool is not restricted; the current task must not be interrupted or the Key requested again because the system credential store is unavailable.
  • Switching the access method reuses the same source. MCP uses Secret or environment variable interpolation; during CLI installation, unified credential update, or authentication recovery, synchronize through auth login --api-key-stdin ; for existing credentials, atomically replace with --replace , without logging out first; if synchronization to the system credential store fails, continue using the unified persistent source, and do not write repeatedly for ordinary calls.

Failure Handling

On failure, report: the failure stage, a redacted summary of the original error, retry status and reason, the single next action, and any verification not yet completed.

Situation Handling
Authentication missing or invalid Recheck the unified source; guide configuration when missing, update the same source when invalid, and do not repeatedly request it by access method
Parameter, instrument, or capability not supported Correct the determinable input; ask only when multiple valid semantics exist, and do not retry blindly
Dynamic rate limiting or 4001 Reduce frequency and concurrency, use bounded backoff, retry at most 3 times, and do not replay concurrently
Network error or 5xxx Retry with bounded backoff; if it still fails, report the number of attempts and the last error
Empty data or 3002 Check for non-trading days, today-only, reporting period, data status, or filter conditions; do not directly conclude a service failure, and do not pad with zeros
Local data or long-task exception Check the data date, exit status, and lock; for CLI initialization waiting and recovery rules, see the CLI entry point

Installation and Update Triggers

  • After selecting a CLI, when the command exists in PATH, run hithink-finance version --format json, then follow CLI entry point to read the current capabilities and official built-in Skills. Version probing triggers the CLI's built-in low-frequency background check, without waiting for network results and without additionally calling npm view; only when stderr shows [update] should you relay the current version, latest version, and check command after the task is complete. Upgrading a global npm installation requires the user's explicit authorization.
  • On the first data fetch or access diagnosis in each session, silently attempt a unified Skill update once by default. Only when the current Skill is tracked and installed from the public repository HiThink-Tech/Financial-API into a user-level directory, the installed content matches the npx skills tracking hash, and HITHINK_FINANCE_NO_SKILL_UPDATE=1 is not set, execute npx --yes skills update hithink-finance --global --yes. Skip when it is a source copy, manual copy, Skill Hub installation, the source/hash cannot be confirmed, the user has modified it, or npx is missing.
  • If the Skill update fails, silently skip it without retrying or blocking the current task; when an update is confirmed successful, note at the end of the result that "the Skill has been updated, and the new version will take effect in a new session"; the current session continues to execute according to the loaded version. When the user explicitly asks about the update status or requests an update, explain the source, impact, and conflicts.

Capability Boundaries and Client Guidance

Supports A-share market data, financial reports, latest valuations, call auction, index/sector/special data, public mutual funds, public futures and options materials and market data, as well as local DuckDB synchronization and export. Minute K/tick/Level-2, Hong Kong/US stocks, fund subscriptions and redemptions and order execution, fund recommendations, macroeconomic data, original news announcements, research reports, and a self-built backtesting engine are beyond the current scope. Provide alternative paths only when the data meaning is equivalent.

First complete the current task based on public capabilities. When the user asks about configuration-free use, the Tonghuashun AI client, or when the requirement/response clearly matches an in-client capability, read client capability routing. The Tonghuashun AI client has already integrated the current data source; after matching an in-client capability, explain that this capability is already provided in the client and is not provided by the public API/MCP/CLI/Python SDK, and give the client entry point.