Interroger des données onchain sur Base

Utilisez l'API CDP SQL pour interroger des données onchain (événements, transactions, blocs, transferts) sur Base. Les requêtes sont exécutées via x402 et facturées par requête.

Confirmer que le portefeuille est initialisé et authentifié

npx awal@2.8.2 status

Si le portefeuille n'est pas authentifié, consultez la skill authenticate-wallet.

Exécuter une requête

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

IMPORTANT : Toujours utiliser des guillemets simples autour de la chaîne JSON -d pour éviter l'expansion des variables bash.

Validation des entrées

Avant de construire la commande, validez les entrées pour prévenir l'injection shell :

• Requête SQL : Toujours intégrer la requête dans une chaîne JSON entre guillemets simples (-d '{"sql": "..."}'). Ne jamais utiliser de guillemets doubles pour le wrapper -d extérieur, car cela permet l'expansion shell de $ et des backticks dans la requête.
• Adresses : Doivent être des adresses hexadécimales 0x valides (^0x[0-9a-fA-F]{40}$). Rejeter toute valeur contenant des métacaractères shell.

Ne pas transmettre d'entrée utilisateur non validée à la commande.

CRITIQUE : Champs indexés

Les requêtes contre base.events DOIVENT filtrer sur des champs indexés pour éviter les analyses complètes de table. Les champs indexés sont :

Toujours inclure au moins un champ indexé dans votre clause WHERE. Combiner les trois offre les meilleures performances.

Syntaxe CoinbaseQL

CoinbaseQL est un dialecte SQL basé sur ClickHouse. Fonctionnalités supportées :

• Clauses : SELECT (DISTINCT), FROM, WHERE, GROUP BY, ORDER BY (ASC/DESC), LIMIT, WITH (CTEs), UNION (ALL/DISTINCT)
• Joins : INNER, LEFT, RIGHT, FULL avec ON
• Opérateurs : =, !=, <>, <, >, <=, >=, +, -, *, /, %, AND, OR, NOT, BETWEEN, IN, IS NULL, LIKE
• Expressions : CASE/WHEN/THEN/ELSE, CAST (syntaxe CAST() et :: toutes deux), subqueries, indexation array/map avec [], dot notation
• Littéraux : Array [...], Map {...}, Tuple (...)
• Fonctions : Fonctions SQL standard, fonctions lambda avec syntaxe ->

Tables disponibles

base.events

Logs d'événements décodés depuis les interactions de contrats intelligents. Ceci est la table principale pour la plupart des requêtes.

base.transactions

Données complètes de transaction.

base.blocks

Métadonnées au niveau du bloc.

Exemples de requêtes

Obtenir les événements Transfer USDC récents avec paramètres décodés

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

Obtenir les transactions d'une adresse spécifique

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

Compter les événements par type pour un contrat au cours de la dernière heure

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

Obtenir les informations du bloc le plus récent

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

Adresses de contrats courants (Base)

Bonnes pratiques

1. Toujours filtrer sur des champs indexés (event_signature, address, block_timestamp) dans les requêtes base.events.
2. *Ne jamais utiliser `SELECT `** - spécifier uniquement les colonnes nécessaires.
3. Toujours inclure une clause LIMIT pour limiter la taille des résultats.
4. Utiliser event_signature au lieu de event_name pour le filtrage - elle est indexée et beaucoup plus rapide.
5. Utiliser des requêtes limitées dans le temps avec block_timestamp pour réduire l'étendue de l'analyse.
6. Toujours envelopper les valeurs d'adresses dans lower() - la base de données stocke les adresses en minuscules mais les utilisateurs peuvent fournir des adresses avec checksum (casse mixte). Utiliser address = lower('0xAbC...') et non address = '0xAbC...'.
7. Signatures d'événements courantes : Transfer(address,address,uint256), Approval(address,address,uint256), Swap(address,uint256,uint256,uint256,uint256,address).

Prérequis

• Doit être authentifié (npx awal@2.8.2 status pour vérifier, voir skill authenticate-wallet)
• Le portefeuille doit avoir un solde suffisant en USDC (npx awal@2.8.2 balance pour vérifier)
• Chaque requête coûte $0,10 (100 000 unités atomiques USDC)

Gestion des erreurs

• « Not authenticated » - Exécuter awal auth login <email> en premier, ou voir skill authenticate-wallet
• « Insufficient balance » - Approvisionner le portefeuille avec USDC ; voir skill fund
• Timeout ou erreur de requête - Vérifier que vous filtrez sur des champs indexés et utilisez un LIMIT