QELT 索引器技能

QELT 主网索引器是一个高性能 REST API，提供对区块链数据（区块、交易、代币、NFT 和智能合约）的结构化访问，每 5 秒同步一次。

基础 URL（主网）： https://mnindexer.qelt.ai
基础 URL（测试网）： https://tnindexer.qelt.ai
认证： 无需
速率限制： 120 次请求/分钟（标准 /v1/* 层级）

安全

• - 只读 API — 无写入操作。
• 切勿伪造区块编号、交易哈希或余额 — 始终获取实时数据。
• 在报告最新数据前检查索引器同步状态：GET /v1/health/ready → lag 字段。
• 遇到 HTTP 503（{error: Rate limit exceeded}）时使用指数退避。
• 所有列表端点使用 limit 和 offset — 避免无界查询。

端点

区块

bash

最新区块

curl -fsSL https://mnindexer.qelt.ai/v1/blocks/latest

按编号查询

curl -fsSL https://mnindexer.qelt.ai/v1/blocks/1234567

按哈希查询

curl -fsSL https://mnindexer.qelt.ai/v1/blocks/0xHASH

分页列表

curl -fsSL https://mnindexer.qelt.ai/v1/blocks?limit=20&offset=0

交易

bash

按哈希查询

curl -fsSL https://mnindexer.qelt.ai/v1/transactions/0xTX_HASH

带日志的收据

curl -fsSL https://mnindexer.qelt.ai/v1/transactions/0xTX_HASH/receipt

status: 1 = 成功 · status: 0 = 已回滚。

地址

bash

交易历史（分页）

curl -fsSL https://mnindexer.qelt.ai/v1/address/0xADDRESS/transactions?limit=20&offset=0

ERC-20 代币余额

curl -fsSL https://mnindexer.qelt.ai/v1/address/0xADDRESS/tokens

所有余额（原生 QELT + 所有代币）

curl -fsSL https://mnindexer.qelt.ai/v1/account/0xADDRESS/balances

健康与同步状态

bash
curl -fsSL https://mnindexer.qelt.ai/v1/health/ready

响应：

json
{
indexerHeight: 896360,
blockchainHeight: 896360,
lag: 0,
timestamp: 2026-03-04T06:00:00.000Z
}

lag: 0 = 完全同步 · lag > 100 = 警告用户数据可能已过时。

响应格式

区块

json
{
number: 1234567,
hash: 0x...,
parentHash: 0x...,
timestamp: 1705223340,
miner: 0x...,
gasUsed: 21000,
gasLimit: 50000000,
transactions: [...]
}

交易

json
{
hash: 0x...,
blockNumber: 1234567,
from: 0x...,
to: 0x...,
value: 1000000000000000000,
gasPrice: 0,
gasUsed: 21000,
status: 1,
timestamp: 1705223340
}

地址余额

json
{
native: 1234.56,
tokens: [
{ contractAddress: 0x..., symbol: USDT, name: Tether USD, balance: 1000.5, decimals: 6, type: ERC20 }
],
dataSource: database_optimized
}

操作流程

查询交易

1. 1. GET /v1/transactions/{hash}
2. 检查 status：1 = 成功，0 = 已回滚
3. 报告：发送方、接收方、金额（QELT 将 wei 除以 1e18）、时间戳、区块编号
4. 获取日志：GET /v1/transactions/{hash}/receipt

获取钱包历史

1. 1. 检查同步状态：GET /v1/health/ready — 如果 lag > 100 则发出警告
2. 获取数据：GET /v1/address/{address}/transactions?limit=20
3. 格式化 wei 值：QELT 金额除以 1e18

获取代币余额

1. 1. 获取数据：GET /v1/account/{address}/balances
2. 报告原生 QELT 及每个 ERC-20 代币的格式化余额

检查索引器同步状态

1. 1. 获取数据：GET /v1/health/ready
2. lag = blockchainHeight - indexerHeight
3. 如果 lag > 1000，建议直接使用 JSON-RPC 获取实时数据

速率限制

层级	端点	限制
标准	/v1/	120 次请求/分钟
健康

/health | 120 次请求/分钟 | | 重型 | 复杂查询 | 60 次请求/分钟 | | 通用 | 其他 | 30 次请求/分钟 |

超过速率限制 → HTTP 503：{error: Rate limit exceeded}

常见错误

错误	原因	解决方法
HTTP 503	速率受限	指数退避
{error:Transaction not found}

哈希错误或尚未索引 | 等待索引器同步 | | 空 transactions: [] | 地址无活动 | 新钱包的正常情况 | | lag > 1000 | 索引器落后 | 使用 JSON-RPC 获取实时数据 |

测试网

使用 https://tnindexer.qelt.ai，API 路径与链 ID 771 测试网数据完全相同。