SQL Query

POST/gateway/v1/onchain/sql

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}`.

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 - 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

```json { "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 } ```

Query Parameters

$schemastring

A URL to the JSON Schema for this object.

Example: https://example.com/schemas/HumaOnchainSQLInputBody.json

max_rowsinteger

Maximum number of rows to return

Example: 1000

sqlstringrequired

Send a JSON object with the sql field. Example: {"sql":"SELECT 1"}. Use GET /v1/onchain/schema for tables and columns. Transfer table amount is decimal-adjusted; amount_raw is the original base-unit value. Use single quotes for ClickHouse strings. Example: toDate('2026-04-07').

Example:

SELECT block_date, project, symbol, apy, tvl_usd FROM agent.ethereum_yields_daily WHERE block_date >= today() - 7 ORDER BY apy DESC LIMIT 10

SQL Query

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "$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"
})
};

fetch('https://api.asksurf.ai/gateway/v1/onchain/sql', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/DataResponseOnchainRow.json",
  "data": [],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "offset": 123,
    "total": 123,
    "watermark": 123
  }
}