# 用 Data API 查代币化股票的每日链上指标 > 原文地址: https://docs.blockvectra.com/zh/guides/stocks/ 数据来自链上公开记录，仅供参考，不构成投资建议。 ## 什么是代币化股票数据集 [#什么是代币化股票数据集] BlockVectra Data API 提供代币化股票（Tokenized Stocks）每日链上指标与元数据查询。该数据集汇总每日转账、铸造、销毁、净供应量变化、持币分布以及去中心化交易所（DEX）交易等指标，帮助开发者跟踪代币化股票在链上的公开动态。 提供该数据集的链以[支持的链](/zh/chains/)页面为准。 * **基础 URL**：`https://dev-api.blockvectra.network/v1/data`——除 `GET /chains` 外，所有 Data API 路由均以链标识为前缀（如 `https://dev-api.blockvectra.network/v1/data/{chain}/…`） * **链标识示例**：`robinhood_mainnet`（本文仅以此作为路径参数示例；提供该数据集的具体链请参阅[支持的链](/zh/chains/)页面） * **身份验证**：在 HTTP 请求头中传入 `x-api-key: ` * **计费与数据覆盖**：按 CU（计算单元）透明计量，仅对 2xx 成功响应计费。若请求的链不支持股票数据集，接口返回 HTTP `422 no_coverage`（不计费） ## 查每日榜单（`GET /{chain}/stocks`） [#查每日榜单get-chainstocks] `GET /{chain}/stocks` 端点提供指定 UTC 日期的代币化股票每日活跃榜单，包含展示元数据（代号、名称等），默认按链上转账活跃度降序（最活跃的代币排在最前）。 ### 请求参数 [#请求参数] * `{chain}`（路径参数，必填）：目标链的标识（例如 `robinhood_mainnet`）。 * `day`（查询参数，可选）：UTC 日期，格式为 `YYYY-MM-DD`。若省略，默认返回最新有记录的日期（若该日无活动记录，返回 `200` 且 `data: []`）。若传入但不是合法的 `YYYY-MM-DD` 日历日期，返回 HTTP `400`（`error.code = "bad_request"`）。 * `limit`（查询参数，可选）：当前响应最多返回条数。默认值为 50；超过 500 的值会被截断为 500；传入 `0` 或非整数会返回 HTTP `400`（`error.code = "bad_request"`）。 ### 分页特性 [#分页特性] 该端点**不支持分页**。`limit` 参数用于限制当前响应返回的最大条数。响应外层的 `StockDailyListEnvelope` 包含 `data` 与 `meta`，其中股票端点不返回 `next_cursor`（该键在响应中完全不出现，而非 `null`）。 ### 代码示例 [#代码示例] ```bash curl -s "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10" \ -H "x-api-key: $BLOCKVECTRA_API_KEY" ``` ```ts const res = await fetch( "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10", { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! }, }, ); const body = await res.json(); console.log(body); ``` ```python import os import requests res = requests.get( "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks?day=2026-09-29&limit=10", headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}, ) print(res.json()) ``` ### 响应结构说明 [#响应结构说明] 响应外层为 `StockDailyListEnvelope`，包含 `data` 与 `meta` 两大字段： * `data`（数组）：日榜单记录列表，每项为 `StockDaily` 对象，按转账活跃度降序（最活跃的代币排在最前）。包含代币标识（`token`、`symbol`、`name`）、转账活跃度（`transfers`、`unique_senders`、`unique_receivers`）、供应量指标（`mint_raw_amount`、`burn_raw_amount`、`net_supply_change`）、持币分布（`holder_count`、`top10_holder_share_bps`）、DEX 交易指标（`dex_swap_count`、`dex_raw_volume`）与刷新时间戳（`refreshed_at`）。 * `meta`（对象）：链元数据对象（`chain`、`chain_slug`、`chain_external_id`、`as_of_block`、`finalized_block`、`coverage`、`refreshed_at`）。股票端点不返回 `next_cursor`。 ## 查单个代币（`GET /{chain}/stocks/{token}`） [#查单个代币get-chainstockstoken] `GET /{chain}/stocks/{token}` 端点根据代币合约地址，查询该代币化股票的基础元数据以及最近最多 30 天的历史每日指标。 ### 请求参数 [#请求参数-1] * `{chain}`（路径参数，必填）：目标链的标识（例如 `robinhood_mainnet`）。 * `{token}`（路径参数，必填）：20 字节代币合约地址，`0x` 可省略，大小写均可（返回地址规范化为 `0x` 开头的 40 位小写十六进制字符）。若地址格式不合法，返回 HTTP `400`（`error.code = "bad_request"`）。 * 若请求的 `{token}` 不是已知的代币化股票，返回 HTTP `404`（`error.code = "not_found"`）。若 `{chain}` 是未知链，返回 HTTP `404`（`error.code = "unknown_chain"`）。 ### 代码示例 [#代码示例-1] ```bash curl -s "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks/0x1111111111111111111111111111111111111111" \ -H "x-api-key: $BLOCKVECTRA_API_KEY" ``` ```ts const token = "0x1111111111111111111111111111111111111111"; const res = await fetch( `https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks/${token}`, { headers: { "x-api-key": process.env.BLOCKVECTRA_API_KEY! }, }, ); const body = await res.json(); console.log(body); ``` ```python import os import requests token = "0x1111111111111111111111111111111111111111" res = requests.get( f"https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks/{token}", headers={"x-api-key": os.environ["BLOCKVECTRA_API_KEY"]}, ) print(res.json()) ``` ### 响应结构说明 [#响应结构说明-1] 响应外层为 `StockTokenEnvelope`，包含 `data` 与 `meta` 两大字段： * `data`（对象）：`StockToken` 对象，包含代币基础元数据（`address`、`symbol`、`name`、`decimals`、`created_block`、`created_tx_hash`、`factory`、`creator`、`mint_address`、`burn_address`、`refreshed_at`）以及历史每日指标数组 `daily`。 * `daily`（数组）：包含最近最多 30 天的历史日指标列表（`StockDailyMetric`），按日期降序（最新在前）排列。每日指标字段结构与上述日榜单中的单日指标相同（不含外层重复的 `token`、`symbol`、`name`）。 * `meta`（对象）：链元数据对象，与日榜单响应一致，不返回 `next_cursor`。 ## 关键返回字段解释 [#关键返回字段解释] ### 每日指标字段（StockDaily 与 StockDailyMetric） [#每日指标字段stockdaily-与-stockdailymetric] 每日榜单与单个代币历史指标均包含以下核心日指标字段： | 字段 | 类型 | 说明 | | ------------------------ | ---------------- | ---------------------------------------------------- | | `day` | `string`（日期） | 聚合统计的 UTC 日期，格式为 `YYYY-MM-DD`。 | | `token` | `string`（地址） | 代币合约地址（仅每日榜单 `StockDaily` 包含），40 位小写十六进制字符加 `0x` 前缀。 | | `symbol` | `string` | 代币符号（例如 `"EXMPL"`）。 | | `name` | `string` | 代币展示名称；若无对应元数据则为空字符串 `""`。 | | `transfers` | `integer`（int64） | 该 UTC 日期内链上转账笔数。 | | `unique_senders` | `integer`（int64） | 该日发起转账的去重发送方地址数量。 | | `unique_receivers` | `integer`（int64） | 该日接收转账的去重接收方地址数量。 | | `mint_raw_amount` | `string`（十进制） | 该日链上铸造的原始代币数量。 | | `burn_raw_amount` | `string`（十进制） | 该日链上销毁的原始代币数量。 | | `net_supply_change` | `string`（十进制） | 该日净供应量变化量（有符号十进制字符串，可能为负）。 | | `holder_count` | `integer`（int64） | 持币地址总数。 | | `top10_holder_share_bps` | `integer` | 前 10 大持币地址所占基点（0–10000，1 bps = 0.01%）。 | | `dex_swap_count` | `integer`（int64） | 该日在去中心化交易所（DEX）涉及该代币的成交笔数。 | | `dex_raw_volume` | `string`（十进制） | 该日在 DEX 上的原始成交总量。 | | `refreshed_at` | `string`（时间戳） | 该日指标最近一次刷新的 ISO-8601 UTC 时间戳。 | ### 代币元数据字段（StockToken） [#代币元数据字段stocktoken] 查询单个代币时，外层 `data` 包含该代币的规格元数据以及最近指标数组： | 字段 | 类型 | 说明 | | ----------------- | -------------------- | ----------------------------------------------------- | | `address` | `string`（地址） | 代币合约地址。 | | `symbol` | `string` | 代币符号。 | | `name` | `string` | 代币完整名称。 | | `decimals` | `integer` 或 `null` | 代币精度小数位数（0–255），不可用时为 `null`。 | | `created_block` | `integer`（int64） | 代币合约被部署的区块高度。 | | `created_tx_hash` | `string`（哈希） | 创建合约的交易哈希，64 位小写十六进制字符加 `0x` 前缀。 | | `factory` | `string`（地址） | 工厂合约地址。 | | `creator` | `string`（地址）或 `null` | 创建者地址；不可用时为 `null`。 | | `mint_address` | `string`（地址）或 `null` | 铸造地址；不可用时为 `null`。 | | `burn_address` | `string`（地址）或 `null` | 销毁地址；不可用时为 `null`。 | | `daily` | `array` | 最近最多 30 天的历史每日指标数组（`StockDailyMetric`），按日期降序（最新在前）排列。 | | `refreshed_at` | `string`（时间戳） | 元数据最近一次刷新的 ISO-8601 UTC 时间戳。 | ### 编码约定说明 [#编码约定说明] API 遵循严格的编码规范以确保跨语言使用时的数据精度与一致性： * **金额安全性（Money-safety）**：所有可能超过 `2^53` 的 256 位整数值（如 `mint_raw_amount`、`burn_raw_amount`、`net_supply_change`、`dex_raw_volume` 等）一律序列化为**十进制字符串**（decimal string），绝不使用 JSON 数字或科学计数/十六进制记法，避免解析浮点数时产生精度截断。在 JavaScript/TypeScript 中建议使用 `BigInt(str)`（例如 `const net = BigInt(body.data.daily[0].net_supply_change)`），在 Python 中使用 `int(str)`。不会超过 `2^53` 的计数器（如 `transfers`、`unique_senders`、`unique_receivers`、`holder_count`、`top10_holder_share_bps`、`dex_swap_count`、`created_block`）为普通 JSON 数字。 * **二进制与十六进制值**：地址固定为 `0x` 加 40 位小写十六进制字符；哈希固定为 `0x` 加 64 位小写十六进制字符。所有返回的十六进制字段一律为全小写。 * **时间与日期**：时间戳字段（如 `refreshed_at`）采用 `YYYY-MM-DDTHH:MM:SSZ`（ISO-8601 UTC，秒级精度）；日聚合指标（`day`）采用纯 `YYYY-MM-DD` 日历日期。 ## 分页说明 [#分页说明] 股票端点不返回 `next_cursor`（该端点不支持分页；需要分页的其他 Data API 端点使用 `cursor` 回传 `next_cursor`）。`GET /{chain}/stocks` 使用 `limit` 参数限制单次返回的最大记录数（最多 500 条）；`GET /{chain}/stocks/{token}` 在 `daily` 数组中返回最近最多 30 天的历史日指标，按日期降序（最新在前）排列。 ## 用量估算（每天刷新 50 个代币） [#用量估算每天刷新-50-个代币] Data API 请求按 CU（计算单元）计量，各操作的 CU 权重由平台统一维护。下方用量测算以「50 个代币各调用一次 `GET /{chain}/stocks/{token}`」为场景，在构建时动态读取生效的权重数据并计算，正文不预设固定数值： ## 开启使用与升级 [#开启使用与升级] 免费额度适合开发探索与轻量运行。当你的业务规模增长、需要更高的并发调用或更多的计算单元时，只需在[控制台](https://console.blockvectra.com/zh/login/)完成充值，即可无缝升级至付费方案。充值后不再受免费套餐的每秒调用次数上限约束；每个 key 仍有 CU 速率与突发上限，见 [JSON-RPC 文档](/zh/api/json-rpc/#方法策略)。尚未用完的免费额度保留在服务额度中，可以继续使用。关于计费单位与当前价格，请参阅[定价页](https://blockvectra.com/zh/pricing/)。 ## 下一步 [#下一步] * [浏览数据集目录](https://blockvectra.com/zh/data/)，查看 BlockVectra 索引的全部数据集。 * [查看免费额度与定价](https://blockvectra.com/zh/pricing/#free)，确认账户可用的方案。 * [登录控制台](https://console.blockvectra.com/zh/login/?next=%2Fzh%2Fkeys%2F)创建 API key。