Simple Template · Latest Crypto Price Snapshot

用例 2: 获取最新加密货币价格

一次请求返回 BTC、ETH、SOL 等主流币的实时价格、24 小时涨跌和成交量（与 Docs 共用 MarketOK Schema）。

Use this template when

在页面或机器人里显示实时币价
给看板或告警补一个价格字段
第一次调用，验证 API Key 通不通

适用用户: 开发者、量化团队、行情产品

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

BTC / USD-394.26 (24h)

$62,580.20

Vol 24h · $494.7M · ready

gatebinanceokx

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

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=BTC&market=crypto"
r = requests.get(url, headers={"Authorization": "Bearer gd_live_…"}, timeout=10)
r.raise_for_status()
data = r.json()
print(data.get("price"), data.get("price_change_24h"))

输入参数

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

Ticker / 查询query

snapshot 支持裸 ticker + market（资产级）。仅在钉单所 listing 时再加 venue/market_type/quote。

市场market

交易所（可选）venue

如 gate / binance — 资产级 snapshot 不必填

市场类型（可选）market_type

钉 listing 时填 spot 或 perp

报价币（可选）quote

钉 listing 时通常为 USDT

GET/api/v1/markets/snapshot?query=BTC&market=crypto

输出与解读

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

{
  "data_status": "ready",
  "listing_id": "listing_gate_BTC_USDT_spot",
  "metadata": {
    "object_refs": [
      {
        "type": "asset",
        "id": "asset_btc",
        "asset_id": "asset_btc",
        "resolved_from": "asset_entity",
        "resolution_confidence": "resolved"
      },
      {
        "type": "instrument",
        "id": "instrument_btc_usdt_spot",
        "asset_id": "asset_btc",
        "instrument_id": "instrument_btc_usdt_spot",
        "resolved_from": "asset_entity",
        "resolution_confidence": "resolved"
      },
      {
        "type": "listing",
        "id": "listing_gate_BTC_USDT_spot",
        "asset_id": "asset_btc",
        "instrument_id": "instrument_btc_usdt_spot",
        "listing_id": "listing_gate_BTC_USDT_spot",
        "venue_id": "venue_gate",
        "resolved_from": "asset_entity",
        "resolution_confidence": "resolved"
      }
    ],
    "updated_at": "2026-08-17T17:07:11Z",
    "data_status": "ready",
    "limitations": []
  },
  "price": 64079.8,
  "price_change_24h": 813.8134600000001,
  "price_change_24h_absolute": 813.8134600000001,
  "price_change_24h_percent": 1.27,
  "updated_at": "2026-08-17T17:07:11.560722597Z",
  "venue_id": "venue_gate",
  "volume_24h": 263668502.3634611,
  "volume_24h_unit": "quote"
}

字段说明

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 可能为空，但仍会返回价格。

如何解读结果

读 price 前先看 metadata.data_status
对比报价时以 updated_at 为准
对比 venue_quotes 可判断跨所价差

边界与下一步

Do NOT use for

不返回订单簿深度
不提供买卖建议

常见边界与状态

metadata.data_status 可能为 ready / partial / stale / no_data
指南 / API Reference / Playground 共用 MARKETS_SNAPSHOT_* 契约

查看历史 K 线打开 API Reference 创建 API Key