Skip to content

Onchain SQL (query Base with SQL)

$0.03 per callUSDC via x402POST /api/onchain-sql

Run read-only SQL against indexed, DECODED blockchain data - base.events (decoded logs with parameters), base.transactions, base.blocks, base.decoded_user_operations, base.transaction_attributions (builder codes), plus solana.instructions (filter it by block_time). Send POST /api/onchain-sql with the required field sql and pay $0.03 per call over x402 or MPP (there is no free tier). It returns a JSON object with rows, rowCount, maxRows, returned, matched and 2 more.

ClickHouse-dialect SELECTs, server-side grammar validation, up to 1,000 rows per call (a larger result is cut at 1,000 and says so). Ask Base anything - token flows, event analytics, gas studies - in one call, no indexer to run.

Category: Wallet operationsTags: wallet onboarding x402 agent-wallet sql analytics onchain-data base

Try in playground →

Parameters

NameTypeRequiredDescription
sqlstringyesRead-only SELECT (ClickHouse dialect, max 60,000 chars). Tables: base.events, base.transactions, base.blocks, base.encoded_logs, base.decoded_user_operations, base.transaction_attributions, base_sepolia.*, solana.instructions (a query that filters, groups or aggregates it needs a block_time range; a day answers in seconds, and a longer range may read past the query service's 100 GB per-query limit). Returns up to 1,000 rows; a larger result is cut and marked truncated. A result the query service cannot send is served in part and says so: rows over its 64 KB per-row limit are omitted and counted (recovered "row-size", rowsOmitted, omittedReason, rowLimitBytes, maxRowBytes, note), and a result too large as a whole is re-run with LIMIT 10 (recovered "result-size", rowBytes, a note with the LIMIT that fits).
cacheSecondsnumbernoAccept cached results up to this old (max 900). Cheaper + faster for repeated analytics.

Example request

curl -i -X POST https://agent402.tools/api/onchain-sql \
  -H "Content-Type: application/json" \
  -d '{"sql":"SELECT COUNT(*) AS txs FROM base.transactions WHERE block_number > 0 LIMIT 1"}'

Without payment this returns HTTP 402 Payment Required with the exact price for onchain-sql; any x402 v2 or MPP client pays it and retries.

Example response

{
  "rows": [
    {
      "txs": 123456
    }
  ],
  "rowCount": 1,
  "maxRows": 1000,
  "returned": 1,
  "matched": 1,
  "complete": true,
  "truncated": false
}
FieldTypeAlways presentIn the example
rowsarray of objectsyes1 item in the example
rowCountnumberyes1
maxRowsnumberyes1000
returnednumberyes1
matchednumberyes1
completebooleanyestrue
truncatedbooleanyesfalse

From an MCP client

catalog.call {
  "slug": "onchain-sql",
  "params": {
    "sql": "SELECT COUNT(*) AS txs FROM base.transactions WHERE block_number > 0 LIMIT 1"
  }
}

The hosted connector at https://agent402.tools/mcp needs a payment for onchain-sql; the stdio package pays it from a wallet or from an AGENT402_CREDITS_KEY issued earlier. Local install: npx -y agent402-mcp@0.13.32.

Errors and behavior

Paid call (JavaScript agent)

import { wrapFetchWithPayment } from "@x402/fetch";
import { x402Client } from "@x402/core/client";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const client = new x402Client();
client.setSpendControls?.({ maxAmountPerPayment: "$0.03" }); // refuse any quote above this tool's price
registerExactEvmScheme(client, { signer: privateKeyToAccount(KEY) });
const payFetch = wrapFetchWithPayment(fetch, client);

const res = await payFetch("https://agent402.tools/api/onchain-sql", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    "sql": "SELECT COUNT(*) AS txs FROM base.transactions WHERE block_number > 0 LIMIT 1"
  }),
});

Part of these workflows

Onchain SQL (query Base with SQL) is one step in this skill pack, each sold as a single call:

Related tools

Onchain SQL schema

$0.002GET /api/onchain-sql-schema

The table + column schema for the onchain-sql tool - every queryable table (base.events, base.transactions, base.blocks.

Wallet token balances (indexed)

$0.002GET /api/wallet-balances

All token balances for any address in one call, from an indexed chain-data API - ERC-20 + native on EVM, SPL on Solana.

Onramp link (fund a wallet with a card)

$0.001POST /api/onramp-link

Generate a single-use hosted onramp URL that lets a human fund any wallet with a card or Apple Pay - the fastest way.

Testnet faucet (try x402 free)

$0.001POST /api/testnet-fund

Fund any address with testnet money from a testnet faucet - USDC (1) or ETH (0.0001) on Base Sepolia, USDC (1) or SOL.

Wallet token transfers (filtered)

$0.003POST /api/asset-transfers

Recent token transfers for a wallet on Base, Ethereum and other EVM chains, newest first.

Attest a settled call on Base

$0.05POST /api/attest

Write an on-chain attestation (Ethereum Attestation Service on Base) that binds a call you paid for to the bytes you.