Sparkles for Pi

Turn Pi into a finance research assistant for mainland China, Hong Kong, and US markets.

This is the Pi distribution of Sparkles. DeepSeek Harness users should install the sibling @dsh-sparkles/dsh-sparkles package, which reuses the same finance cores but owns separate DSH tools, agent/session lifecycle, browser presentation, and release maturity.

Ask about a stock or ETF in everyday language. Pi Sparkles brings current market data, price history, company filings, fundamentals, and financial calculations into the conversation, so you can spend less time moving between websites, spreadsheets, and one-off scripts.

What it gives you

• Current quotes and recent price history for supported CN, HK, and US sources.
• Trend, momentum, and volatility analysis with SMA, RSI, and ATR.
• SEC, CNINFO, and HKEXnews filing and disclosure research.
• Fundamental, valuation, portfolio-risk, scenario, event-study, and backtest calculations when the required data is available.
• Bounded CN/HK/US transaction-tape packet review, local possible-fill simulation, read-only broker evidence review, compound compliance checks, non-executable handoffs, and receipt reconciliation.
• Clear source, timestamp, currency, freshness, and data-limit context in answers.

Pi automatically looks up current evidence for questions about price, trend, buying now, or when to sell. You do not need to ask it to "use tools" first.

Quick start

pi install npm:@pi-sparkles/pi-sparkles@0.1.11

For most mainland China and Hong Kong quote/history research, and for SEC filing research, the only setup is a contact address used to identify requests to public data services:

AGENT_CONTACT="you@example.com" pi --finance-track cn

Choose cn, hk, or us. You can switch later with /cn-track, /hk-track, or /us-track inside Pi.

Then ask naturally:

• 分析一下科创50ETF的走势
• 588000 如果现在买，什么时候卖比较好？
• 分析腾讯 00700.HK 最近半年的趋势、动量和波动
• Summarize AAPL's latest SEC fundamentals and cite the evidence.
• Compare this portfolio with its benchmark and explain the largest risks.

Data sources

Research area	Available sources
Mainland China	Eastmoney quotes and daily history; CNINFO disclosures; optional Tushare symbol, name, corporate-action, earnings, quote, and history data; SSE, SZSE, and BSE calendars and rules
Hong Kong	Eastmoney quotes and daily history; HKEXnews disclosures; HKEX calendar and rules
United States	SEC EDGAR and XBRL filings; optional Alpaca quotes, bars, news, corporate actions, and asset data; optional OpenFIGI identity mapping and Twelve Data company profiles; NYSE and Nasdaq calendars and rules
Macroeconomics	Optional Federal Reserve Bank of St. Louis FRED series
Day-trader and execution review	Exact bounded packets supplied by a caller-selected external market-data or broker capability; the package validates declared identity, rights, clocks, sequence, conditions, corrections, limits, and receipts without authenticating the provider
Your own data	Portfolio files and supported structured imports for research and calculation

Availability and history depth depend on the selected provider and your account's permissions. Public-web sources do not promise uptime, completeness, or real-time delivery.

Optional data-service setup

The package loads without provider credentials. Add only the services you want; you do not need every variable below.

Variable	What it enables
AGENT_CONTACT	Identified access to supported public services, including Eastmoney, CNINFO, SEC, and HKEXnews. Use one email address everywhere.
TUSHARE_TOKEN	Optional Tushare data for mainland China. Tushare permissions and points apply.
ALPACA_API_KEY_ID, ALPACA_API_SECRET_KEY	Optional Alpaca US prices, bars, news, corporate actions, and assets. Feed permissions apply.
OPENFIGI_API_KEY	Optional OpenFIGI identity mapping.
TWELVE_DATA_API_KEY	Optional Twelve Data company profiles.
FRED_API_KEY	Optional FRED macroeconomic series.

Example:

AGENT_CONTACT="you@example.com" \
ALPACA_API_KEY_ID="..." \
ALPACA_API_SECRET_KEY="..." \
pi --finance-track us

Your credentials stay in your runtime environment. Sparkles for Pi does not add them to the package or save them in Pi settings. For a project-local installation, add --local to pi install.

External day-trader and broker dependencies

Transaction-tape and broker-review tools require exact caller-supplied packets or receipts from an explicitly selected provider, gateway, export, or adapter. Futu OpenD, Alpaca, IBKR, their SDKs, credentials, login state, and equivalent provider components are external dependencies and are not included in this npm package. Results preserve the declared provider, entitlement, track, venue, clocks, limits, and unsupported claims; Sparkles never silently selects or falls back to another provider.

Sparkles for Pi is read-only research software: it cannot place, change, or cancel broker orders. It is not investment, legal, accounting, or tax advice. See CONFIGURATION.md for the complete source and configuration reference.

Version 0.1.11 · Pi package @pi-sparkles/pi-sparkles