用途
Portal 用于跨 210+ 条链查询和链上数据分析，基于 SQD Portal Stream API。适用场景包括：查询区块链事件日志、交易、追踪、指令、Substrate 事件/调用或成交数据；查找某条链对应的 Portal 数据集名称；分析链上活动（代币转账、DeFi 事件、合约部署、交易）；使用 Portal MCP 工具或原始 Stream API。
主要能力
支持的数据类型及对应 type 字段：EVM 日志（"type": "evm"）、EVM 交易、EVM 追踪、Solana 指令（"type": "solana"）、Substrate 事件/调用/外部交易（"type": "substrate"）、Bitcoin 交易/输入/输出（"type": "bitcoin"）、Hyperliquid 成交（"type": "hyperliquidFills"）。
使用方式
第一步：查找正确的数据集名称。Portal 使用特定命名约定，与常见名称不同。常见错误如 ethereum 应为 ethereum-mainnet，arbitrum 应为 arbitrum-one，bsc 应为 binance-mainnet。可验证数据集名称：
curl -I https://portal.sqd.dev/datasets/{dataset-name}/metadata
# 200 = exists, 404 = wrong name
或使用 MCP 的 portal_list_networks 搜索。
第二步：选择数据类型，参考对应参考文件（EVM logs、transactions、traces，Solana，Substrate，Bitcoin，Hyperliquid）。
第三步：构造查询。所有查询使用同一端点模式：
POST https://portal.sqd.dev/datasets/{dataset-name}/stream
Content-Type: application/json
Accept: application/x-ndjson
最小查询模板：
{
"type": "<evm|solana|substrate|bitcoin|hyperliquidFills>",
"fromBlock": <start-block>,
"toBlock": <end-block>,
"<data-key>": [{ <filters> }],
"fields": {
"<field-key>": { <field-selection> }
}
}
时间范围处理：将 Unix 时间戳（秒）解析为不早于该时间的第一个区块：
GET https://portal.sqd.dev/datasets/{dataset}/timestamps/{unix-seconds}/block
→ {"block_number": 25043068}
适用于归档和实时数据。示例：
NOW=$(date +%s)
FROM=$(curl -s https://portal.sqd.dev/datasets/base-mainnet/timestamps/$((NOW - 4*3600))/block | jq -r .block_number)
TO=$(curl -s https://portal.sqd.dev/datasets/base-mainnet/head | jq -r .number)
不要用 (now - ts) / block_time 估算区块，区块时间会变化且结果会漂移数百个区块。
MCP 工具可优先于原始 API 调用。工具名称对应 Portal MCP server v0.7.8，早期版本使用无链族前缀的扁平命名（如 portal_query_logs → portal_evm_query_logs）。可用工具分组包括：发现与概览（portal_list_networks、portal_get_network_info、portal_get_head、portal_get_recent_activity、portal_debug_resolve_time_to_block、portal_debug_query_blocks）；EVM 查询（portal_evm_query_logs、portal_evm_query_transactions、portal_evm_query_token_transfers、portal_evm_get_contract_activity、portal_evm_get_contract_deployment、portal_evm_get_analytics、portal_evm_get_ohlc）；Solana 查询（portal_solana_query_instructions、portal_solana_query_transactions、portal_solana_get_analytics）；Substrate 查询（portal_substrate_query_events、portal_substrate_query_calls、portal_substrate_get_analytics）；Hyperliquid 查询（portal_hyperliquid_query_fills、portal_hyperliquid_get_analytics、portal_hyperliquid_get_ohlc）；Bitcoin 查询（portal_bitcoin_query_transactions、portal_bitcoin_get_analytics）；跨链分析（portal_get_wallet_summary、portal_get_time_series）。
响应格式为 JSON Lines（NDJSON），每行一个 JSON 对象，第一行总是区块头：
{"header":{"number":19500000,"hash":"0x...","parentHash":"0x...","timestamp":1234567890}}
{"logs":[...]}
{"transactions":[...]}
解析时按换行拆分，逐行解析 JSON。
常见错误
数据集名称错误：POST /datasets/ethereum/stream ❌，正确为 POST /datasets/ethereum-mainnet/stream ✅。
缺少 type 字段：每个查询必须包含 type。
数据集与 type 不匹配：EVM 链用 "type": "evm"；Solana 用 "type": "solana"；Substrate 链（Polkadot、Kusama、平行链）用 "type": "substrate"（不是 evm）；Bitcoin 用 "type": "bitcoin"；Hyperliquid 成交用 "type": "hyperliquidFills"；HyperEVM（hyperliquid-mainnet）用 "type": "evm"；Frontier 平行链（moonbeam-substrate）用 "type": "substrate"（使用 evmLogs 过滤器）。
查询过宽：如 {"fromBlock": 0, "logs": [{}]} ❌ 会产生数百万结果。应始终添加 address/topic/programId 过滤器和合理的区块范围。
性能建议
始终按 address/programId 过滤，可提速 10-100 倍；添加 topic0/sighash/discriminator 再提速 10 倍；探索时使用狭窄区块范围（100-10K 区块）；只请求需要的字段以减少响应体积；先用 MCP count/aggregate 工具概览再查询完整数据。
限制
Substrate 链不支持实时流式传输，仅有已最终确定的历史数据可用。时间戳解析端点对超出数据集头部的未来时间戳返回 404。