Schwab Marketdata Ops

schwab-marketdata-ops

> Responsibility disclaimer: 本工具调用 Schwab Market Data > Production API。用户须自行阅读 与 > ，并对其使用方式的合规性负全责。 > schwab-marketdata-mcp 与 schwab-marketdata-skill 的作者不对违反 > Schwab ToS 的使用承担责任。

Activation handshake (run first)

激活本 skill 时第一步必须调用 get_server_info，确认返回的 server_version 落在 frontmatter compatible_mcp_version 范围内：

get_server_info()
→ { "server_version": "0.1.x", "supported_tools": [...13 names...] }

若版本不匹配或调用失败：立即停下，告知用户升级 schwab-marketdata-mcp 或本 skill，不要继续执行业务调用。

完整握手流程（含 token 体检）：

1. get_server_info()  → 校验 server_version ∈ compatible_mcp_version
2. health_check()     → 校验 token_state == "valid"
                       且 token_expires_in_days >= 0.5
3. 若任一步骤失败 → 立即停下，按 reference 修复

Quick Start — 7 步从零到 hello-world

第一次接入或换台机器，按顺序读以下 7 个 step 文件：

| Step | 文件 | 期望产出 | | ---- | ---- | -------- | | 1 | [references/quick-start/step-1-developer-portal-app.md](references/quick-start/step-1-developer-portal-app.md) | Schwab Developer Portal app 已创建，App Key / Secret 已拿到 | | 2 | [references/quick-start/step-2-credentials-env.md](references/quick-start/step-2-credentials-env.md) | .env 已填好（chmod 600），pre-commit 钩子已装 | | 3 | [references/quick-start/step-3-first-oauth.md](references/quick-start/step-3-first-oauth.md) | token.json 已落地（chmod 600） | | 4 | [references/quick-start/step-4-token-health-check.md](references/quick-start/step-4-token-health-check.md) | health 模块退出 0，token_state == "valid" | | 5 | [references/quick-start/step-5-first-mcp-tool-call.md](references/quick-start/step-5-first-mcp-tool-call.md) | 最小 Python MCP client 跑通 get_quote("VOO") | | 6 | [references/quick-start/step-6-cursor-integration.md](references/quick-start/step-6-cursor-integration.md) | ~/.cursor/mcp.json 注册成功，agent 能调 13 个 tool | | 7 | [references/quick-start/step-7-cron-launchd-setup.md](references/quick-start/step-7-cron-launchd-setup.md) | cron / launchd 健康巡检已启用，桌面通知通道已自检 |

Common usage scenarios

仿照 helis "I want to..." 路由表，按用户意图直达对应工具与参考文档。

"我要查实时报价"

| 场景 | 用什么 | 备注 | | ---- | ------ | ---- | | 单只股票 / ETF / 指数 | get_quote("AAPL") / get_quote("$SPX") | symbol 必须 UPPERCASE；指数加 $ 前缀 | | 批量 (≤ 50) | get_quotes(symbols=[…]) | 超 50 自行分批，否则 SchwabValidationError(field="symbols") | | 期权合约 | get_quote("AAPL 240119C00170000") | OSI 21 字符：root 6 字符（含空格右补齐）+ YYMMDD + C/P + 8 位 strike(×1000) |

→ Schema 完整定义见 [references/tools/tool-reference-quotes.md](references/tools/tool-reference-quotes.md)。

"我要研究期权链"

1. get_option_expiration_chain(symbol) — 先取可用到期日列表
2. get_option_chain(symbol, contract_type=…, strike_count=…, strike_range=…) — 按 ATM/OTM/ITM 拉具体合约
3. 多步骤研究型工作流 → 转用 schwab-marketdata-workflows skill 的 option-chain-research.md playbook

→ Schema 见 [references/tools/tool-reference-options.md](references/tools/tool-reference-options.md)； Greeks 时效性见 playbook Cautions 段与 [references/concepts/osi-option-symbol.md](references/concepts/osi-option-symbol.md)。

"Token 过期了怎么办"

1. health_check()
   → 看 token_state ∈ {"valid","missing","malformed","insecure_perms"}
   → 看 token_expires_in_days（< 0.5 强烈建议立即 reauthorize）
2. 若 SchwabAuthError(reason="refresh_token_expired" | "token_not_initialized")：
   uv run python -m schwab_marketdata_mcp.auth login_flow   # 默认
   # 或 manual_flow（headless / SSH-only / WSL2）
3. 重新 health_check() 确认 token_state == "valid"

→ 完整对照表与逐步处置见 [references/troubleshooting/auth-overview.md](references/troubleshooting/auth-overview.md)； OAuth 流程详解见 [references/oauth/oauth-overview.md](references/oauth/oauth-overview.md)； token 生命周期见 [references/oauth/oauth-token-lifecycle.md](references/oauth/oauth-token-lifecycle.md)。

"限流被拒了怎么办"

| 症状 | 处置 | | ---- | ---- | | SchwabRateLimitError(retry_after_seconds=N) | 等待 N 秒后重试；连续两次告诉用户 | | stderr 出现 {"event":"rate_limit_warning","remaining":<20} | 将批量请求改用 get_quotes（一次 50）；或降低 SCHWAB_RATE_LIMIT_PER_MIN | | 0 slots 立即 raise | agent 端实施 retry-with-backoff（schwab-py 内部已重试 SCHWAB_MAX_RETRIES 次） |

→ token-bucket 行为与排查见 [references/operations/rate-limit-token-bucket.md](references/operations/rate-limit-token-bucket.md)； 4 种限流症状分流见 [references/troubleshooting/rate-limit-overview.md](references/troubleshooting/rate-limit-overview.md)。

"我想看 server 健康"

get_server_info()  → server_version / mcp_sdk_version / schwab_py_version / supported_tools
health_check()     → token_state / token_expires_in_days / rate_limit_remaining_per_min / recent_error_count_24h

两者组合即可在 30 秒内回答 "MCP server 是否健康、token 是否有效、限流是否已被吃掉"。

→ Schema 见 [references/tools/tool-reference-meta.md](references/tools/tool-reference-meta.md)。

"我要把数据画 K 线 / 拉历史"

get_price_history(symbol, period_type, period?, frequency_type, frequency?, ...)

(period_type, period, frequency_type, frequency) 四元组只接受 受限组合，非法组合服务端静默 400。MCP server 在 Pydantic 层提前 拦截。

→ Schema + 合法组合表见 [references/tools/tool-reference-price-history.md](references/tools/tool-reference-price-history.md)； 笛卡尔积错误处置见 [references/troubleshooting/validation-pricehistory-cartesian.md](references/troubleshooting/validation-pricehistory-cartesian.md)。

"我要查 instrument 元数据 / 公司基本面"

| 场景 | 用什么 | | ---- | ------ | | 已知 ticker → 元数据 | search_instruments(symbols=["AAPL"], projection="SYMBOL_SEARCH") | | 已知 ticker → 基本面 | search_instruments(symbols=["AAPL"], projection="FUNDAMENTAL") | | 已知 9 位 CUSIP | get_instrument_by_cusip(cusip="037833100") | | 公司名模糊查找 | search_instruments(symbols=["TESLA"], projection="DESCRIPTION_SEARCH") |

→ Schema 见 [references/tools/tool-reference-instruments.md](references/tools/tool-reference-instruments.md)。

"我要看 top movers / 当日异动"

get_movers(index="DJI"|"COMPX"|"SPX"|..., sort_order=..., frequency=...)

index 等枚举值必须传 enum 名（"DJI"），不是 wire 值（"$DJI"）。

→ Schema + 枚举详解见 [references/tools/tool-reference-movers.md](references/tools/tool-reference-movers.md)。

"我要从自己的 Python / TypeScript / Rust 应用调"

| 客户端 | 文件 | | ------ | ---- | | Python（mcp SDK） | [references/integration/python-mcp-client.md](references/integration/python-mcp-client.md) | | TypeScript / Node | [references/integration/typescript-mcp-client.md](references/integration/typescript-mcp-client.md) | | Rust（rmcp 或自实现） | [references/integration/rust-mcp-client.md](references/integration/rust-mcp-client.md) | | Shell + jq pipe | [references/integration/cli-jq-pipe.md](references/integration/cli-jq-pipe.md) |

Data coverage clarifications

get_price_history 就是 K 线 / candlestick 接口

如果你在找 OHLCV bar（candle / kline / candlestick），get_price_history 就是对应的 tool。返回结构包含 candles[]，每根 candle 含 open / high / low / close / volume / datetime（毫秒级 epoch）。

支持的粒度由 (period_type, frequency_type, frequency) 三元组决定：

• period_type=DAY：MINUTE × {1, 5, 10, 15, 30}（约 48 天 / 9 个月历史）
• period_type=MONTH：DAILY / WEEKLY（最多 6 个月）
• period_type=YEAR：DAILY / WEEKLY / MONTHLY（最多 20 年）
• period_type=YEAR_TO_DATE：DAILY / WEEKLY（年初至今）

亚分钟级 K 线（秒级、tick 级）不在 Schwab Market Data API 范围内。

→ 完整合法组合表 + 笛卡尔积错误处置见 [references/tools/tool-reference-price-history.md](references/tools/tool-reference-price-history.md) 与 MCP 仓库的 README → "Data coverage clarifications"。

Schwab Market Data API 不提供的数据

以下数据在 Schwab Market Data Production API 上架构性不可用，需要 第三方数据源补齐：

• Time & sales / tape（逐笔成交） —— Schwab 2024 API 迁移移除

TIMESALE_* services 后，REST 与 Streaming 都没有。

• Tick-by-tick history（逐笔历史） —— Schwab API 不提供。
• Level 2 历史快照 —— 仅 Streaming，REST 无历史回放。
• 基本面 / 财报时间序列（EPS 历史、营收历史等）—— quotes 带

FUNDAMENTAL 字段但没有对应历史接口。

• 新闻 / SEC 文件 —— Market Data API 不提供。

各数据类的推荐第三方（Polygon.io、Tiingo、Alpaca、Databento、FMP、SEC EDGAR）见 MCP 仓库 README → "Data coverage clarifications"。

Trader API 不在范围内

Trader API 端点（账户、订单、成交、持仓）显式排除在范围之外 —— 本 skill 只涵盖只读 Market Data。如果用户请求下单 / 修改持仓，立刻 拒绝并指向 MCP README 的 "Responsible use" 段。

Decision tree — pick the right tool

| 用户意图 | 用什么 tool | | ----------------------------------------- | -------------------------------------------------------- | | 单只股票/ETF/指数现价 | get_quote(symbol="AAPL") | | 一次性查多只行情（≤50） | get_quotes(symbols=[...]) | | 历史 K 线 / OHLC | get_price_history(symbol, period_type, …) | | 期权链快照 | get_option_chain(symbol, contract_type=…) | | 期权到期日列表 | get_option_expiration_chain(symbol) | | 多市场开闭市状态 | get_market_hours(markets_list=[…]) | | 单一市场开闭市状态 | get_market_hour_single(market_id) | | 当日 top movers | get_movers(index, sort_order) | | 用 ticker 模糊查找 instrument | search_instruments(symbols, projection) | | 用 9 位 CUSIP 精确查找 | get_instrument_by_cusip(cusip) | | 调试 token 状态 / 错误计数 | health_check() | | 取 server 元数据（版本、13 tool 列表） | get_server_info() | | 实时 bid/ask/last 或 1 分钟 K 线（实验性）| get_streaming_snapshot(symbols, service, duration_ms?) |

枚举值全部用 models.py 中定义的 enum 名（如 "VOLUME"、 "NASDAQ"、"DAY"），MCP server 内部会翻译成 schwab-py 的 wire 值。

Key Concepts

| 术语 | 定义 | | ---- | ---- | | accesstoken | Schwab OAuth bearer token，90 分钟有效；schwab-py 在每次 API 调用前自动续签，agent 无需关心。 | | refreshtoken | rotate-on-use：每次刷新都签发新 refreshtoken，7 天绝对寿命到期后必须重新 login_flow，不可绕过（Schwab OAuth 设计如此）。 | | TokenState | health_check() 返回的 4 个枚举：valid（可用） / missing（无 token.json） / insecure_perms（权限非 600/700） / malformed（JSON 损坏或字段缺失）。前三种由 auth login_flow 修复，第四种通常需要先备份再删除 token.json。 | | SchwabAuthError reason | 业务调用失败时附带的细分原因枚举（6 种）：refresh_token_expired_soon / refresh_token_expired / token_not_initialized / token_corrupted / insecure_token_perms / callback_url_mismatch。每种 reason 在 [references/troubleshooting/](references/troubleshooting/) 有独立 5 段处置。 | | ratelimit_bucket | MCP server 用 token-bucket + 滑动窗口（容量 = SCHWAB_RATE_LIMIT_PER_MIN，默认 120）而非 asyncio.Semaphore。区别：Semaphore 在 retry sleep 期间持有 slot，会阻塞其他并发 tool；token-bucket 在 sleep 期间释放 slot，让别的 tool 继续跑。 | | OSI option symbol | 21 字符固定格式：{ROOT:6}{YYMMDD:6}{C\|P:1}{STRIKE×1000:8}，root 不足 6 字符用空格右补齐。例："AAPL 240119C00170000" = AAPL 2024-01-19 Call $170.00；"BRK/B 240419P00350000"（含 /）。可直接传给 get_quote。 | | pricehistory cartesian product | Schwab 对 (period_type, period, frequency_type, frequency) 四元组只接受受限组合，非法组合服务端静默返回 400。MCP server 在 Pydantic 层提前拦截，避免对计费配额的浪费。完整合法组合表见 [references/tools/tool-reference-price-history.md](references/tools/tool-reference-price-history.md)。 | | Pydantic Literal enum 名 vs wire 值 | 公开 API 一律传 enum 名（如 MoversIndex.DJI = "DJI"），MCP server 在内部翻译成 schwab-py 的 wire 值（如 "$DJI"）。这层翻译让 agent 不用记住前缀字符（$ / lowercase / 大小写）。永远不要直接传 wire 值，否则触发 SchwabValidationError。 | | Activation handshake | skill 激活后必经的两步：get_server_info 校验版本兼容、health_check 校验 token 状态。任一失败立即停下，不得静默 fallback。 | | error normalization | 所有 schwab-py 异常被 server 包装成 {"error": "Schwab*Error", ...} dict 返回，不抛异常穿透 MCP 协议；agent 必须永远先查 error 字段再读 payload。 | | non-redistributable | Schwab Market Data 数据不可再分发；任何 markdown / 报告写入必须留在私有仓库（workflows skill 用 gh repo view --json isPrivate 强制校验）。 |

Architecture overview

┌────────────────────┐
│  AI agent (this    │  Cursor / Claude / Kiro / 自定义 SDK 客户端
│  skill activates)  │
└────────┬───────────┘
         │ MCP JSON-RPC over stdio
         ▼
┌────────────────────────────────────────────┐
│  schwab-marketdata-mcp（独立仓库）          │
│  Pydantic → token-bucket → schwab-py       │
└──────────┬─────────────────────────────────┘
           │ HTTPS Bearer access_token
           ▼
┌────────────────────────┐
│ Schwab Market Data API │ api.schwabapi.com
└────────────────────────┘

完整架构与 5 个核心组件、数据流、信任边界见 [references/concepts/architecture-overview.md](references/concepts/architecture-overview.md)。

Glossary

跨 OAuth / MCP / Schwab API / 限流 / 错误体系的术语速查见 [references/concepts/glossary.md](references/concepts/glossary.md)。

11 个最关键概念的 "为什么这样设计" 解释见 [references/concepts/key-concepts.md](references/concepts/key-concepts.md)。

Schema cheat-sheet（详尽版按 family 拆分到 references/tools/）

get_quote(symbol: str, fields?: list[QuoteFields])  # symbol must be UPPERCASE; "$SPX"/"AAPL  240119C00170000" also OK
get_quotes(symbols: list[str], fields?, indicative?)  # ≤50 symbols / call

get_price_history(
  symbol, period_type, period?, frequency_type, frequency?,
  start_datetime?, end_datetime?, need_extended_hours_data?, need_previous_close?
)
# Cartesian-product rules in references/tools/tool-reference-price-history.md.  TZ-aware datetimes only.

get_option_chain(symbol, contract_type?, strike_count?, ...)  # see references
get_option_expiration_chain(symbol)
get_market_hours(markets_list: list[MarketEnum], date?)
get_market_hour_single(market_id, date?)
get_movers(index, sort_order?, frequency?)
search_instruments(symbols, projection)
get_instrument_by_cusip(cusip: 9 alphanumerics)
health_check()
get_server_info()

# Experimental — bounded WebSocket snapshot (≤10 s):
get_streaming_snapshot(
  symbols: list[str],                                # ≤ 20
  service: "LEVELONE_EQUITIES" | "CHART_EQUITY",
  duration_ms: int = 2000                            # [500, 10000]
)

Error normalization

所有业务 tool 在出错时返回 dict 而非抛出（让 agent 看到结构化数据）：

| error 字段 | 处置 | | --------------------------- | --------------------------------------------------------------------------------------- | | SchwabAuthError | 看 reason → [references/troubleshooting/auth-overview.md](references/troubleshooting/auth-overview.md) 路由表（6 种 reason 各有独立子文件）。 | | SchwabRateLimitError | retry_after_seconds 后重试或降低 SCHWAB_RATE_LIMIT_PER_MIN。详见 [references/troubleshooting/rate-limit-overview.md](references/troubleshooting/rate-limit-overview.md)。 | | SchwabTransientError | Schwab 5xx/网络抖动；可短期重试，频繁出现告知用户。详见 [references/troubleshooting/transient-errors.md](references/troubleshooting/transient-errors.md)。 | | SchwabValidationError | 输入参数错误；详见 [references/troubleshooting/validation-overview.md](references/troubleshooting/validation-overview.md)。 |

完整分流索引见 [references/error-recovery.md](references/error-recovery.md)。

Compatibility matrix

不同 agent 客户端对本 skill frontmatter 字段的支持情况。详细 5 客户端 × 8 字段表格见仓库根 README.md 的 "Compatibility matrix" 段。关键 约定：所有非标准 frontmatter 字段（compatible_mcp_version / required_workspace / language_directive / auto_activate / activation_handshake / compatibility / dependencies / governance）只是文档化约束——真正的执行靠本 SKILL.md body 的 运行时检查（get_server_info 版本握手 + cwd 校验 + 中文回复指令）。 即便客户端不识别 frontmatter 字段，skill 行为仍正确。

FAQ

25+ 个常见问题速查见 [references/faq.md](references/faq.md)（按"入门 / 安装注册 / OAuth / 限流 / 调用 / 安全 / skill / 故障"7 类分组）。

Reference index

按主题分类的完整 reference 文件索引，仿 helis SKILL.md 的多级表格结构。

Quick Start (7 files)

| File | Description | | ---- | ----------- | | [quick-start/step-1-developer-portal-app.md](references/quick-start/step-1-developer-portal-app.md) | 注册 Schwab Developer Portal app，拿 App Key / Secret | | [quick-start/step-2-cred

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kevinkda
• Source: kevinkda/schwab-marketdata-skill
• License: MIT

Install and usage instructions live in the source repository linked above.