sparklesfinance kit

Manual · environment

Provider configuration stays local.

The bundle contains variable names, never values. Configure only the read-only adapters you intend to select; a missing provider is allowed and never triggers fallback.

Necessary variables7
Site variables0
Secret persistenceForbidden
Provider fallbackNever silent

Safe setup

Load values into the selected host process.

Never put values in a prompt, repository, plugin package, fixture, receipt, log, or this static website. The provider contracts are shared; only the host's environment-loading path differs.

Use your shell, service manager, or a private environment loader. The Pi package does not load a .env file itself.

# Illustrative names only — supply your own private values
export AGENT_CONTACT="ops@example.com"

# Optional read-only adapters. Omit any you will not select.
export OPENFIGI_API_KEY="<secret-manager:openfigi>"
export TUSHARE_TOKEN="<secret-manager:tushare>"
export ALPACA_API_KEY_ID="<secret-manager:alpaca-key-id>"
export ALPACA_API_SECRET_KEY="<secret-manager:alpaca-secret>"
export TWELVE_DATA_API_KEY="<secret-manager:twelve-data>"
export FRED_API_KEY="<secret-manager:fred>"

# Launch Pi from the same private environment
pi --finance-track cn
Do not paste secrets into chat. Ask the capability inventory whether a variable name is configured; never ask it to display the value.

Provider inventory

Every network adapter owns its authority.

Shared operator identity

CN · HK · USNon-secret caller identification
AGENT_CONTACT

Set once and reuse everywhere. It identifies the operator to public-source adapters and the active host's status surface; it grants no provider, entitlement, or cross-track authority.

Eastmoney

CN · HKPublic-web, read-only local analysis

No provider-specific environment variable. Uses the shared AGENT_CONTACT and a fixed plugin product label.

Sina Finance

CNPublic-web, read-only local analysis

No provider-specific environment variable. Available only as an explicitly selected daily-history alternative after a reported Eastmoney failure; it never runs automatically.

Tushare Pro

CNCaller-owned credential, read-only
TUSHARE_TOKEN

Used only after explicit adapter selection. It is required for CN symbol and historical-name discovery; it is not required for Eastmoney history of an already-known exact code. Provider entitlement and permission apply.

CNINFO

CNPublic, read-only local analysis

No provider-specific environment variable. Uses AGENT_CONTACT, and only for explicitly requested disclosure or announcement work.

HKEX / HKEXnews

HKPublic, read-only local analysis

No provider-specific environment variable. Uses AGENT_CONTACT for supported board-meeting and disclosure inputs.

SEC EDGAR

USPublic, read-only

No provider-specific environment variable. EDGAR and XBRL use the shared monitored AGENT_CONTACT and fixed plugin product labels.

Alpaca Market Data

USCredentialed, read-only market data
ALPACA_API_KEY_IDALPACA_API_SECRET_KEY

These are the actual Alpaca market-data credentials; caller identification comes from AGENT_CONTACT. The T6 broker review accepts explicit external capability packets or receipts and does not bundle an Alpaca SDK, account session, or trading authority.

Interactive Brokers

US broker reviewCaller-owned external gateway or export

IBKR Gateway/TWS, its SDK, credentials, login state, and entitlements are not bundled. Select an external adapter or bounded caller-owned receipt explicitly; Sparkles receives no broker mutation authority.

Futu OpenD

CN · HK · US tape capabilityCaller-owned external process and entitlements

OpenD, the Futu SDK, credentials, login state, quote rights, and provider certification are not bundled. T6 validates an explicitly selected bounded capability packet; it does not start, install, authenticate, or silently fall back to OpenD.

OpenFIGI

Shared identityCredentialed, read-only
OPENFIGI_API_KEY

Optional identity resolution adapter. The returned mapping does not silently move a request between tracks.

Twelve Data

US company profileCredentialed, read-only
TWELVE_DATA_API_KEY

Optional company-profile source with provider terms and coverage limitations retained.

FRED

US / macroCredentialed, read-only
FRED_API_KEY

Optional macro adapter. Series metadata and vintage assumptions remain explicit.

One shared identity

Set the operator contact once.

AGENT_CONTACT is reused by every CN, HK, and US provider adapter and by the active host's finance-track status surface. It is identification, not a credential, and grants no cross-track or provider authority.

Use /finance-track cn, /finance-track hk, or /finance-track us in either host lane. Switching does not relabel observations or select a provider. Pi renders the compact state in its TUI statusline; DSH folds agent-scoped session events into a projection and renders it through the web shell.overlay. Neither surface echoes the contact value to the model or session log.

Per-plugin authority: Tushare is required for CN name-to-code discovery, not for Eastmoney history of an already-known exact code. Alpaca credentials enable US quote, OHLCV, universe, corporate-action, and news slices only. SEC, CNINFO, HKEX, and Eastmoney reuse AGENT_CONTACT and never inherit an Alpaca or Tushare token.

Configuration law

Four rules make optional providers safe.

  • A credential belongs only to its named adapter and never grants authority to another provider or market track.
  • The caller selects a provider explicitly; absence or failure is reported instead of triggering fallback.
  • Rights, entitlement, service-level, correction, and completeness limits remain visible in the result.
  • Deterministic tests use rights-safe fixtures and scripted transports, never ambient credentials or live network calls.