节点状态
区块、交易、回执、日志、余额和合约调用。
区块链数据架构
免费链上数据 API 选择指南
根据问题选择节点状态、索引实体、市场背景或派生信号，避免把不同层的数据混在一起。
四类链上数据不能混为一谈
索引实体
解析后的转账、标签、协议仓位和实体历史。
市场背景
资产价格、流动性、成交量和交易所元数据。
派生信号
资金流、用户分组、风险评分、实现指标和预警条件。
先定义区块链数据 API 的输出
钱包余额与交易历史
钱包余额接口应说明原生资产、同质化代币、NFT、待确认交易、垃圾资产过滤、法币估值、区块高度和源时间戳。交易历史还应说明内部交易、调用轨迹、手续费、状态、分页与解码标签。
代币转账、持币地址与合约事件
代币与智能合约数据接口需要稳定的合约地址、精度、事件签名、日志索引、交易哈希与链 ID。持币地址和资产组合通常来自索引或衍生计算，并非节点直接响应。
历史与实时链上数据
历史链上数据需要明确归档深度、确定性时间边界、回填分页与修订处理。实时链上数据可通过轮询、Webhook、WebSocket 或流式接口获取，应记录确认策略和重复事件处理。
派生链上指标需要实体标签与明确公式
活跃地址、新增地址、交易所流入、已实现价值、持币集中度和盈利供应量都属于分析指标，并非链上原始字段。结果会受到地址聚类、找零地址识别、合约与跨链桥过滤、交易所标签覆盖、价格来源、时间边界和确认策略影响。每条观测都应保存指标定义、网络、区块范围、标签集版本、价格版本和计算版本。一个地址不一定对应一个用户，一笔代币转账也不一定代表一笔独立经济流。
交易所资金流案例：内部调拨不是充值或提现
交易所资金流案例：内部调拨不是充值或提现
假设某个 UTC 自然日内，外部实体向已标记交易所地址集合转入 100 BTC，交易所向外部实体转出 70 BTC，且这些交易都已达到规定确认数。按照已声明公式，交易所净流入为 100 − 70 = +30 BTC。同一天，交易所又把 500 BTC 从已标记的热钱包调拨到一个尚未标记的新冷钱包。若标签集还不知道该冷钱包属于同一家交易所，按地址计算的简单方法会额外记录 500 BTC 流出，使当日结果变成 100 − (70 + 500) = −470 BTC。当两个钱包都被识别为同一交易所实体后，这笔内部调拨对外部净流量的贡献应为零，结果才恢复为 +30 BTC。
新增标签后不能静默改写旧序列。系统应保留首次可得结果，在新的标签集版本下发布更正值，并披露修订时间和原因。同时要说明跨链桥合约、托管机构、综合钱包、矿池、混币器、代币铸造与销毁、失败交易和被重组区块是否计入。用于告警时，应等待规定确认数并支持可逆更正；用于历史研究时，则应查询研究截止时点真正可获得的指标版本。
REST API
适合查询地址余额、交易详情或分页转账历史等请求—响应场景。
GraphQL API
适合从已索引的多链数据模型中选择字段并关联实体。
JSON-RPC
提供链原生方法，但通常需要自行完成解码、索引、批处理、归档访问与重组处理。
WebSocket 与 Webhook
用于近实时事件；应核验投递保证、重试签名、顺序、确认深度与重连行为。
最小查询契约
| 字段 | 为什么重要 | 拒绝条件 |
|---|---|---|
| chain_id | 避免同一地址跨链歧义 | 缺失，或仅靠页面推断 |
| 区块 / 时间 | 让结果可以复现 | 只返回“最新”而没有锚点 |
| 地址 + 类型 | 区分钱包、代币与合约 | 校验格式或代币身份不清楚 |
| 确认策略 | 控制链重组风险 | 未确认与已确认数据混在一起 |
| 来源信息 | 说明解析和补充数据从哪里来 | 派生字段没有来源 |
按问题选择数据源
需要链上原始状态？
从节点或归档节点开始，并保留区块高度和 chain ID。
需要解析后的历史？
使用索引服务，同时记录解析规则和链重组处理方式。
需要协议分析？
使用 Subgraph 或专业数据集，并固定 Schema 版本。
需要估值？
先稳定代币身份和时间点，再连接市场价格数据。
选择正确的链上数据来源模型
“链上数据 API”包含多种取舍不同的产品。原始节点方法、已索引的地址历史接口、已解码事件 API 和分析数据集，可能用不同方式描述同一笔交易。因此应先选择数据来源模型，再比较服务商。
| 来源模型 | 主要输出 | 适合场景 | 仍需自行处理 |
|---|---|---|---|
| JSON-RPC | 区块、回执、日志、状态 | 链原生控制 | 解码、索引、链重组 |
| 索引型 REST | 钱包与交易历史 | 钱包、税务、资产组合应用 | 服务商 Schema 映射 |
| GraphQL | 选定实体与关联关系 | 自定义索引查询 | 查询成本与分页 |
| 流 / Webhook | 新区块、转账与事件 | 告警与实时自动化 | 顺序、去重与重放 |
原始数据与解码数据
原始日志保留协议级细节，但需要 ABI 和链特定逻辑。解码后的 API 接入更快，不过其标签、代币元数据、垃圾资产规则与协议分类也会成为应用的数据依赖。
索引数据与节点实时状态
索引适合高效回答历史与跨实体问题，但可能落后于链尖。节点状态更接近网络，适合核验；深度历史则可能需要归档节点和大量调用。
供应商角色
| 供应商 | 角色 | 适合用途 |
|---|---|---|
| Ethereum JSON-RPC | 协议原生接口 | 区块、交易、回执和日志 |
| Coinbase Data | 托管区块链数据 | 应用接入与标准化传输 |
| The Graph | 可查询的索引 Schema | 协议实体与历史记录 |
| QVeris 中的 CoinGecko | 加密资产市场背景 | 价格和资产市场覆盖 |
正确理解免费区块链 API 的限制
“免费 API”可能指无需鉴权的公共端点、每月自动重置的额度、促销积分或限时试用，它们不能混为一谈。测试当天应记录条款，不要围绕无法保证续期的额度设计生产依赖。
请求计费方式
确认配额按 HTTP 请求、返回记录、计算单元还是链特定积分扣减；批量调用可能使用不同权重。
速率与并发
记录每秒请求、突发窗口、并发流、Webhook 投递限制、429 响应头和额度重置行为。
数据访问范围
检查归档深度、支持网络、付费专属解码字段、最大页大小、批量导出与数据保留。
使用权利
核验展示、缓存、存储、署名、再分发、商业使用与衍生数据条件。
免费访问不等于 SLA。足够原型使用的额度，并不代表可用性、支持、变更通知或恢复保证。
如何接入免费区块链数据接口
1. 编写数据契约
选择端点前先明确链、实体、字段、时间范围、最终性、最大陈旧时间、分页和允许的空结果。
2. 运行代表性请求
测试有余额钱包、空钱包、代币合约、失败交易、长历史、最新区块与不支持的网络。
3. 标准化并验证
保留原始响应，对字段映射进行版本管理，验证地址和数值单位，并分别保存源时间与采集时间。
4. 添加配额感知控制
Key 保存在服务端，按新鲜度缓存，对 429 单独处理，限制重试并加入抖动，监控配额并准备回退。
定义最低标准化响应
{
"chainId": "eip155:1",
"blockNumber": 00000000,
"transactionHash": "0x…",
"timestamp": "ISO-8601",
"asset": {"address": "0x…", "decimals": 18},
"valueRaw": "0",
"status": "confirmed",
"sourceRetrievedAt": "ISO-8601"
}应保留原始整数值，避免直接接受浮点转换，并保存服务商响应样本用于排错。把服务商特有字段放在标准化核心之外，避免切换数据源时静默改变产品行为。
实算示例：先解码、再唯一识别、最后确认
一条代币转账的原始整数为 123456789，合约精度为 6，实际数量就是 123456789 ÷ 10⁶ = 123.456789 枚。应把原始整数以字符串保存，再用十进制安全算法生成展示数量；代币元数据发生变化或程序使用二进制浮点数，都不能改写来源事件。日志的唯一键应由 chain ID + transaction hash + log index 组成，不能只使用交易哈希，因为一笔交易可能触发多条转账日志。
确认状态会变化，首次看到事件时并不代表它已经永久成立。应保存区块高度与区块哈希、交易和日志索引、首次观察时间、供应商入库时间、确认数及最终性策略。如果事件最初出现在高度 N、区块哈希为 A，随后链重组使同一高度的哈希 B 成为主链，就应把 A 中的事件标记为已移除或已回滚，并以幂等方式处理主链替代事件，不能让两条记录同时进入余额或告警。所需确认深度取决于网络与业务场景，应明确展示 pending、confirmed、finalized 和 reverted 状态，而不是把首次观测写成不可逆事实。
上线前检查
- 用已知交易和已知合约事件做基准测试。
- 模拟短链重组或索引延迟。
- 应用标签前先保存原始标识符。
- 区分供应商时间戳与区块时间戳。
生产使用前测试链上数据 API
建立代表性验收数据集
- 一个有余额地址和一个无历史地址。
- 成功交易、失败交易、内部调用与代币转账。
- 发生过代理升级或包含多个事件版本的合约。
- 必然触发分页的长历史范围。
- 最新区块，以及刻意使用的不支持链或错误地址。
验证正确性与一致性
用区块浏览器或链原生 RPC 交叉核验关键样本。重复相同请求，检查标识不稳定、记录缺失、分页变化或时间戳不一致。条件允许时，应在已知链重组附近测试，或等待更多确认后再次比较。
规划监控、回填与故障回退
监控源延迟、采集延迟、空值激增、区块缺口、Schema 漂移、配额消耗、429 与服务错误。回填应按链、区块、交易和日志索引保持幂等。故障回退还需要明确的对账规则，因为两个服务商可能以不同方式标准化同一事件。
把任务路由到正确的数据角色
可以用 QVeris 发现能力，但必须明确区分链原生数据与市场数据的职责。 可继续打开CoinGecko 服务商详情，并通过QVeris REST API 参考核对调用契约。
免费链上数据 API 常见问题
有免费的链上数据 API 吗？
有。部分服务提供公共端点、试用或长期免费层，可查询余额、交易、转账、区块、合约与索引数据，但限制和使用权不同。
如何通过 API 获取链上数据？
可选择链原生 JSON-RPC，或已索引的 REST、GraphQL、WebSocket 与 Webhook 接口，再测试覆盖、配额、新鲜度与错误。
免费区块链 API 哪个好？
应按所需网络、数据类型、历史范围、更新速度、配额、许可与运维要求选择，不存在适合所有场景的唯一答案。
一个 API 能查询多条公链吗？
部分多链数据 API 使用统一 Schema 覆盖多条网络；仍需逐链核验特有字段和功能缺口。
免费链上 API 需要 API Key 吗？
部分公共端点不需要，很多免费层会用 Key 做配额和滥用控制。不要在浏览器代码中暴露高权限 Key。
免费接口可以用于生产环境吗？
只有许可、容量、可用性、变更策略、监控和回退满足应用风险要求时才适合。