Base上のオンチェーンデータをクエリする

CDP SQL APIを使用してBase上のオンチェーンデータ(イベント、トランザクション、ブロック、転送)をクエリします。クエリはx402経由で実行され、クエリごとに課金されます。

ウォレットが初期化され、認証されていることを確認

npx awal@2.10.0 status

ウォレットが認証されていない場合は、authenticate-wallet スキルを参照してください。

クエリを実行

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

重要: Bash変数の展開を防ぐため、常に-d JSON文字列を単一引用符で囲んでください。

入力検証

コマンドを構築する前に、シェルインジェクションを防ぐために入力を検証してください:

• SQLクエリ: クエリを常に単一引用符で囲まれたJSON文字列内に埋め込んでください (-d '{"sql": "..."}')。-d ラッパーの外側に二重引用符を使用しないでください。二重引用符を使用するとクエリ内の$とバッククォートのシェル展開が有効になります。
• アドレス: 有効な0x16進アドレス (^0x[0-9a-fA-F]{40}$) である必要があります。シェルメタ文字を含む値は拒否してください。

検証されていないユーザー入力をコマンドに渡さないでください。

重要: インデックス付きフィールド

base.eventsに対するクエリは、フルテーブルスキャンを避けるため、インデックス付きフィールドでフィルタする必須です。インデックス付きフィールドは:

インデックス付きフィールド	用途
event_signature	イベントタイプでフィルタします。パフォーマンスのためevent_nameの代わりにこれを使用してください。
address	コントラクトアドレスでフィルタします。
block_timestamp	時間範囲でフィルタします。

WHERE句に少なくとも1つのインデックス付きフィールドを常に含めてください。 3つすべてを組み合わせると最高のパフォーマンスが得られます。

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関数、->構文を使用したラムダ関数

利用可能なテーブル

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

完全なトランザクションデータ。

カラム	型	説明
block_number	UInt64	ブロック番号
block_hash	String	ブロックハッシュ
transaction_hash	String	トランザクションハッシュ
transaction_index	UInt64	ブロック内のインデックス
from_address	String	送信者アドレス
to_address	String	受信者アドレス
value	String	転送値(Wei)
gas	UInt64	ガスリミット
gas_price	UInt64	ガス価格
input	String	入力データ
nonce	UInt64	送信者ノンス
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ガス手数料
blob_versioned_hashes	Array(String)	Blobハッシュ
timestamp	DateTime	ブロックタイムスタンプ
action	Int8	追加(1)または削除(-1)

base.blocks

ブロックレベルのメタデータ。

カラム	型	説明
block_number	UInt64	ブロック番号
block_hash	String	ブロックハッシュ
parent_hash	String	親ブロックハッシュ
timestamp	DateTime	ブロックタイムスタンプ
miner	String	ブロックプロデューサー
nonce	UInt64	ブロックノンス
sha3_uncles	String	アンクルハッシュ
transactions_root	String	トランザクションマークルルート
state_root	String	状態マークルルート
receipts_root	String	レシートマークルルート
logs_bloom	String	ブルームフィルター
gas_limit	UInt64	ブロックガスリミット
gas_used	UInt64	ブロック内で使用されたガス
base_fee_per_gas	UInt64	ガス当たりのベース手数料
total_difficulty	String	チェーン総難易度
size	UInt64	ブロックサイズ(バイト)
extra_data	String	エクストラデータフィールド
mix_hash	String	ミックスハッシュ
withdrawals_root	String	引き出しルート
parent_beacon_block_root	String	ビーコンチェーン親ルート
blob_gas_used	UInt64	使用されたBlob ガス
excess_blob_gas	UInt64	余剰Blob ガス
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 awal@2.10.0 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

過去1時間のコントラクトのイベントタイプ別カウント

npx awal@2.10.0 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.10.0 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

ベストプラクティス

1. 常にインデックス付きフィールド (event_signature、address、block_timestamp)でbase.eventsクエリをフィルタしてください。
2. SELECT *を使用しないでください - 必要なカラムのみを指定してください。
3. 常にLIMIT句を含めてください - 結果サイズを制限するため。
4. フィルタリングにはevent_nameの代わりにevent_signatureを使用してください - インデックス付きで、はるかに高速です。
5. block_timestampを使用した時間制限クエリを使用してください - スキャン範囲を縮小するため。
6. アドレス値を常にlower()で囲んでください - データベースは小文字のアドレスを保存していますが、ユーザーはチェックサム(大文字小文字混合)アドレスを提供する場合があります。address = '0xAbC...'ではなくaddress = lower('0xAbC...')を使用してください。
7. 一般的なイベント署名: Transfer(address,address,uint256)、Approval(address,address,uint256)、Swap(address,uint256,uint256,uint256,uint256,address)。

前提条件

• 認証される必要があります (npx awal@2.10.0 statusで確認、authenticate-walletスキルを参照)
• ウォレットは十分なUSDCバランスを持つ必要があります (npx awal@2.10.0 balanceで確認)
• 各クエリのコストは$0.10(100000 USDCアトミック単位)

エラーハンドリング

• "Not authenticated" - まずawal auth login <email>を実行してください。または、authenticate-walletスキルを参照
• "Insufficient balance" - USDCでウォレットを資金提供してください。fundスキルを参照
• クエリタイムアウトまたはエラー - インデックス付きフィールドでフィルタし、LIMITを使用していることを確認してください