global-stock-data: US market data for AI coding assistants, sourced and tiered

The problem is not data access, it is knowing which data you are allowed to touch

US market data is not scarce. It is scattered, and the terms attached to each pile differ enough that a working prototype can quietly become a compliance problem. The README states the project's own framing plainly: "This project distributes code, not market data. Data is fetched by the user under each source's own terms." That sentence is the whole design.

The target user is an engineer wiring a coding assistant to live market context, or a quant-adjacent developer who wants options Greeks and filing streams without signing up for three vendor accounts. The repository describes a single self-contained Skill file that removes the need to memorize Eastmoney secid prefixes, Yahoo crumb auth flows or SEC EDGAR CIK mappings. Those three examples are the actual friction being solved: identifier formats and handshake details, not the existence of the data.

What makes the project unusual is the compliance tier table. Sources are graded S, B, C or excluded, with terms quoted verbatim. Tier S covers SEC EDGAR, Treasury and CFTC, marked as commercially usable and redistributable, with a hard limit of 10 requests per second and a required User-Agent. Tier B is FINRA: files are published for download, but the quoted terms prohibit data mining, scraping or harvesting tools and state non-commercial use. Tier C is CBOE, Nasdaq, Yahoo, Eastmoney, Sina and Tencent, where CBOE requires approval in advance and a license agreement, and Yahoo is described as personal use only. HKEX sits outside the table entirely, because its terms prohibit robots and scrapers whether or not for gain, and the README says a working HKEX shareholding layer was built and then removed rather than shipped. That removal is the most informative thing in the repository.

Thirteen layers, and the V2.0 split between convenience sources and official ones

The architecture diagram groups layers by function: market data, K-line, technical indicators, fundamentals, fund flow, options, SEC filing, and tools. The V2.0 release, titled Official-source-first architecture, added five layers on top of that base: CBOE options with full Greeks and 0DTE flow, FINRA Reg SHO short volume, an EDGAR daily index and full-text search stream, an EDGAR frames screener, and a macro and calendar layer covering Treasury yield curves, CFTC COT and the Nasdaq earnings calendar.

The split matters because the older layers and the newer ones have different legal standing. Real-time quotes come from Sina, Tencent and Eastmoney. Fundamentals blend Eastmoney, Yahoo and SEC XBRL. Options chains in the original layer go through Yahoo crumb auth. All of those sit in tier C. The V2.0 layers lean on CBOE's official CDN feed, FINRA, and EDGAR, which is why the release notes call it official-source-first rather than simply an expansion.

Technical indicators are computed locally in pure Python with no extra dependencies: MA, EMA, MACD, RSI, KDJ and Bollinger. That is a deliberate boundary. Anything derivable from price series stays in the skill file, so the number of outbound requests does not grow with the indicator count.

One detail worth noting for anyone planning load: the README describes the EDGAR frames layer as covering any XBRL tag across the whole market, with a company range of roughly 1,842 to 5,309 depending on the tag. The same section gives a single-day EDGAR index example of 547 Form 4 filings, 370 8-Ks and 261 13Fs. Those are the project's own illustrative figures, not throughput guarantees.

Installing the skill and asking your first real question

The README gives a three-step quick start that it describes as taking about two minutes. You create a skill directory, download SKILL.md into it, and install one dependency. The path below is the Claude Code convention used in the README; Codex and OpenClaw users are told to paste SKILL.md into a system prompt or project context file instead, where the embedded Python runs as-is.

mkdir -p ~/.claude/skills/global-stock-data
curl -o ~/.claude/skills/global-stock-data/SKILL.md \
  https://raw.githubusercontent.com/simonlin1212/global-stock-data/main/SKILL.md
pip install requests

After that, the README says to launch Claude Code and say something like "check AAPL's financials", and the skill activates on its own. There is no server to start, no API key to paste, and no port to open. The only dependency declared is requests.

Before you touch any SEC layer, the README carries an explicit warning: set SEC_CONTACT in SKILL.md to your real name and email. SEC requires a declared User-Agent, and requests without one are rejected as an Undeclared Automated Tool. According to the README, the code raises a clear error if you forget, which is a better failure mode than a silent empty response. Treat that edit as part of installation, not as optional configuration; the README frames it as a precondition rather than a nicety.

Where the skill file approach breaks down

Distribution as a single Markdown file with embedded Python buys zero-auth simplicity and costs you the things a package gives you. There is no version pinning mechanism described in the README, no lockfile, and no dependency beyond requests to resolve. Updating means re-running the curl command, which overwrites your local SKILL.md, including the SEC_CONTACT value you set during installation. The README does not document a merge or migration path for that, so anyone who edits the file should keep their own copy of the edit.

Rate limits are the second constraint. The tier table states a hard limit of 10 requests per second for tier S sources, which covers EDGAR. The screener layer queries XBRL tags across thousands of companies. Nothing in the README describes batching, caching or backoff behaviour, so a loop over many tickers is your problem to throttle.

The third limitation is jurisdictional. Despite the name, the coverage described is US equities. K-line history for US names goes back to 1984 via Sina and Yahoo, and the SEC layers are inherently US. The HKEX layer was removed on terms grounds, and no other non-US exchange layer appears in the architecture diagram. If your universe is global, the project name oversells what the code does.

Finally, tier C is a real ceiling, not a footnote. CBOE options data requires approval in advance and a license agreement per the quoted terms. Yahoo is personal use only. A production system that leans on the CBOE Greeks layer without that approval is outside what the README describes as permitted. For commercial use, the README says to rely only on tier S.

How this differs from yfinance and from vendor APIs

The obvious comparison is yfinance, which also wraps Yahoo data behind a Python interface and also carries Yahoo's personal-use terms. The difference is scope and labelling. yfinance is a library you call directly; global-stock-data is a skill file an assistant reads, and it deliberately mixes sources rather than staying on one. Where yfinance gives you Yahoo's quote and statement endpoints, this project routes quotes through Sina, Tencent and Eastmoney, fundamentals through Eastmoney, Yahoo and SEC XBRL, and options through both a Yahoo crumb path and the CBOE CDN feed. That redundancy is the point: if one source changes shape, the layer above it can still answer.

The second comparison is a commercial vendor API. Those give you a contract, a rate-limit policy, support and, usually, redistribution rights. This project gives you none of that. What it gives instead is a tier label on every source, quoted terms, and a documented refusal to ship a scraper for a source whose terms forbid it. If you need an SLA, a vendor is the right answer and this is the wrong tool. If you need to know exactly which terms you are operating under before you write the first line, the tier table is more useful than a vendor's marketing page.

The third comparison is writing your own fetchers. That is what the project replaces, and the README is candid about the specific tedium: secid prefixes, crumb auth, CIK mapping. Those are identifier and handshake problems with stable solutions, and reimplementing them per project is wasted effort.

Maintenance, releases and what the licence does and does not cover

The repository is not archived and the last push was on 2026-09-16. The release history is short and recent: v2.0.0 on 2026-07-24 introduced the official-source-first architecture, v2.0.1 the same day addressed error handling and timezone correctness, and v2.0.3 on 2026-07-26 fixed data correctness in the Tencent quotes, EDGAR Frames and CBOE layers. Two of the three releases in that window are correctness fixes rather than features, which tells you the parsing surface is where the work is. Anyone building on the CBOE or EDGAR frames layers should expect upstream format changes to be the main upgrade driver.

The licence is Apache-2.0, which covers the code in the repository. It does not cover the data the code fetches. The README is explicit that the project distributes code and not market data, and that data is fetched by the user under each source's own terms. So the Apache-2.0 grant and the tier table answer different questions: the first is about your rights to the software, the second is about your rights to what flows through it. A permissive code licence does not launder a restrictive data term, and the tier table exists precisely because those two things get conflated. This is not legal advice; the quoted terms in the table are the primary reference.

Upgrade cost is low in the mechanical sense, since replacing SKILL.md is one curl command, and high in the operational sense, because you must re-apply any local edits and re-verify the field names your code depends on after a correctness release.

Editorial conclusion

Adopt it if you are building assistant-driven workflows over US equities and you care about where each number came from: the tier table and the per-source labels are the reason to pick this over a generic scraping helper. Do not adopt it if you need licensed commercial redistribution, if your universe is non-US, or if you want a hosted API with an SLA, because this ships code and the fetches happen from your machine under each source's own terms. Verify three things before you build on it: that SEC_CONTACT is set to a real name and email in SKILL.md, that the tiers your workflow touches are S-tier for anything commercial, and that the raw JSON returned by the CBOE and EDGAR layers still matches the field names your code reads, since the v2.0.3 release was itself a data-correctness fix.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. simonlin1212/global-stock-data on GitHub