Skip to main content

​
Overview

Explorer tools allow your AI agents to query Allium’s historical blockchain data using SQL queries. These tools provide access to raw and decoded data across 80+ blockchains.

​
Available Tools

Tool NameDescription
explorer_create_queryCreate a new saved query programmatically. Returns a query_id for future use
explorer_update_queryUpdate an existing saved query’s SQL, parameters, or configuration
explorer_run_queryRun a saved Explorer query using its query_id. Supports parameterization
explorer_run_sqlRun raw SQL directly against Allium’s production datasets
explorer_search_schemasSemantic search across all schema docs. Returns relevant table IDs
explorer_browse_schemasBrowse data schema hierarchy like a filesystem to discover databases, schemas, tables
explorer_fetch_schemaFetch YAML schema metadata by table IDs (full table name, e.g. ethereum.raw.blocks)
Schema IDs match full table names (e.g. ethereum.raw.token_transfers). Use search before fetching.

​
Tool Usage

​
Create & Manage Queries

​
Create a New Query

Save a query programmatically for later reuse: 
{
  "name": "explorer_create_query",
  "arguments": {
    "title": "Ethereum Transactions by Date",
    "sql": "SELECT * FROM ethereum.raw.transactions WHERE block_timestamp > {{start_date}} LIMIT {{limit}}",
    "limit": 1000,
    "parameters": {
      "start_date": "2024-01-01",
      "limit": "1000"
    }
  }
}
Returns: 
{
  "query_id": "abc123..."
}
Save this query_id to run or update the query later.

​
Update an Existing Query

Modify a saved query’s SQL or configuration: 
{
  "name": "explorer_update_query",
  "arguments": {
    "query_id": "abc123...",
    "title": "Ethereum Transactions by Date (Updated)",
    "sql": "SELECT block_number, hash, value FROM ethereum.raw.transactions WHERE block_timestamp > {{start_date}}",
    "limit": 5000
  }
}
Common use cases:
  • Optimize SQL for better performance
  • Adjust row limits
  • Update parameter defaults
  • Change compute profiles

​
Run Saved Queries

Execute queries created in the Allium App or via explorer_create_query.
1

Get a Query ID

Create a query using explorer_create_query or save one in the Allium App to obtain its query_id.
2

Call the Tool

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "explorer_run_query",
    "arguments": {
      "query_id": "<YOUR_QUERY_ID>"
      // "parameters": { "param": "value" } // optional
    }
  }
}
Response includes:
  • sql - Full query text
  • data - Result rows
  • meta.columns - Column names and types
  • queried_at - Execution timestamp

​
Run Raw SQL

Execute ad-hoc SQL queries directly: 
{
  "name": "explorer_run_sql",
  "arguments": {
    "sql": "SELECT COUNT(*) FROM ethereum.raw.transactions"
  }
}
Supports up to 250,000 rows per query by default.

​
Explore Schemas

Find relevant tables using semantic search:
{
  "name": "explorer_search_schemas",
  "arguments": {
    "query": "erc20 token transfers"
  }
}
Returns:
["ethereum.raw.token_transfers", "ethereum.unified.transfers", ...]

​
Response Format

All Explorer query tools return a JSON-RPC result: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": {
      "text": "{\"sql\": \"SELECT ...\", \"data\": [...], \"meta\": {\"columns\": [...]}, \"queried_at\": \"2025-07-01T00:00:00Z\"}"
    }
  }
}
Parse content.text as JSON to extract:
  • sql - Full query string
  • data - List of result rows (objects)
  • meta.columns - Each column’s name and data type
  • queried_at - ISO timestamp

Create Query API

REST endpoint for creating queries

Update Query API

REST endpoint for updating queries

Run Queries

Learn how to save queries in Explorer

Data Catalog

Explore available data schemas

Explorer API

REST endpoints for running queries