Onchain SQL (query Base with SQL)
POST /api/onchain-sqlRun 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.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sql | string | yes | Read-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). |
cacheSeconds | number | no | Accept 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
}| Field | Type | Always present | In the example |
|---|---|---|---|
rows | array of objects | yes | 1 item in the example |
rowCount | number | yes | 1 |
maxRows | number | yes | 1000 |
returned | number | yes | 1 |
matched | number | yes | 1 |
complete | boolean | yes | true |
truncated | boolean | yes | false |
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
sqlis required. An input the tool rejects returns an HTTP 4xx whose body carrieserror,tool,expected,requiredandexample, so the caller can correct it.- A paid call that ends in any status of 400 or above is not charged over x402, MPP or a prepaid credits key: settlement runs after the tool and only on a successful response. The exception is a Tempo push credential, a transfer the buyer sent before the call: it settles before the tool runs, so if the tool then fails the payment is recorded as a refund owed to the paying wallet.
- Wallet-only: this tool reaches the network or stored state, so it has no proof-of-work tier. A prepaid card-credits key issued earlier (
Authorization: Bearer a402_...) also pays it. - A
GETorHEADto /api/onchain-sql returns the same 402 quote, so the price can be read without a body. - An
Idempotency-Keyheader makes a retried paid call replay the first 200 instead of charging again (an answer larger than 1 MB is not replayed).
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:
- Onchain analyst (SQL over Base) - Ask Base anything in one paid call: your SQL runs against indexed, DECODED chain data (events with parsed parameters, transactions, blocks, user-ops) with the live schema alongside - no indexer, no RPC archaeology.
Related tools
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)
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)
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)
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)
Recent token transfers for a wallet on Base, Ethereum and other EVM chains, newest first.
Attest a settled call on Base
Write an on-chain attestation (Ethereum Attestation Service on Base) that binds a call you paid for to the bytes you.