Text2SQL API

Convert natural language queries to SQL queries and execute them, returning query results. Supports both streaming and non-streaming response modes.

POST/agent/api/v2/text2sql

Request Parameters

Parameter	Type	Required	Description
query	string	Yes	Natural language query to convert to SQL, like 'Show me the top 10 token trades by volume today'
stream	boolean	No	Whether to return streaming response Default: true

AI SQL Generation

The system automatically analyzes your natural language query and generates corresponding SQL statements:

• Data Filtering - Filter data based on conditions
• Aggregation - Statistics, sum, average and other calculations
• Time Range - Date and time period filtering
• Sorting & Grouping - Data sorting and grouping operations
• Multi-table Joins - Cross-table data queries

Response Format

Standard Response (stream: false)

{
  "data": {
    "sql": "SELECT ...",
    "rows": [
      {"token": "ABC", "volume": 12345},
      {"token": "XYZ", "volume": 67890}
    ]
  }
}

Streaming Response (stream: true)

SSE Streaming Events - Each event is sent as a single line with Server-Sent Events format:

Recommended Usage with curl

curl -N -H "Content-Type: application/json" \
     -H "HUBBLE-API-KEY: <YOUR_KEY>" \
     https://api.hubble-rpc.xyz/agent/api/v2/text2sql \
     -d '{"query":"Show me the top 10 token trades by volume today","stream":true}'

Response Format

Each streaming event follows this structure:

data: {"id":"...","phase":"plan","status":"end","message":"plan phase completed","duration":285,"timestamp":"2025-08-21T05:09:29.825Z","plan":["[Query] Get the top 10 token trades by volume from the DEX table for today with time filter and LIMIT 10."]}

data: {"id":"...","phase":"sql_generation","status":"start","message":"sql_generation phase started","timestamp":"2025-08-21T05:09:29.826Z"}

data: {"id":"...","phase":"sql_generation","status":"end","message":"sql_generation phase completed","duration":2666,"timestamp":"2025-08-21T05:09:32.492Z","rowCount":10}

data: {"id":"...","phase":"data_display","status":"start","message":"data_display phase started","timestamp":"2025-08-21T05:09:32.492Z"}

Event Types (Streaming)

Event Name	Description	Commonly Used
token	LLM real-time generated tokens (streaming output content)	✅ Common
result	Final query result	✅ Common
complete	Entire process completed	✅ Common
error	Error occurred	✅ Common

Recommendation for developers: Focus mainly on token, result, complete, and error events.

Responses

200stream: false

Success (stream: false)

{
  "id": "2dcc91df-6296-47ce-90b2-4a3e0b8b354c",
  "status": "complete",
  "query": "Show me the top 10 token trades by volume today",
  "sql": "SELECT token_name, SUM(volume) as volume ... LIMIT 10",
  "data": [
    {
      "token_name": "Giggles",
      "volume": "5344877.3 SOL"
    },
    {
      "token_name": "DubX on SOL",
      "volume": "4183920.3 SOL"
    },
    {
      "token_name": "Polycule",
      "volume": "3304656.1 SOL"
    }
  ],
  "rowCount": 10,
  "duration": 2700,
  "timestamp": "2025-08-21T05:09:32.492Z"
}

200stream: true

Success (stream: true)

data: {"id":"...","phase":"plan","status":"start","message":"plan phase started",...}
data: {"id":"...","phase":"plan","status":"end","message":"plan phase completed","plan":["..."]}
data: {"id":"...","phase":"sql_generation","status":"start",...}
data: {"id":"...","phase":"sql_generation","status":"end","rowCount":10}
data: {"id":"...","phase":"data_display","status":"end","data":[{...},{...}],...}

400

Bad Request

{
  "error": "Missing required field: query"
}

500

Internal Server Error

{
  "error": "Database connection failed"
}