Blockchain SQL Query

Run a raw ClickHouse SELECT query against blockchain data.

All tables live in the agent database. Discover tables and columns first with GET /v1/onchain/schema.

Send a JSON object, not raw SQL text. Example: {"sql":"SELECT ...","max_rows":1000}.

Execution modes

• The default response is synchronous and has a 30s timeout.
• For queries that may exceed that window, send Prefer: respond-async. The same request is accepted as a durable job with 202 Accepted and Preference-Applied: respond-async.
• Send a stable Idempotency-Key with respond-async so equivalent client retries reuse the retained job.
• A synchronous timeout is non-retryable and returns recommended_action: use_async_job plus the async job URL. Do not resubmit the synchronous request automatically.
• Synchronous and asynchronous ClickHouse executions share one cluster-wide per-owner concurrency budget. Accepted async jobs remain queued while that owner's execution slots are occupied.

Rules

• Only SELECT/WITH statements allowed (read-only)
• All table references must be database-qualified: agent.<table_name>
• Max 10,000 rows (default 1,000), 30s timeout
• Always filter on block_date or block_number — partition key, without it queries will timeout
• Normalize address literals to lowercase and compare stored address columns directly. Wrapping address columns in lower() is rejected because it prevents key/index pruning.
• On transfer tables, do not combine from and to address predicates with OR. Use separate UNION ALL branches so each branch can use its address-ordered projection, and account for self-transfers when preserving counts.
• Never resolve token symbols here — symbol columns are unindexed (full scan) and symbol matches surface scam clones. Use GET /v1/search/token?q={symbol}&chain={chain} to get the contract address, then filter by contract_address
• For transfer tables, amount is decimal-adjusted display units; amount_raw is the original base-unit value
• Avoid SELECT * on large tables — specify only the columns you need
• Use single quotes for ClickHouse strings. Example: toDate('2026-04-07').

Data refresh: ~24 hours.

Example

{
  "sql": "SELECT block_time, token_pair, amount_usd, taker, tx_hash FROM agent.ethereum_dex_trades WHERE block_date >= today() - 7 AND project = 'uniswap' AND amount_usd > 100000 ORDER BY amount_usd DESC LIMIT 20",
  "max_rows": 1000
}

{
  "$schema": "https://example.com/schemas/HumaOnchainSQLInputBody.json",
  "max_rows": 1000,
  "sql": "SELECT block_date, project, symbol, apy, tvl_usd FROM agent.ethereum_yields_daily WHERE block_date >= today() - 7 ORDER BY apy DESC LIMIT 10"
}

{
  "$schema": "https://example.com/schemas/DataResponseOnchainRow.json"
}