query-onchain-data

查询 Base 上的链上数据

使用 CDP SQL API 查询 Base 上的链上数据（事件、交易、区块、转账）。查询通过 x402 执行，并按查询次数收费。

确认钱包已初始化并完成身份验证

npx [email protected] status

如果钱包尚未通过身份验证，请参阅 authenticate-wallet 技能。

执行查询

npx [email protected] x402 pay https://x402.cdp.coinbase.com/platform/v2/data/query/run -X POST -d '{"sql": "<YOUR_QUERY>"}' --json

重要：始终使用单引号括起 -d JSON 字符串，以防止 bash 展开变量。

输入验证

在构造命令前，请验证输入以防止 shell 注入：

• SQL 查询：始终将查询放在单引号括起的 JSON 字符串中（-d '{"sql": "..."}'）。外层 -d 封装不要使用双引号，否则查询中的 $ 和反引号会触发 shell 展开。
• 地址：必须是有效的 0x 十六进制地址（^0x[0-9a-fA-F]{40}$）。拒绝包含任何 shell 元字符的值。

不要将未经验证的用户输入传入命令。

严重：索引字段

查询 base.events 时，必须按索引字段进行筛选，以避免全表扫描。索引字段包括：

索引字段	用途
event_signature	按事件类型筛选。为提升性能，请使用此字段，而非 event_name。
address	按合约地址筛选。
block_timestamp	按时间范围筛选。

WHERE 子句中始终至少包含一个索引字段。 同时使用这三个字段可获得最佳性能。

CoinbaseQL 语法

CoinbaseQL 是一种基于 ClickHouse 的 SQL 方言。支持的功能：

• 子句：SELECT (DISTINCT)、FROM、WHERE、GROUP BY、ORDER BY (ASC/DESC)、LIMIT、WITH（CTE）、UNION (ALL/DISTINCT)
• 连接：INNER、LEFT、RIGHT、FULL（带 ON）
• 运算符：=、!=、<>、<、>、<=、>=、+、-、*、/、%、AND、OR、NOT、BETWEEN、IN、IS NULL、LIKE
• 表达式：CASE/WHEN/THEN/ELSE、CAST（支持 CAST() 和 :: 语法）、子查询、使用 [] 的数组/映射索引、点表示法
• 字面量：数组 [...]、映射 {...}、元组 (...)
• 函数：标准 SQL 函数、使用 -> 语法的 lambda 函数

可用表

base.events

智能合约交互的已解码事件日志。这是大多数查询的主要数据表。

列	类型	描述
log_id	String	唯一日志标识符
block_number	UInt64	区块编号
block_hash	FixedString(66)	区块哈希
block_timestamp	DateTime64(3, 'UTC')	区块时间戳（已索引）
transaction_hash	FixedString(66)	交易哈希
transaction_to	FixedString(42)	交易接收方
transaction_from	FixedString(42)	交易发送方
log_index	UInt32	区块内的日志索引
address	FixedString(42)	合约地址（已索引）
topics	Array(FixedString(66))	事件主题
event_name	LowCardinality(String)	已解码的事件名称
event_signature	LowCardinality(String)	事件签名（已索引——优先于 event_name 使用）
parameters	Map(String, Variant(Bool, Int256, String, UInt256))	已解码的事件参数
parameter_types	Map(String, String)	参数的 ABI 类型
action	Enum8('removed' = -1, 'added' = 1)	已添加或已移除（链重组）

base.transactions

完整的交易数据。

Column	Type	Description
block_number	UInt64	区块编号
block_hash	String	区块哈希
transaction_hash	String	交易哈希
transaction_index	UInt64	区块内的索引
from_address	String	发送方地址
to_address	String	接收方地址
value	String	转账金额（wei）
gas	UInt64	Gas 上限
gas_price	UInt64	Gas 价格
input	String	输入数据
nonce	UInt64	发送方 nonce
type	UInt64	交易类型
max_fee_per_gas	UInt64	EIP-1559 最高费用
max_priority_fee_per_gas	UInt64	EIP-1559 优先费用
chain_id	UInt64	链 ID
v	String	签名 v
r	String	签名 r
s	String	签名 s
is_system_tx	Bool	系统交易标记
max_fee_per_blob_gas	String	Blob Gas 费用
blob_versioned_hashes	Array(String)	Blob 哈希
timestamp	DateTime	区块时间戳
action	Int8	已添加（1）或已移除（-1）

base.blocks

区块级元数据。

Column	Type	Description
block_number	UInt64	区块编号
block_hash	String	区块哈希
parent_hash	String	父区块哈希
timestamp	DateTime	区块时间戳
miner	String	区块生产者
nonce	UInt64	区块 nonce
sha3_uncles	String	叔块哈希
transactions_root	String	交易 Merkle 根
state_root	String	状态 Merkle 根
receipts_root	String	收据 Merkle 根
logs_bloom	String	布隆过滤器
gas_limit	UInt64	区块 Gas 上限
gas_used	UInt64	区块已用 Gas
base_fee_per_gas	UInt64	每 Gas 基础费用
total_difficulty	String	链的总难度
size	UInt64	区块大小（字节）
extra_data	String	附加数据字段
mix_hash	String	Mix 哈希
withdrawals_root	String	提款根
parent_beacon_block_root	String	信标链父根
blob_gas_used	UInt64	已用 Blob Gas
excess_blob_gas	UInt64	超额 Blob Gas
transaction_count	UInt64	交易数量
action	Int8	已添加（1）或已移除（-1）

示例查询

获取近期的 USDC Transfer 事件及其解码参数

SELECT
  parameters['from'] AS sender,
  parameters['to'] AS to,
  parameters['value'] AS amount,
  address AS token_address
FROM base.events
WHERE
  event_signature = 'Transfer(address,address,uint256)'
  AND address = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913'
  AND block_timestamp >= now() - INTERVAL 7 DAY
LIMIT 10

获取来自特定地址的交易

npx [email protected] x402 pay https://x402.cdp.coinbase.com/platform/v2/data/query/run -X POST -d '{"sql": "SELECT transaction_hash, to_address, value, gas, timestamp FROM base.transactions WHERE from_address = lower('\''0xYOUR_ADDRESS'\'') AND timestamp >= now() - INTERVAL 1 DAY LIMIT 10"}' --json

统计过去一小时内某合约的各类型事件数量

npx [email protected] x402 pay https://x402.cdp.coinbase.com/platform/v2/data/query/run -X POST -d '{"sql": "SELECT event_signature, count(*) as cnt FROM base.events WHERE address = lower('\''0xCONTRACT_ADDRESS'\'') AND block_timestamp >= now() - INTERVAL 1 HOUR GROUP BY event_signature ORDER BY cnt DESC LIMIT 20"}' --json

获取最新区块信息

npx [email protected] x402 pay https://x402.cdp.coinbase.com/platform/v2/data/query/run -X POST -d '{"sql": "SELECT block_number, timestamp, transaction_count, gas_used FROM base.blocks ORDER BY block_number DESC LIMIT 1"}' --json

常见合约地址（Base）

Token	Address
USDC	0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
WETH	0x4200000000000000000000000000000000000006

最佳实践

1. 在 base.events 查询中，始终使用索引字段（event_signature、address、block_timestamp）进行筛选。
2. 切勿使用 SELECT *——仅指定所需的列。
3. 始终添加 LIMIT 子句以限制结果集大小。
4. 筛选时使用 event_signature 而非 event_name——前者有索引，速度快得多。
5. 使用基于 block_timestamp 的时间范围查询缩小扫描范围。
6. 始终用 lower() 包裹地址值——数据库存储的是小写地址，但用户可能提供带校验和的混合大小写地址。使用 address = lower('0xAbC...')，而不是 address = '0xAbC...'。
7. 常见事件签名：Transfer(address,address,uint256)、Approval(address,address,uint256)、Swap(address,uint256,uint256,uint256,uint256,address)。

前提条件

• 必须完成身份验证（运行 npx [email protected] status 检查，参见 authenticate-wallet skill）
• 钱包必须有足够的 USDC 余额（运行 npx [email protected] balance 检查）
• 每次查询费用为 $0.10（100000 USDC 原子单位）

错误处理

• “Not authenticated”——先运行 awal auth login <email>，或参见 authenticate-wallet skill
• “Insufficient balance”——为钱包充值 USDC；参见 fund skill
• 查询超时或出错——确保筛选时使用索引字段并添加 LIMIT