# agent402.tools Onchain SQL

> agent402.tools Onchain SQL is a paid API for AI agents from agent402.tools, paid per call via x402, $0.02/call, status healthy (last checked 2026-09-14, last successful call 2026-08-28).

Run read-only ClickHouse SQL queries against decoded, indexed blockchain data for Base, Base Sepolia, Solana, and HyperEVM networks

## Facts

- Endpoint: POST https://agent402.tools/api/onchain-sql
- Price: $0.02/call
- Payment: x402
- Status: healthy
- Last checked: 2026-09-14
- Last successful call: 2026-08-28
- Success rate: 100% of calls made through Zero
- Activations on Zero: 2
- Tags: x402
- Canonical page: https://www.zero.xyz/c/agent402-tools-onchain-sql-5c983a9b
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_S6lJirBZM_-n6ADJZIL0z

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability agent402-tools-onchain-sql-5c983a9b -d '<json body>'
```

Example prompt: Can you query the Base blockchain for the top 10 contracts by number of decoded events in the last 1000 blocks? Run a SELECT against base.events grouped by contract address, and cache results for 300 seconds to save cost.

## When to prefer this

Use this endpoint when you need to run arbitrary analytical SQL against decoded, indexed Base, Solana, or HyperEVM blockchain data — especially when you need decoded event parameters rather than raw hex logs, or when you want to aggregate and filter onchain activity with full SQL expressiveness. Prefer this over block explorer APIs when you need joins, aggregations, or custom WHERE clauses across millions of rows.

## Known failure modes

- Invalid SQL syntax returns a parse or execution error
- Queries exceeding 10,000 characters are rejected
- Non-SELECT statements (INSERT, UPDATE, DROP) are rejected as read-only enforcement
- Referencing tables outside the allowed schema returns an unknown table error
- Cache miss on cold query may take longer than expected
- Payment failure via x402 returns 402 with payment details
- Query result set too large may be truncated or timeout

## How this service works

Run read-only SQL against Coinbase's 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 and hyperevm.events. ClickHouse-dialect SELECTs, server-side grammar validation, up to 50k rows / 30s / 12 joins. Ask Base anything - token flows, event analytics, gas studies - in one call, no indexer to run.

## Output

Returns rows matching the SQL query from Coinbase's indexed decoded blockchain tables — including decoded log parameters, transaction hashes, block numbers, addresses, and other onchain fields depending on which tables are queried.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "sql": {
   "type": "string",
   "description": "Read-only SELECT (ClickHouse dialect, max 10,000 chars). Tables: base.events, base.transactions, base.blocks, base.encoded_logs, base.decoded_user_operations, base.transaction_attributions, base_sepolia.*, solana.instructions, hyperevm.events"
  },
  "cacheSeconds": {
   "type": "number",
   "description": "Accept cached results up to this old (max 900). Cheaper + faster for repeated analytics."
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "rows": [
   {
    "txs": 123456
   }
  ],
  "rowCount": 1
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/agent402-tools-onchain-sql-5c983a9b/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from agent402.tools](https://www.zero.xyz/host/agent402.tools/llms.txt)