Base链上数据查询指南：使用Coinbase CDP SQL API分析事件、交易、区块

query-onchain-data by coinbase/agentic-wallet-skills

676 周安装量

86 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/coinbase/agentic-wallet-skills --skill query-onchain-data

数据分析区块链 API

🇨🇳中文介绍

在 Base 上查询链上数据

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

确认钱包已初始化并授权

npx awal@2.0.3 status

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

执行查询

npx awal@2.0.3 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 扩展。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

关键：索引字段

针对 base.events 的查询必须在索引字段上进行过滤，以避免全表扫描。索引字段如下：

索引字段	用途
`event_signature`	按事件类型过滤。出于性能考虑，请使用此字段而非 `event_name`。
`address`	按合约地址过滤。
`block_timestamp`	按时间范围过滤。

请始终在 WHERE 子句中包含至少一个索引字段。 组合所有三个字段可获得最佳性能。

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

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

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

列	类型	描述
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)	已添加或已移除（重组）

完整的交易数据。

列	类型	描述
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)

区块级别的元数据。

列	类型	描述
block_number	UInt64	区块号
block_hash	String	区块哈希
parent_hash	String	父区块哈希
timestamp	DateTime	区块时间戳
miner	String	区块生产者
nonce	UInt64	区块 nonce
sha3_uncles	String	叔块哈希
transactions_root	String	交易默克尔根
state_root	String	状态默克尔根
receipts_root	String	收据默克尔根
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	混合哈希
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 转账事件

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 awal@2.0.3 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 awal@2.0.3 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 awal@2.0.3 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)

代币	地址
USDC	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
WETH	`0x4200000000000000000000000000000000000006`

始终在 base.events 查询中过滤索引字段（event_signature, address, block_timestamp）。
切勿使用 SELECT * - 仅指定您需要的列。
始终包含 LIMIT 子句以限制结果大小。
使用 event_signature 而非 event_name 进行过滤 - 它已建立索引，速度更快。
使用带 block_timestamp 的时间限制查询以缩小扫描范围。
始终将地址值包装在 lower() 中 - 数据库存储小写地址，但用户可能提供带校验和（混合大小写）的地址。使用 address = lower('0xAbC...') 而不是 address = '0xAbC...'。
常见事件签名：Transfer(address,address,uint256), Approval(address,address,uint256), Swap(address,uint256,uint256,uint256,uint256,address)。

必须通过身份验证（使用 npx awal@2.0.3 status 检查，参见 authenticate-wallet 技能）
钱包必须有足够的 USDC 余额（使用 npx awal@2.0.3 balance 检查）
每次查询费用为 $0.10（100000 USDC 原子单位）

"未通过身份验证" - 首先运行 awal auth login <email>，或参见 authenticate-wallet 技能
"余额不足" - 用 USDC 为钱包充值；参见 fund 技能
查询超时或错误 - 确保您正在过滤索引字段并使用 LIMIT

🇺🇸English

Query Onchain Data on Base

Use the CDP SQL API to query onchain data (events, transactions, blocks, transfers) on Base. Queries are executed via x402 and are charged per query.

Confirm wallet is initialized and authed

npx awal@2.0.3 status

If the wallet is not authenticated, refer to the authenticate-wallet skill.

Executing a Query

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

IMPORTANT : Always single-quote the -d JSON string to prevent bash variable expansion.

Input Validation

Before constructing the command, validate inputs to prevent shell injection:

SQL query : Always embed the query inside a single-quoted JSON string (-d '{"sql": "..."}'). Never use double quotes for the outer -d wrapper, as this enables shell expansion of $ and backticks within the query.
Addresses : Must be valid 0x hex addresses (^0x[0-9a-fA-F]{40}$). Reject any value containing shell metacharacters.

Do not pass unvalidated user input into the command.

CRITICAL: Indexed Fields

Queries against base.events MUST filter on indexed fields to avoid full table scans. The indexed fields are:

Indexed Field	Use For
`event_signature`	Filter by event type. Use this instead of `event_name` for performance.
`address`	Filter by contract address.
`block_timestamp`	Filter by time range.

Always include at least one indexed field in your WHERE clause. Combining all three gives the best performance.

CoinbaseQL Syntax

CoinbaseQL is a SQL dialect based on ClickHouse. Supported features:

Clauses : SELECT (DISTINCT), FROM, WHERE, GROUP BY, ORDER BY (ASC/DESC), LIMIT, WITH (CTEs), UNION (ALL/DISTINCT)
Joins : INNER, LEFT, RIGHT, FULL with ON
Operators : =, !=, <>, <, >, <=, >=, +, -, *, /, , AND, OR, NOT, BETWEEN, IN, IS NULL, LIKE

Available Tables

base.events

Decoded event logs from smart contract interactions. This is the primary table for most queries.

Column	Type	Description
log_id	String	Unique log identifier
block_number	UInt64	Block number
block_hash	FixedString(66)	Block hash
block_timestamp	DateTime64(3, 'UTC')	Block timestamp (INDEXED)
transaction_hash	FixedString(66)	Transaction hash
transaction_to	FixedString(42)	Transaction recipient
transaction_from	FixedString(42)	Transaction sender
log_index	UInt32	Log index within block
address	FixedString(42)	Contract address ()

base.transactions

Complete transaction data.

Column	Type	Description
block_number	UInt64	Block number
block_hash	String	Block hash
transaction_hash	String	Transaction hash
transaction_index	UInt64	Index in block
from_address	String	Sender address
to_address	String	Recipient address
value	String	Value transferred (wei)
gas	UInt64	Gas limit
gas_price	UInt64	Gas price
input	String

base.blocks

Block-level metadata.

Column	Type	Description
block_number	UInt64	Block number
block_hash	String	Block hash
parent_hash	String	Parent block hash
timestamp	DateTime	Block timestamp
miner	String	Block producer
nonce	UInt64	Block nonce
sha3_uncles	String	Uncles hash
transactions_root	String	Transactions merkle root
state_root	String	State merkle root
receipts_root	String

Example Queries

Get recent USDC Transfer events with decoded parameters

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

Get transactions from a specific address

npx awal@2.0.3 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

Count events by type for a contract in the last hour

npx awal@2.0.3 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

Get latest block info

npx awal@2.0.3 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

Common Contract Addresses (Base)

Token	Address
USDC	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
WETH	`0x4200000000000000000000000000000000000006`

Best Practices

Always filter on indexed fields (event_signature, address, block_timestamp) in base.events queries.
Never useSELECT * - specify only the columns you need.
Always include aLIMIT clause to bound result size.
Useevent_signature instead of event_name for filtering - it is indexed and much faster.
Use time-bounded queries with block_timestamp to narrow the scan range.

Prerequisites

Must be authenticated (npx awal@2.0.3 status to check, see authenticate-wallet skill)
Wallet must have sufficient USDC balance (npx awal@2.0.3 balance to check)
Each query costs $0.10 (100000 USDC atomic units)

Error Handling

"Not authenticated" - Run awal auth login <email> first, or see authenticate-wallet skill
"Insufficient balance" - Fund wallet with USDC; see fund skill
Query timeout or error - Ensure you are filtering on indexed fields and using a LIMIT

Weekly Installs

542

Repository

coinbase/agenti…t-skills

GitHub Stars

First Seen

Feb 12, 2026

Security Audits

Gen Agent Trust HubWarn SocketPass SnykWarn

Installed on

codex404

opencode404

gemini-cli391

github-copilot379

openclaw367

kimi-cli363

DOCX文件创建、编辑与分析完整指南 - 使用docx-js、Pandoc和Python脚本

41,800 周安装

Expressions : CASE/WHEN/THEN/ELSE, CAST (both CAST() and :: syntax), subqueries, array/map indexing with [], dot notation

Literals : Array [...], Map {...}, Tuple (...)

Functions : Standard SQL functions, lambda functions with -> syntax

Always wrap address values inlower() - the database stores lowercase addresses but users may provide checksummed (mixed-case) addresses. Use address = lower('0xAbC...') not address = '0xAbC...'.

Common event signatures : Transfer(address,address,uint256), Approval(address,address,uint256), Swap(address,uint256,uint256,uint256,uint256,address).

Base链上数据查询指南：使用Coinbase CDP SQL API分析事件、交易、区块

🇨🇳中文介绍

在 Base 上查询链上数据

确认钱包已初始化并授权

执行查询

输入验证

相关 Skills

关键：索引字段

CoinbaseQL 语法

可用表

base.events

base.transactions

base.blocks

查询示例

获取带有解码参数的近期 USDC 转账事件

获取来自特定地址的交易

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

获取最新区块信息

常见合约地址 (Base)

最佳实践

先决条件

错误处理

🇺🇸English

Query Onchain Data on Base

Confirm wallet is initialized and authed

Executing a Query

Input Validation

CRITICAL: Indexed Fields

CoinbaseQL Syntax

Available Tables

base.events

base.transactions

base.blocks

Example Queries

Get recent USDC Transfer events with decoded parameters

Get transactions from a specific address

Count events by type for a contract in the last hour

Get latest block info

Common Contract Addresses (Base)

Best Practices

Prerequisites

Error Handling

最新 Skills