---
title: "On-Chain Table Schema"
method: GET
path: "/gateway/v1/onchain/schema"
tags: ["Onchain"]
---

# On-Chain Table Schema

`GET /gateway/v1/onchain/schema`

Discover tables and columns before writing SQL or structured queries. Example: call this endpoint first, then use `agent.ethereum_dex_trades` in `/v1/onchain/query` or `/v1/onchain/sql`.

The response includes database name, table name, column names, types, and comments. Pass the optional `table` parameter to include bounded physical source metadata: engine, partition key, sorting key, primary key, row estimate, and compressed bytes.

For transfer tables, `amount` is decimal-adjusted display units and `amount_raw` is the original base-unit value.

## Query parameters

- `table` string — Optional logical table name from the agent database. Use this to include bounded physical partition, ordering-key, and size metadata.

## Response `200`

OK

- DataResponseOnchainSchemaTable
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `data` OnchainSchemaTable[], nullable, required
    - `columns` OnchainSchemaCol[], nullable, required — List of columns in this table
      - `comment` string — Column comment or description
      - `name` string, required — Column name
      - `type` string, required — Column data type like `UInt64`, `String`, or `DateTime`
    - `database` string, required — Database name (always `agent`)
    - `engine` string — Logical table engine, commonly View
    - `partition_key` string — Logical table PARTITION BY expression when applicable
    - `physical_sources` OnchainPhysicalTable[], nullable — Bounded physical source metadata for a selected logical view
      - `database` string, required — Physical ClickHouse database
      - `engine` string, required — Physical ClickHouse table engine
      - `partition_key` string — Physical PARTITION BY expression
      - `primary_key` string — Physical primary-key expression
      - `sorting_key` string — Physical ORDER BY expression
      - `table` string, required — Physical ClickHouse table
      - `total_bytes` integer — Current compressed bytes from system.tables
      - `total_rows` integer — Current physical row estimate from system.tables
    - `primary_key` string — Logical table primary-key expression when applicable
    - `sorting_key` string — Logical table ORDER BY expression when applicable
    - `table` string, required — Logical table name
    - `total_bytes` integer — Logical table compressed bytes when available
    - `total_rows` integer — Logical table row estimate when available
  - `meta` OffsetMeta, required
    - `cached` boolean, required — Whether this response was served from cache
    - `credits_used` integer, required — Credits deducted for this request
    - `empty_reason` string — Hint explaining why the data array is empty, when applicable
    - `has_more` boolean — Whether more items may exist beyond this response. For offset-paged endpoints, continue with a larger offset. For time-series endpoints without offset/cursor controls, true means the requested time range hit an upstream cap; narrow from/to to continue. Omitted when exhaustion cannot be proven.
    - `limit` integer, required — Maximum number of items returned in this response
    - `offset` integer, required — Number of items skipped (pagination offset)
    - `total` integer — Total number of matching items (before pagination). Omitted when total is unknown.
    - `watermark` integer — Warehouse watermark (Unix seconds) this response was computed at, on warehouse-backed endpoints (e.g. Hyperliquid /trades/aggregate) — rows up to this time come from the warehouse, newer rows from the live tail. Omitted elsewhere.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api.md) · [All operations](https://skmtc.dev/asksurf/apis/asksurf-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asksurf/asksurf-public-rest-api/revisions/4153a9cb5145/schema)