Custom On-Chain SQL Query (ClickHouse, Read-Only)

{
  "type": "object",
  "required": [
    "sql"
  ],
  "properties": {
    "sql": {
      "type": "string",
      "minLength": 1,
      "description": "Read-only ClickHouse SELECT/WITH query. Discover tables with /onchain/schema. Rules (server-enforced or query-killing): SELECT/WITH only (read-only); table references must be database-qualified as agent.<table>; ALWAYS filter on block_date or block_number (partition key — without it the query times out); compare address columns directly against lowercase literals (wrapping the column in lower() is rejected); never filter on symbol columns (unindexed full scan, and symbol matches surface scam clones — resolve a ticker to a contract address with /search/token first); on transfer tables use separate UNION ALL branches instead of OR across from/to; use single quotes for strings, e.g. toDate('2026-04-07'). Example: SELECT block_date, sum(amount_usd) FROM agent.ethereum_dex_trades WHERE block_date >= today() - 7 GROUP BY block_date."
    },
    "max_rows": {
      "type": "integer",
      "default": 1000,
      "maximum": 10000,
      "minimum": 1,
      "description": "Maximum rows to return. Example: 100. Defaults to 1000 (server-side), capped at 10000."
    }
  },
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Present only when the query is rejected instead of executed (e.g. a non-SELECT query caught by the read-only guard). Observed as 'HTTP_400' on the one real rejected query."
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "trades": {
            "type": "number",
            "description": "Row count for the day, when the query aliases its count() column as `trades`. Only present when the SELECT list computes it."
          },
          "block_date": {
            "type": "number",
            "description": "Unix seconds for the day bucket, observed when the query groups by a block_date column. Only present when the SELECT list includes it."
          },
          "volume_usd": {
            "type": [
              "number",
              "null"
            ],
            "description": "Summed USD volume for the day, when the query aliases its sum() column as `volume_usd`. Only present when the SELECT list computes it. Null for the current, still-incomplete day when no priced trades have settled yet."
          }
        },
        "additionalProperties": true
      },
      "description": "Result rows. Only observed with one real query (a daily Ethereum DEX trade-count and volume aggregation) -- a different SELECT list returns different column names entirely; the fields below describe that one observed shape, not a fixed schema."
    },
    "meta": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "number",
          "description": "Effective row limit applied, echoing max_rows."
        },
        "total": {
          "type": "number",
          "description": "Total row count for the query."
        },
        "cached": {
          "type": "boolean"
        },
        "offset": {
          "type": "number"
        }
      },
      "additionalProperties": true
    },
    "message": {
      "type": "string",
      "description": "Human-readable rejection reason, present only alongside `code`."
    }
  },
  "description": "The query's result rows, or an error object when the query is rejected instead of executed.",
  "additionalProperties": true
}