TickHub-US

TickHub-US does one thing: it turns US / HK market data scattered across 20 sources into structured tools a model can call directly.

Every number must come from a tool call, and must carry its source and compliance tier. Quotes, K-lines, financial statements, options chains and unusual flow, short data, SEC filings and 13F, policy rates, energy — the service fetches, normalizes and caches them, then returns a single DataEnvelope instead of asking the model to remember numbers or stitch URLs itself.

It is a deployable standalone service, not a prompt. Three things come with that: process isolation (a real process exposing MCP stdio / Streamable HTTP plus a th-us CLI), compliance interception (a commercial call against a disallowed tier raises ComplianceError and does not walk the fallback chain) and cache degradation (Redis when available, in-process LRU when not, with an explicit warning).

• 41 MCP tools + ten th-us CLI groups, same response shape at every entry point.

• 20 sources graded S / B / C / D (plus tier X, never integrated); the grade is enforced at the call site, not in documentation.

• Fallback order and compliance grades live in YAML, so changing a source is a config change, not a release.

• Optional Redis, automatic LRU fallback, and cache keys that separate commercial from non-commercial calls.

• The wheel ships its own config, so pip install works from any directory.

This project distributes code, not market data. Data is fetched by the user under each source's own terms. For commercial use, rely only on tier-S sources.

Why TickHub-US

One sentence: direct API calls give you freedom, aggregation libraries give you breadth, and TickHub-US gives you "a model can retrieve sourced, compliance-tagged data without writing code".

Related MCP server: Stock MCP

Architecture

TickHub-US · MCP Server + CLI · v1.0.0
│
├── Access       MCP stdio / Streamable HTTP (41 tools) + th-us CLI (10 command groups)
│                ↳ commercial_use is mandatory at the entry point; missing → ComplianceError
│
├── Orchestration
│                Fallback chain (config/sources.yaml) → try each source → record all attempts
│                Compliance gate (config/compliance.yaml) → tier decision → denial is final
│                Cache (Redis, auto-degrades to in-process LRU) → per-domain TTL
│
├── Domains      quotes / K-lines / indicators / fund flow / short / volatility / Taiwan
│                fundamentals / statements / key metrics / analysts / institutional holders
│                options chain / unusual flow / CBOE quotes
│                SEC filings / daily feed / full-text / XBRL / insiders / 13F
│                macro / rates / FX / energy
│
└── Adapters     20 providers, each registering a compliance_source
                 SEC EDGAR · Treasury · CFTC · Fed Board · NY Fed · BIS · ECB · EIA · EIA spot
                 TWSE · TPEx · FINRA · CBOE · Eastmoney · Sina · Tencent · Polygon · Yahoo · Nasdaq · local

Design trade-off: source priority is written in YAML, not code — one line changes the fallback order. Compliance works the same way: the code only knows compliance_source. When a source changes its terms, that is a config change, not a release.

Compliance tiers

Source terms differ a lot, and "official" does not mean "free to use". These grades come from reading each source's actual terms; the full text is in config/compliance.yaml.

A working HKEX shareholding layer was removed. Shipping scraping code that violates a source's terms would defeat the point of grading sources in the first place.

Why keep tier-D Yahoo and Nasdaq? The difference is whether a substitute exists: Yahoo is the only source for HK K-lines and for markets beyond the US and HK, and Nasdaq is the only key-free earnings calendar. So the code stays and the terms are quoted in full; whether to use them is the user's call under those terms.

The gate really fires, and it is not a documentation convention:

• commercial_use=false: S / B / C / D are all callable; C / D carry warnings.

• commercial_use=true: S passes; tier B is denied by default and can be whitelisted per source; C / D raise ComplianceError and never walk the fallback chain to get around it.

• If every source on the chain is denied by compliance, the call raises ComplianceError instead of silently degrading.

Quick start

Distribution name tickhub-us · Python package tickhub_us · CLI th-us. Requires Python ≥ 3.11.

3 steps, 2 minutes.

# 1. Install (PyPI 1.0.0, published 2026-10-26)
pip install tickhub-us
# or from a checkout
git clone https://github.com/QuotaFuse-ai/TickHub-US.git
pip install -e TickHub-US
# development
pip install -e "TickHub-US[dev]"

# 2. Declare your SEC contact (EDGAR requires a real name + email; missing → E_CONFIG)
export SEC_CONTACT="Zhang San zhangsan@example.com"

# 3. Try one call
th-us quote get AAPL
th-us quote get AAPL --output json      # stdout is JSON only, logs go to stderr

A real response, captured 2026-10-26 (fields elided):

{
  "schema_version": "1.0",
  "domain": "quote_us",
  "symbol": "AAPL",
  "payload": {
    "symbol": "AAPL",
    "price": 347.725,
    "prev_close": 348.22,
    "change_pct": -0.14,
    "high_52w": 348.36,
    "low_52w": 242.89,
    "pe": 41.89,
    "eps": 8.3,
    "currency": "USD"
  },
  "source": "sina",
  "compliance_tier": "C",
  "freshness": "realtime",
  "fetched_at": "2026-10-26T08:35:47Z",
  "cache_hit": false,
  "trace_id": "54dc2aebd9904304",
  "warnings": ["新浪财经 属 Tier C：商用需事先书面许可，当前为非商用调用。"],
  "attempts": [
    { "provider": "polygon", "status": "disabled" },
    { "provider": "sina", "status": "ok", "tier": "C" }
  ]
}

Look at compliance_tier and warnings: this row came from Sina, a tier-C source, so the same call with commercial_use=true is rejected outright. attempts shows Polygon skipped for lack of a key and Sina answering.

One-click install

Four distribution channels, one code base — PyPI wheel / sdist, GitHub Release assets, GHCR container image, and source install. All three published channels are live as of v1.0.0. See Publishing.

# PyPI
pip install tickhub-us
th-us quote get AAPL

# Container (stdio, launched by the MCP client)
docker run --rm -i -e SEC_CONTACT="Zhang San zhangsan@example.com" \
  ghcr.io/quotafuse-ai/tickhub-us

# Container (HTTP, published to loopback only)
# Binding a non-loopback address inside the container requires a bearer token
# and a Host allowlist, so the two env vars below are not optional.
docker run --rm -p 127.0.0.1:8001:8001 \
  -e MCP_HTTP_TOKEN=change-me \
  -e MCP_HTTP_ALLOWED_HOSTS=127.0.0.1:8001 \
  ghcr.io/quotafuse-ai/tickhub-us \
  mcp http --host 0.0.0.0 --port 8001

pip install places config/sources.yaml and config/compliance.yaml under <prefix>/share/tickhub-us/config, so the CLI works from any directory. Source installs find the repo's config/ automatically; TICKHUB_US_CONFIG_DIR overrides both.

Connect to an MCP client

# stdio (preferred for local agents)
th-us mcp stdio

# Streamable HTTP
th-us mcp http --host 127.0.0.1 --port 8001

# Both at once
th-us start-all

MCP client configuration (Claude Desktop style):

{
  "mcpServers": {
    "tickhub-us": {
      "command": "th-us",
      "args": ["mcp", "stdio"],
      "env": { "SEC_CONTACT": "Zhang San zhangsan@example.com" }
    }
  }
}

Commercial calls

Every data call requires an explicit commercial_use (an MCP tool argument, or --commercial-use on the CLI). That is the only mechanism that puts compliance at the call site — an agent cannot violate a source's terms without saying so.

# Whitelist specific tier-B sources (a non-empty whitelist is authoritative)
export TICKHUB_US_ALLOW_TIER_B_SOURCES=finra,eia_spot

# Or allow all tier-B sources (coarse switch)
export TICKHUB_US_ALLOW_TIER_B_COMMERCIAL=true

# Polygon commercial use: the key alone is not enough, confirm the subscription
export POLYGON_API_KEY=...
export TICKHUB_US_POLYGON_COMMERCIAL_BASIS=true

Endpoints

Price — Sina / Tencent / Eastmoney real-time quotes (US + HK) · Sina K-lines (US back to 1984) · Yahoo K-lines (HK and markets beyond US/HK) · MA / EMA / MACD / RSI / KDJ / BOLL computed locally.

Value — Eastmoney three statements + key indicators (including HK) · Yahoo quoteSummary structured statements / analyst estimates / institutional holders · SEC XBRL companyfacts.

Flow & positioning ⭐ — FINRA market-wide daily short volume and short interest (with days to cover and rankings) · CBOE options chains (IV + full Greeks) and unusual-flow detection · CBOE volatility indices (VIX since 1990) and the VIX term structure · Eastmoney daily fund flow.

Filings & events ⭐ — EDGAR submissions · daily index event stream (same-day Form 4 / 8-K / 13F) · full-text search back to 2001 · Form 4 insider trades line by line · 13F institutional holdings · XBRL frames market-wide cross-section (a free screener).

Macro / rates ⭐ — Treasury yield curve · CFTC COT · earnings calendar · Treasury auctions and federal debt · BIS central-bank policy rates · ECB FX / rates / yield curve · NY Fed SOFR / EFFR · Fed Board H.10 / H.6.

Taiwan / energy ⭐ — TWSE + TPEx official open APIs (quotes / P/E / monthly revenue / margin) · EIA weekly crude and natural gas inventories plus spot prices.

Tools — stock search · full-market list · per-symbol and keyword news · ticker ↔ CIK.

Quotes / K-lines / technical indicators

Short data / volatility ⭐

Fundamentals

Options

Filings / insiders / 13F ⭐

Macro / rates / FX ⭐

Energy ⭐

Diagnostics

Usage examples

Say these to your AI assistant to trigger the tools (the CLI equivalent is in parentheses):

Data sources

Tiers: S = government and central-bank data, commercial + redistribution OK (some require attribution) · B = published but terms-restricted, verify before commercial use and do not redistribute · C = needs prior approval or personal research only · D = terms prohibit automated access without permission; personal study and research only, at your own risk. Quoted basis: Compliance tiers.

All requests go through core/http.py: per-host rate limiting (SEC 8 req/s, CFTC / FINRA / CBOE 4 req/s, Nasdaq 2 req/s, default 5 req/s), exponential-backoff retries, an 8 MB response cap, and cross-host redirects allowed only to hosts registered in config/sources.yaml.

Configuration

Everything is environment variables. A .env file in the current directory (or its parent) is loaded automatically on first use. th-us config show prints the effective settings with secrets redacted.

Data-source access

Runtime and cache

MCP HTTP server

commercial_use is not an environment variable — it is a per-call parameter, deliberately, so that no deployment-wide setting can flip a whole process into commercial mode by accident.

Fallback chains and cache

config/sources.yaml defines one chain per domain. A failure (throttle / no data / compliance denial / upstream 5xx) is recorded in DataEnvelope.attempts and the next source is tried:

quote_us:  polygon → sina → tencent → eastmoney    # TTL 30s,  realtime
fundamental: eastmoney → yahoo → sec_edgar         # TTL 12h,  eod
rates: bis → ecb → ny_fed → federal_reserve → treasury
options_flow: cboe → yahoo                          # TTL 60s, realtime

Cache TTLs are per domain: quotes 30 s, options 60 s, news 5 min, statements and filings 12 h, CIK mapping 24 h. When Redis is unavailable the cache degrades to an in-process LRU and says so in the log — cache degradation never changes which data source is used. Cache keys include the commercial_use flag, so a commercial result is never served to a non-commercial call.

DataEnvelope

Every response uses the same envelope, so an agent can consume source / freshness / compliance_tier / attempts directly:

{
  "schema_version": "1.0",
  "domain": "quote_us",
  "symbol": "AAPL",
  "payload": { "...": "..." },
  "source": "sina",
  "compliance_tier": "C",
  "freshness": "realtime",
  "fetched_at": "2026-10-26T01:30:00Z",
  "cache_hit": false,
  "trace_id": "9f2c1e7a4b6d0c33",
  "warnings": ["新浪财经 属 Tier C：商用需事先书面许可，当前为非商用调用。"],
  "attempts": [{ "provider": "polygon", "status": "disabled" }]
}

(The warnings string is read from config/compliance.yaml and is currently Chinese-only; callers should treat it as opaque text, not parse it.)

Technical indicators additionally carry underlying, which records the source and tier of the K-lines they were computed from: the indicator itself is tier-S local computation, but its trustworthiness depends on its input, and that tier stays visible to the caller.

MCP tools

41 tools in total, grouped below. The three signatures fixed by the product spec:

(The th_us_ prefix is omitted above.)

MCP HTTP security

By default the server listens on loopback only (127.0.0.1 / localhost / [::1]) with DNS-rebinding protection always on. The Host / Origin allowlists are passed explicitly by create_app(); in the loopback case only loopback hosts are allowed.

Listening externally is an explicit action — missing one requirement fails startup with E_CONFIG:

With MCP_HTTP_TOKEN set, every request except GET /healthz (kept anonymous for container probes) must carry Authorization: Bearer <token>. The check uses a constant-time comparison; failures return 401 with WWW-Authenticate: Bearer realm="tickhub-us". /healthz returns only {"status": "ok"} — no version, no tool count (SEC-12).

MCP_HTTP_HOST=0.0.0.0 \
MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
MCP_HTTP_ALLOWED_HOSTS=tickhub.internal:8001 \
th-us mcp http

FinanceCoffer event stream

On top of the MCP / CLI surface, TickHub-US can publish what it already collects as standard events for the downstream warehouse FinanceCoffer. The event contract (Event Contract v1) lives in the FinanceCoffer repository and is shared by both ends.

The publisher is a sidecar (us_collector), not part of the MCP server process — if you never start it, nothing is published.

# Dry run first: assemble events, print a summary, write nothing
python -m us_collector.scheduler --config us_collector/config.yaml --once --dry-run

# One real round
python -m us_collector.scheduler --config us_collector/config.yaml --once

# Scheduled sidecar: 17:30 America/New_York, weekdays
python -m us_collector.scheduler --config us_collector/config.yaml

Design notes:

• Sidecar, never fatal: Publisher.publish does not raise into the collector. When Redis is unavailable the event goes to a SQLite outbox (var/us_collector/outbox.sqlite3) and is flushed later with bounded retries; a run that cannot publish still completes.

• Deterministic event_id: an evt_ prefix plus a hash of the business key, so retries and duplicates collapse into one row downstream.

• Exactly one instance: a PID lock (var/us_collector/scheduler.lock) makes a second scheduler exit with code 2 instead of double-publishing.

• Heartbeat on non-trading days: US market holidays publish data_type=heartbeat only — no tool is called and no data event is emitted.

• Amounts stay strings: decimal amounts are validated as strings and never round-tripped through a float.

Field definitions, failure handling and versioning: docs/specs/event-contract.md.

Amount units and valuation fields (QUOT-249)

The contract requires amounts in the basic currency unit of that market — USD for US listings, HKD for HK. quote_us resolves through polygon → sina → tencent → eastmoney (config/sources.yaml), and the vendors do not publish market cap at the same scale, so the value the warehouse saw depended on which vendor answered first:

A provider that is not in the table is treated as unknown, not as scale 1 — the collector would rather publish no amount than a guessed order of magnitude. Scales are pinned by magnitude evidence (market cap ÷ price = shares outstanding) and per-provider fixtures, one file entry per vendor; see UNIT-AUDIT.md.

quote events also carry pb_mrq — the vendor's most-recent-quarter price-to-book, the same number as pb, published under that name because it is the ratio the downstream reference basis reads. It is emitted only when strictly greater than zero; otherwise the field stays absent and pb_mrq appears in quality_metrics.missing_fields. US/HK reference values are expected to stay null downstream this phase (no currency column in dwd.stock_quote_snapshot) — that is a recorded limitation, not a defect.

US biz_key values for quote end in a field-generation tag |g2 (the unit normalisation above). event_id hashes only provider|data_type|symbol|biz_key, and the downstream DWD layer is append-only and dedupes by that id, so a corrected amount re-published under the old key would be dropped as a replay. Cutover and existing data: UNIT-AUDIT.md §5.

Testing and CI

# Full offline run (no network, no Redis needed)
pytest -m "not live"

# Live smoke (needs SEC_CONTACT; Eastmoney endpoints can be skipped outside mainland China)
SEC_CONTACT="you@example.com" TICKHUB_US_LIVE=1 pytest tests/contract/test_live_smoke.py -m live
TICKHUB_US_LIVE_SKIP_REGIONAL=1 ...   # skip the two cases that depend on Eastmoney push2

CI (.github/workflows/ci.yml):

• push / pull_request: Python 3.11 + 3.12 matrix, ruff → compileall → offline tests, as the merge gate;

• workflow_dispatch with live checked: an extra networked job that reads the repository variable SEC_CONTACT (cases skip themselves when it is unset, so the job never goes red) and the optional POLYGON_API_KEY secret, and skips the Eastmoney cases that are unreachable from overseas. Writing code needs no keys; running against live sources does.

Exact check names, copy-paste equivalents for Windows and Linux, and the current required-check status (main is unprotected and there are no rulesets, so CI is advisory only): docs/CI.md.

Two manual release workflows, neither triggered by a push:

Operating steps and the one-time PyPI setup are in Publishing. If egress needs a proxy, set HTTPS_PROXY / HTTP_PROXY (the standard variables requests reads); keep proxy credentials in the environment only — never in config/ and never committed.

Publishing

Both channels are manual dispatch only — pushing a commit or a tag uploads nothing.

PyPI / TestPyPI (publish.yml, already live at 1.0.0):

• Run Actions → Publish to PyPI → Run workflow, pick pypi or testpypi. Auth is GitHub OIDC (Trusted Publishing); no token is stored in the repository.

• One-time setup, needed only for a new project or environment: on the index, Publishing → Add a new pending publisher with project tickhub-us, owner QuotaFuse-ai, repository TickHub-US, workflow publish.yml, environment pypi (or testpypi, a separate account).

• A version, once uploaded, cannot be replaced — bump version in pyproject.toml before re-running. Upload the exact artefacts that passed twine check --strict; do not rebuild between check and upload.

Container (docker.yml): builds and pushes ghcr.io/quotafuse-ai/tickhub-us with the version tag plus latest, then pulls it back and smokes it (anonymous /healthz, authenticated MCP initialize, 401 on unauthenticated POST).

Directory layout

config/                 sources.yaml (chains / rate limits / redirect allowlist), compliance.yaml (tiers)
src/tickhub_us/
  core/                 settings, errors, HTTP, logging, symbols, DataEnvelope
  cache/                tiered TTL + Redis / in-process LRU fallback
  compliance/           tier registry and interceptor
  providers/            20 source adapters + local indicator computation
  market/               quotes, K-lines, indicators, fund flow, short, volatility, Taiwan
  fundamental/          statements, key metrics, analyst estimates, institutional holders
  options/              options chain, Greeks, 0DTE, unusual flow
  filings/              SEC submissions / XBRL / daily index / full-text / Form 4 / 13F
  mcp/                  MCP server (stdio / HTTP)
  cli/                  th-us command tree
tests/
  contract/             interface contracts + live smoke + defect regressions
  compliance/           compliance interception tests
CHANGELOG.md            update log (the only document in the repository)
SKILL.md                compact agent-facing SOP
Dockerfile              image (non-root, stdio by default)
.github/workflows/      ci.yml (gate) + publish.yml (PyPI / Release) + docker.yml (GHCR)

FAQ

Does it need an API key? No, by default. Only Polygon is an optional source (POLYGON_API_KEY); SEC EDGAR needs a real SEC_CONTACT, which is an identity declaration, not a secret.

Will it silently switch sources when data is missing? It will walk the fallback chain, but it will not degrade around a compliance denial — if every source on the chain is denied, it raises ComplianceError and lists each denial in attempts.

Are HK options available? No. The options layer is US only; HK options would require HKEX's paid proprietary feed.

Can it look up stocks outside the US and HK? K-lines and Yahoo fundamentals, yes: Japan .T, Taiwan .TW, Korea .KS, India .NS, London .L, Germany .DE and more. Note that Yahoo is a tier-D source. Taiwan also has the official TWSE / TPEx APIs (tier S, latest trading day only).

How fresh are global rates and FX? ECB and NY Fed update every business day; Fed H.10 is published each Monday for the prior week; BIS lags by a few days to about three weeks depending on the country. Every value carries a date — check the central bank itself when you need today's exact number.

How often does short interest update? FINRA publishes it twice a month, for settlement dates on the 15th and at month-end (moved earlier for holidays), about 8 business days after settlement. The daily dataset is a different one — daily short volume, which counts that day's short-sale trades, not open short positions.

Can a server in mainland China reach Yahoo / SEC? They are overseas services and may be flaky on a direct connection. Use a proxy, or lean on the Eastmoney / Sina / Tencent sources. The CI live job runs on GitHub-hosted runners, which is why the Eastmoney cases are skipped there.

Can I use it without an MCP client? Yes. The th-us CLI covers every endpoint, and --output json feeds any script directly.

Can I install it from PyPI? Is there a Docker image? Yes to both. pip install tickhub-us installs 1.0.0 (PyPI), the same wheel / sdist ship as v1.0.0 release assets, and the container is public at ghcr.io/quotafuse-ai/tickhub-us (tags 1.0.0 and latest, docker pull needs no login). Publishing is a single manual dispatch of publish.yml / docker.yml; steps are in Publishing.

Version

v1.0.0 (2026-10-26) — first stable release, feature-complete against the spec and re-verified end to end against live sources:

• Fixed BIS policy rates always returning 404 (the SDMX key duplicated the D. dimension);

• Fixed Yahoo quoteSummary returning 401 across the board (a non-browser UA got 429, so no crumb could be obtained; now it cools down and retries instead of giving up permanently);

• Added 13 live smoke cases and a workflow_dispatch live job, with an offline regression test for each of the two defects;

• Shipped four distribution channels: PyPI wheel / sdist (publish.yml, PEP 639 metadata), GitHub Release assets, GHCR container image (docker.yml, with a real smoke), and source install; the wheel bundles config/, so it runs from any directory. Verified by installing 1.0.0 from PyPI into a clean venv and running a live quote from outside the repository, and by an anonymous docker pull of ghcr.io/quotafuse-ai/tickhub-us:1.0.0.

Disclaimer

This project provides data-access tooling only. It is not investment advice. Markets carry risk. Data licensing follows each source's terms — see config/compliance.yaml.

License

Apache License 2.0. Author: QuotaFuse · https://github.com/QuotaFuse-ai

Update log: CHANGELOG.md · agent SOP: SKILL.md