Simple Template · Stock Price Snapshot

用例 1: 获取美股最新价格与市场状态

GET /v1/markets/snapshot，股票必须 market=us_equity。已配置 TradFi live 时返回现价 / 买卖一价 / 当日统计；缺 size 或滚动 24h 时 data_status=partial（验收通过，不是失败）。Free Sample Key 可能限制可用 ticker。

Use this template when

需要股票现价 / 当日统计并复用 MarketOK Schema
同一 client 还要支持 market=crypto 的 crypto snapshot
与 Docs API Reference 同一 path / 字段

适用用户: 美股投研、量化开发者、投研工具团队

输出预览静态样例，非实时

AAPL · us_equitysession_change_pct +0.33

$311.97

data_status

partial

volume_24h

day_volume 1

request_id

—

静态 fixture（来自 API 单测）· 禁止自造 listing/asset id · 非实时

美股实时目前仍可能返回 metadata.data_status=no_data。验 Key 请用 BTC crypto 快照.

登录后可加载实时结果；当前为静态样例。

Run in Playground 在 MCP Playground 试跑创建 API Key API Reference

API / MCP 调用

同一个模板同时支持 REST、Python 与 MCP Prompt。选择你熟悉的入口。

import requests

url = "https://api.gatedata.ai/api/v1/markets/snapshot?query=AAPL&market=us_equity"
r = requests.get(url, headers={"Authorization": "Bearer gd_live_…"}, timeout=10)
r.raise_for_status()
data = r.json()
meta = data.get("metadata") or {}
# Equity TradeFi live: partial is normal (no size / no rolling 24h).
# Prefer day_volume / session_change_*; do not require volume_24h.
print(meta.get("data_status"), data.get("price") or data.get("last_price"),
      data.get("day_volume"), data.get("session_change_amount"), data.get("updated_at"),
      meta.get("limitations"))
print("empty_reason", data.get("empty_reason"), "field_sources", data.get("field_sources"))

输入参数

修改下方参数，上方代码示例和请求 URL 会同步更新。Live 模板的默认值即可一键跑通。

Ticker / 查询query

与 API Reference / Playground 相同的 GET /v1/markets/snapshot query

市场market

股票必填（如 us_equity）。支持 crypto | us_equity | hk_equity

GET/api/v1/markets/snapshot?query=AAPL&market=us_equity

输出与解读

静态样例响应静态样例，非实时

{
  "data_status": "partial",
  "market": "us_equity",
  "ticker": "AAPL",
  "price": 311.97,
  "last_price": 311.97,
  "session_change_pct": 0.33,
  "day_open": 309,
  "day_high": 311,
  "day_low": 305,
  "day_volume": 1,
  "day_turnover": 2,
  "open_price": 309,
  "high_price": 311,
  "low_price": 305,
  "volume": 1,
  "turnover": 2,
  "volume_ratio": null,
  "bid_price": 313.66,
  "ask_price": 314.29,
  "best_bid": 313.66,
  "best_ask": 314.29,
  "bid_volume": null,
  "ask_volume": null,
  "mid_price": 313.975,
  "spread_bps": 20.065291822597196,
  "market_session": "post_market",
  "snapshot_type": "single_venue",
  "updated_at": "2026-08-05T20:56:00Z",
  "as_of_utc": "2026-08-05T20:56:00Z",
  "venue_quotes": [],
  "field_sources": {
    "price": "live:session",
    "last_price": "live:session",
    "as_of_utc": "live:session",
    "session_change_pct": "live:session",
    "market_session": "live:session",
    "bid_price": "live:orderbook",
    "best_bid": "live:orderbook",
    "ask_price": "live:orderbook",
    "best_ask": "live:orderbook",
    "mid_price": "live:orderbook",
    "spread_bps": "live:orderbook",
    "day_open": "live:day",
    "day_high": "live:day",
    "day_low": "live:day",
    "day_volume": "live:day",
    "day_turnover": "live:day",
    "open_price": "live:day",
    "high_price": "live:day",
    "low_price": "live:day",
    "volume": "live:day",
    "turnover": "live:day"
  },
  "metadata": {
    "data_status": "partial",
    "partial": true,
    "limitations": [
      "order_book_size_unavailable",
      "price_change_24h_not_mapped_session_semantics",
      "volume_24h_not_mapped_use_day_volume",
      "day_stats_are_session_day_not_rolling_24h",
      "volume_ratio_unavailable_live",
      "listing_id_unavailable_source_code_only",
      "missing_fields"
    ],
    "missing_fields": [
      "price_change_24h",
      "volume_24h",
      "bid_size",
      "ask_size",
      "volume_ratio"
    ],
    "updated_at": "2026-08-05T20:56:00Z",
    "object_refs": []
  }
}

字段说明

pricenumber | null
最新一笔有效成交的价格
last_pricenumber | null
当日最新成交价，与 price 同义。
price_change_24hnumber | null
过去 24 小时绝对价格变化
price_change_24h_absolutenumber | null
过去 24 小时绝对价格变化
price_change_24h_percentnumber | null
过去 24 小时价格涨跌幅
volume_24hnumber | null
过去 24 小时累计成交数量
volume_24h_unitstring | null
volume_24h 的计量单位，例如以计价币计的金额
amplitudenumber | null
当日价格振幅百分比 =（当日最高价 − 当日最低价）/ 上一交易日收盘价 × 100
open_pricenumber | null
当日第一笔有效成交价。
high_pricenumber | null
当日最高成交价。
low_pricenumber | null
当日最低成交价。
prev_close_pricenumber | null
上一交易日收盘价，用作涨跌计算的基准价。
volumenumber | null
统计窗口内累计成交数量，单位为股或币
turnovernumber | null
统计窗口内累计成交金额，约等于成交数量 × 成交价。
avg_pricenumber | null
成交均价 = turnover ÷ volume
volume_rationumber | null
当前成交量相对历史均值的倍数（量比）
day_opennumber | null
当日开盘价
day_highnumber | null
当日最高价
day_lownumber | null
当日最低价
day_volumenumber | null
当日累计成交数量
day_turnovernumber | null
当日累计成交金额。
session_change_pctnumber | null
当日相对上一交易日收盘价的涨跌幅
session_change_amountnumber | null
当日相对上一交易日收盘价的绝对涨跌额。
bid_pricenumber | null
买一价
ask_pricenumber | null
卖一价
best_bidnumber | null
买一价，与 bid_price 同义。
best_asknumber | null
卖一价，与 ask_price 同义。
bid_volumenumber | null
买一挂单数量
ask_volumenumber | null
卖一挂单数量
mid_pricenumber | null
双边均有时的中间价：(bid + ask) / 2。
spread_bpsnumber | null
相对 mid_price 的买卖价差（基点 bps）。
listing_idstring | null
交易场所挂牌标识，标识某个交易品种在特定交易场所的挂牌记录
venue_idstring | null
交易场所标识，标识交易所或交易平台
tickerstring
展示用的代码，例如 AAPL、BTC。
marketstring
该接口支持的市场码（crypto | us_equity | hk_equity）。
market_sessionstring
当前所处的交易时段。
枚举说明
- pre_market盘前
- regular常规交易时段
- post_market盘后
- closed休市
- unknown会话未知
snapshot_typestring
本次快照的聚合范围
枚举说明
- multi_venue跨多个交易场所聚合，venue_quotes 有 2 行以上
- single_venue限定单一挂牌，venue_quotes 最多 1 行
venue_quotes[]object[]
按交易场所拆分的报价行
venue_quotes[].listing_idstring
交易场所挂牌标识，标识某个交易品种在特定交易场所的挂牌记录
venue_quotes[].venue_idstring
交易场所标识，标识交易所或交易平台
venue_quotes[].pricenumber
该交易场所的最新成交价
venue_quotes[].volumenumber | null
该交易场所的成交数量
venue_quotes[].volume_24hnumber | null
该交易场所过去 24 小时的成交数量（有则返回）
venue_quotes[].updated_atiso8601
该交易场所的报价时间（UTC ISO-8601）
field_sourcesobject
各字段的数据来源标识，取值如 live:session、live:orderbook、live:day。
updated_atiso8601 | null
本次报价或响应的最近更新时间（UTC ISO-8601）。
as_of_utciso8601 | null
报价在数据源发生的时间（UTC ISO-8601）
source_delay_secondsnumber | null
数据延迟秒数（当前时间 − as_of_utc/updated_at）
snapshot_timeiso8601 | null
盘口快照时间
data_statusstring
业务数据可用状态
枚举说明
- ready数据完整可用
- partial部分字段缺失，价格与盘口可能仍可用
- stale数据源延迟超过阈值，见 source_delay_seconds
- no_data查询成功但无结果；代码无法识别时 empty_reason=object_not_found
- not_ready该数据域尚未开放
metadata.data_statusstring
业务数据可用状态
枚举说明
- ready数据完整可用
- partial部分字段缺失，价格与盘口可能仍可用
- stale数据源延迟超过阈值
- no_data查询成功但无结果；代码无法识别时 empty_reason=object_not_found
- not_ready该数据域尚未开放
metadata.partialboolean
为 true 表示响应本就不完整，与 data_status=partial 对应。
metadata.limitationsstring[] | null
本次响应的已知数据限制，例如 order_book_size_unavailable、volume_ratio_unavailable_live、quote_source_latency_high、snapshot_stale。
metadata.missing_fieldsstring[]
已知缺失的字段名，例如 price_change_24h、volume_24h、bid_size。
metadata.updated_atiso8601 | null
本次响应的组装时间（UTC ISO-8601）
empty_reasonstring
无数据时的原因码，例如 object_not_found、snapshot_expired。
reasonstring
无数据的可读说明。
next_actionstring
无数据时的下一步建议。
try_paramsobject
本次请求实际使用的查询参数回显，例如 query、market。
metadata.object_refs[]object[]
统一对象引用数组
object_refs[].typestring
对象引用类型
object_refs[].idstring
对象标识，标识 type 指定的具体对象
object_refs[].entity_idstring
主体标识，标识公司、项目方或协议等主体
object_refs[].asset_idstring
资产标识，标识股票、加密资产等资产对象
object_refs[].listing_idstring
交易场所挂牌标识，标识某个交易品种在特定交易场所的挂牌记录
object_refs[].instrument_idstring
交易工具标识，标识股票、现货交易对或合约等具体交易产品
object_refs[].venue_idstring
交易场所标识，标识交易所或交易平台
object_refs[].event_refstring
关联事件标识，标识与当前对象关联的事件
object_refs[].market_idstring
预测市场标识，标识预测事件下的具体市场
object_refs[].venuestring
对象关联的平台代码
object_refs[].resolved_fromstring
对象解析所用输入来源
object_refs[].resolution_confidencestring
对象解析置信度
metadata.limitations includes listing_id_unavailable_source_code_onlystring (limitation token)
未能识别挂牌，此时 object_refs 可能为空，但仍会返回价格。

如何解读结果

始终先读 metadata.data_status — equity live 常见 partial（size/24h）或 stale（RTH 延迟）
优先 day_volume / session_change_*；勿用 session 日伪造 volume_24h / price_change_24h
优先 listing_id 或 query+market；裸 ticker 不带 market 会走 crypto 路径（no_data）
未知 equity ticker → empty_reason=object_not_found（HTTP 200），不是 ambiguous
有 field_sources 时看 live:session / live:orderbook / live:day

边界与下一步

Do NOT use for

不返回逐笔成交，不替代专业行情终端
不会用 equity 当日量伪造成 crypto 滚动 24h

常见边界与状态

路径为 /v1/markets/snapshot — 不存在 stock-state
股票必须 market=us_equity|hk_equity；其他 Market 接口仅支持 crypto
无盘口 size、无滚动 24h 量 → partial（验收通过）；RTH 过迟 → stale
Live 空盘口不会静默回退小时级快照买一卖一

BTC 实时快照（crypto） API 参考 · snapshot 打开我的账户