用 Data API 查代币化股票的每日链上指标
了解如何通过 Data API 查询代币化股票的每日链上活跃榜单与单个代币历史指标，掌握字段含义、编码约定、分页规则与用量估算。
数据来自链上公开记录，仅供参考，不构成投资建议。
什么是代币化股票数据集
BlockVectra Data API 提供代币化股票（Tokenized Stocks）每日链上指标与元数据查询。该数据集汇总每日转账、铸造、销毁、净供应量变化、持币分布以及去中心化交易所（DEX）交易等指标，帮助开发者跟踪代币化股票在链上的公开动态。
提供该数据集的链以支持的链页面为准。
- 基础 URL：
https://dev-api.blockvectra.network/v1/data——除GET /chains外，所有 Data API 路由均以链标识为前缀（如https://dev-api.blockvectra.network/v1/data/{chain}/…） - 链标识示例：
robinhood_mainnet（本文仅以此作为路径参数示例；提供该数据集的具体链请参阅支持的链页面） - 身份验证：在 HTTP 请求头中传入
x-api-key: <your_api_key> - 计费与数据覆盖：按 CU（计算单元）透明计量，仅对 2xx 成功响应计费。若请求的链不支持股票数据集，接口返回 HTTP
422 no_coverage（不计费）
查每日榜单（GET /{chain}/stocks）
GET /{chain}/stocks 端点提供指定 UTC 日期的代币化股票每日活跃榜单，包含展示元数据（代号、名称等），默认按链上转账活跃度降序（最活跃的代币排在最前）。
请求参数
{chain}（路径参数，必填）：目标链的标识（例如robinhood_mainnet）。day（查询参数，可选）：UTC 日期，格式为YYYY-MM-DD。若省略，默认返回最新有记录的日期（若该日无活动记录，返回200且data: []）。若传入但不是合法的YYYY-MM-DD日历日期，返回 HTTP400（error.code = "bad_request"）。limit（查询参数，可选）：当前响应最多返回条数。默认值为 50；超过 500 的值会被截断为 500；传入0或非整数会返回 HTTP400（error.code = "bad_request"）。
分页特性
该端点不支持分页。limit 参数用于限制当前响应返回的最大条数。响应外层的 StockDailyListEnvelope 包含 data 与 meta，其中股票端点不返回 next_cursor（该键在响应中完全不出现，而非 null）。
代码示例
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"响应结构说明
响应外层为 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 /{chain}/stocks/{token} 端点根据代币合约地址，查询该代币化股票的基础元数据以及最近最多 30 天的历史每日指标。
请求参数
{chain}（路径参数，必填）：目标链的标识（例如robinhood_mainnet）。{token}（路径参数，必填）：20 字节代币合约地址，0x可省略，大小写均可（返回地址规范化为0x开头的 40 位小写十六进制字符）。若地址格式不合法，返回 HTTP400（error.code = "bad_request"）。- 若请求的
{token}不是已知的代币化股票，返回 HTTP404（error.code = "not_found"）。若{chain}是未知链，返回 HTTP404（error.code = "unknown_chain"）。
代码示例
curl -s "https://dev-api.blockvectra.network/v1/data/robinhood_mainnet/stocks/0x1111111111111111111111111111111111111111" \
-H "x-api-key: $BLOCKVECTRA_API_KEY"响应结构说明
响应外层为 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）
每日榜单与单个代币历史指标均包含以下核心日指标字段：
| 字段 | 类型 | 说明 |
|---|---|---|
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）
查询单个代币时，外层 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 个代币）
Data API 请求按 CU（计算单元）计量，各操作的 CU 权重由平台统一维护。下方用量测算以「50 个代币各调用一次 GET /{chain}/stocks/{token}」为场景，在构建时动态读取生效的权重数据并计算，正文不预设固定数值：
- 单次调用计费权重：每次调用
data.stock消耗 15 CU（标价每百万次 $1.5）。 - 每天刷新 50 个代币指标（各调用一次
GET /{chain}/stocks/{token}，每天 50 次调用）：单日消耗 750 CU；一个 30 天周期累计调用 1,500 次，消耗 22,500 CU，占免费额度（3,000 万 CU）的 0.07%。 超出免费额度或在付费方案下，全量用量按标价约每月 $0.00225。
开启使用与升级
免费额度适合开发探索与轻量运行。当你的业务规模增长、需要更高的并发调用或更多的计算单元时，只需在控制台完成充值，即可无缝升级至付费方案。充值后不再受免费套餐的每秒调用次数上限约束；每个 key 仍有 CU 速率与突发上限，见 JSON-RPC 文档。尚未用完的免费额度保留在服务额度中，可以继续使用。关于计费单位与当前价格，请参阅定价页。