Query Builder
Generate and preview SQL queries for incentive data sources
The query builder tools generate SQL queries that define what user activity an incentive tracks and how it's measured, and preview the results before an incentive is created.
generate_incentive_query
Generate the SQL for an incentive query. Set the source parameter to select the data source, then provide source-specific parameters. The tool returns a validated SQL string ready to pass as sqlQuery to create_recurring_incentive.
Requires: authentication, active project
Common parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
source | "swap" | "bonding_curve" | "hold" | "custom_event" | "idl_instruction" | "dune_query" | Yes | Data source for the query |
confirmed | boolean | No | Set to true to confirm (custom_event, idl_instruction, dune_query). Omit to preview the generated SQL. |
Threshold semantics are inclusive by default. minUsdAmount, minAmountIn, minBalance, and any
numeric filters use >= (inclusive). When a user says "over 100" or "100+", use 100. Only use > when
the user says "more than" or "above" without inclusion.
Swap parameters
| Parameter | Type | Description |
|---|---|---|
tokenMint | string | SPL token mint address (required) |
direction | "buy" | "sell" | "both" | Trade direction (default: "buy") |
measure | "volume" | "count" | Required. volume uses USD; count is transaction count. |
minUsdAmount | number | Minimum USD value per swap (inclusive) |
protocol | string | DEX protocol filter (e.g. Jupiter, Raydium) |
Bonding curve parameters
| Parameter | Type | Description |
|---|---|---|
launchpad | "raydium_launchlab" | "metaplex_genesis" | Required |
direction | "buy" | "sell" | "both" | Default: "buy" |
measure | "volume" | "count" | Required |
poolState | string | Pool state address (required for raydium_launchlab) |
genesisAccount | string | Genesis account (required for metaplex_genesis) |
minAmountIn | number | Minimum purchase size, raw amount (inclusive) |
Hold parameters
| Parameter | Type | Description |
|---|---|---|
tokenMint | string | SPL token mint address (required) |
measure | "balance" | "duration" | "count" | Required. balance = latest qualifying balance per wallet; duration = distinct days with qualifying balance; count = number of qualifying balance records. |
minBalance | number | Minimum token balance, must be > 0 (required; inclusive) |
Custom event parameters
| Parameter | Type | Description |
|---|---|---|
customEventId | string | Custom event ID (required). Use list_custom_events. |
valueExpression | string | E.g. "SUM(amount)", "COUNT(*)", "1" (flat reward). Mutually exclusive with rawQuery. |
filters | string[] | WHERE conditions using field names (inclusive semantics apply). |
groupByPubkey | boolean | Default: true |
orderBy | "DESC" | "ASC" | Sort order |
limit | number | Max rows |
rawQuery | string | Full SELECT with {{startDate}} / {{endDate}} placeholders. Mutually exclusive with valueExpression. |
IDL instruction parameters
| Parameter | Type | Description |
|---|---|---|
instructionId | string | Instruction ID (required). Use list_idls. |
valueExpression | string | E.g. "SUM(amount_in)", "COUNT(*)". Mutually exclusive with rawQuery. |
filters | string[] | WHERE conditions |
groupByFeePayer | boolean | Default: true |
orderBy | "DESC" | "ASC" | Sort order |
rawQuery | string | Full SELECT with {{startDate}} / {{endDate}} placeholders. Mutually exclusive with valueExpression. |
Dune query parameters
| Parameter | Type | Description |
|---|---|---|
duneEventQueryId | string | Torque-side UUID returned by register_dune_event_source — NOT the numeric duneQueryId. Required. |
valueExpression | string | E.g. "SUM(volume_usd)", "COUNT(*)", "1". Mutually exclusive with rawQuery. |
filters | string[] | WHERE conditions using columns from the Dune result set |
groupByPubkey | boolean | Default: true |
orderBy | "DESC" | "ASC" | Sort order |
limit | number | Max rows |
rawQuery | string | Full SELECT with {{startDate}} / {{endDate}} placeholders. Mutually exclusive with valueExpression. |
Dune event sources must complete at least one daily ingestion run before they can be queried.
generate_incentive_query rejects sources without a populated column mapping. See Dune Event
Sources.
preview_incentive_query
Execute a SQL query against real indexed data and preview the results before creating an incentive. The query runs asynchronously with up to 60 seconds of polling. By default, previews the last 3 complete days of data (midnight today is excluded to avoid partial-day data).
Requires: authentication, active project
| Parameter | Type | Required | Description |
|---|---|---|---|
sqlQuery | string | Yes | The SQL query to preview |
startDate | string | No | ISO 8601 start (default: midnight 3 days ago) |
endDate | string | No | ISO 8601 end (default: midnight today) |
Up to 20 rows are rendered in the output as a markdown table; the full result count is reported alongside. If the query times out (60s), the tool returns the queryId so results can be retrieved later from the platform.
Always preview your query before creating an incentive. This validates that the query produces the expected shape and data against the live indexed database.
Creation-time only. This tool tests queries during incentive setup. To check results or status of a live
incentive, use get_epoch_leaderboard instead.