Structured Query

POST/gateway/v1/onchain/query

Send a JSON object describing the query. Example: `{"source":"agent.ethereum_dex_trades","fields":["block_time"],"filters":[{"field":"block_date","op":"gte","value":"2025-03-01"}],"limit":1}`.

Use this endpoint when you want structured filtering without writing raw SQL. Discover tables and columns first with `GET /v1/onchain/schema`.

Key rules: - Source format: `agent.<table_name>` - Max 10,000 rows (default 20), 30s timeout - Always filter on `block_date` for large tables - Never filter by `symbol` — it is unindexed (full scan). To resolve a ticker to a contract address, use `GET /v1/search/token?q={symbol}&chain={chain}` and filter by `contract_address` instead - For transfer tables, `amount` is decimal-adjusted display units; `amount_raw` is the original base-unit value

Data refresh: ~24 hours.

Example

```json { "source": "agent.ethereum_dex_trades", "fields": ["block_time", "project", "token_pair", "amount_usd", "taker"], "filters": [ {"field": "block_date", "op": "gte", "value": "2025-03-01"}, {"field": "project", "op": "eq", "value": "uniswap"}, {"field": "amount_usd", "op": "gte", "value": 100000} ], "sort": [{"field": "amount_usd", "order": "desc"}], "limit": 20 } ```

Query Parameters

$schemastring

A URL to the JSON Schema for this object.

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

fieldsstring[]

Columns to return. Omit to return all columns.

Example: ["project","symbol","apy","tvl_usd"]

filtersobject[]

WHERE conditions (ANDed together)

limitinteger

Max rows to return. Default 20, max 10000

Example: 20

offsetinteger

Rows to skip for pagination. Default 0

Example: 0

sortobject[]

ORDER BY clauses

sourcestringrequired

Fully-qualified table name like `agent.ethereum_yields_daily`. Use GET /v1/onchain/schema for available tables.

Example: agent.ethereum_yields_daily

Structured Query

const options = {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
  "$schema": "https://example.com/schemas/StructuredQuery.json",
  "fields": [
    "project",
    "symbol",
    "apy",
    "tvl_usd"
  ],
  "limit": 20,
  "offset": 0,
  "source": "agent.ethereum_yields_daily"
})
};

fetch('https://api.asksurf.ai/gateway/v1/onchain/query', 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
  }
}