Query Onchain Data
Run paid SQL queries against Base onchain data (blocks, transactions, events) through Coinbase CDP and x402 via the awal CLI.
Overview
Query Onchain Data is an agent skill for the Build phase that runs SQL against Base onchain datasets through the CDP API, paying per query with awal x402.
Install
npx skills add https://github.com/coinbase/agentic-wallet-skills --skill query-onchain-dataWhat is this skill?
- Queries Base onchain data via CDP SQL API with x402 per-query billing
- Uses npx awal@2.10.0 status, balance, and x402 pay with POST JSON body
- Mandates single-quoted -d '{"sql": "..."}' to avoid bash expansion of $ and backticks
- Validates 0x hex addresses (^0x[0-9a-fA-F]{40}$) and rejects shell metacharacters in inputs
- Points to authenticate-wallet when awal status shows wallet not authenticated
- Pinned awal CLI: npx awal@2.10.0
Adoption & trust: 2.1k installs on skills.sh; 110 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You need trustworthy Base chain facts (transfers, events, blocks) inside an agent workflow but do not want to operate your own node or indexer.
Who is it for?
Builders already on Base with awal who want quick SQL-shaped onchain answers inside Claude Code or similar agents.
Skip if: Multi-chain analytics without CDP coverage, users without wallet auth, or workflows that cannot accept per-query x402 charges.
When should I use this skill?
User or agent wants to view onchain information about decoded blocks, transactions, and events on Base using the CDP SQL API via x402.
What do I get? / Deliverables
Authenticated awal wallet executes a validated SQL query and returns JSON onchain results after x402 payment—ready to feed UI, logs, or downstream agent reasoning.
- JSON query result from CDP data/run endpoint
- Documented awal x402 pay command
Recommended Skills
Journey fit
How it compares
An integration skill for CDP SQL + x402, not a self-hosted BigQuery-style warehouse or generic REST MCP.
Common Questions / FAQ
Who is query-onchain-data for?
Solo builders and agent authors integrating Coinbase wallet tooling who need SQL access to Base onchain tables.
When should I use query-onchain-data?
During Build when wiring onchain lookups, debugging contract activity, or prototyping agent tools that need blocks, transactions, or decoded events on Base.
Is query-onchain-data safe to install?
It invokes bash, network, and payment commands; review the Security Audits panel on this page and never pass unvalidated SQL or addresses into the shell.
Workflow Chain
Requires first: authenticate wallet
SKILL.md
READMESKILL.md - Query Onchain Data
# 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 ```bash npx awal@2.10.0 status ``` If the wallet is not authenticated, refer to the `authenticate-wallet` skill. ## Executing a Query ```bash npx awal@2.10.0 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 - **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 ## 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 (**INDEXED**) | | topics | Array(FixedString(66)) | Event topics | | event_name | LowCardinality(String) | Decoded event name | | event_signature | LowCardinality(String) | Event signature (**INDEXED** - prefer over event_name) | | parameters | Map(String, Variant(Bool, Int256, String, UInt256)) | Decoded event parameters | | parameter_types | Map(String, String) | ABI types for parameters | | action | Enum8('removed' = -1, 'added' = 1) | Added or removed (reorg) | ### base.transactions Complete transaction data. | Column | Type | Description | | --- | --- | --- | | block_number | UInt64 | Block number | | block_hash | String | Block hash | | transaction_hash | String | Transaction hash | | transa