Creating Incentives

Step-by-step guide to creating any type of incentive

Every incentive follows the same pattern: set up your data source → generate a query → preview results → create the incentive. The setup step varies by action type.

Choose Your Action Type

Action	What It Tracks	Setup Required
Swap	Token trades on DEXs (Jupiter, Raydium, etc.)	None — already indexed
Bonding Curve	Trades on launchpads (Raydium Launchlab, Metaplex Genesis)	None — already indexed
Hold	Token balance at evaluation time	None — already indexed
Custom Event	Off-chain activity (signups, social actions, purchases)	Event schema + data ingestion
IDL Instruction	On-chain Solana program interactions	IDL upload

Token Incentives (Zero Setup)

Token incentives reward on-chain token activity using already-indexed data. No setup required.

Generate the query

Use generate_incentive_query with the appropriate source:

Swap — track DEX trades:

source: "swap"
tokenMint: "your-token-mint"
direction: "buy"
measure: "volume"

Bonding Curve — track launchpad trades:

source: "bonding_curve"
tokenMint: "your-token-mint"
launchpad: "raydium_launchlab"
measure: "volume"

Hold — track token holders:

source: "hold"
tokenMint: "your-token-mint"
measure: "balance"
minBalance: 1000

Preview results

Use preview_incentive_query to validate against real data:

sqlQuery: "<the generated SQL>"

Create the incentive

Use create_recurring_incentive with the query and reward configuration:

name: "Weekly Swap Leaderboard"
type: "leaderboard"
emissionType: "TOKENS"
tokenAddress: "your-token-mint"
tokenDecimals: 9
totalFundAmount: 1000
interval: "WEEKLY"
startDate: "2025-01-01T00:00:00Z"
sqlQuery: "<the generated SQL>"

Token Incentive Examples

Recipe	Source	Measure	Direction	Type
Top Buyers by Volume	`swap`	`volume`	`buy`	`leaderboard`
Hold Rewards	`hold`	`balance`	—	`leaderboard` or `rebate`
Bonding Curve Early Buyers	`bonding_curve`	`volume`	`buy`	`leaderboard`
Swap Raffle	`swap`	`count`	`buy`	`raffle`

Custom Event Incentives

Custom event incentives track off-chain activity — social actions, content creation, purchases, game events.

Create the event schema

Use create_custom_event to define your event:

eventName: "content_share"
name: "Content Share"
fields: [
  { fieldName: "platform", type: "string" },
  { fieldName: "reach", type: "number" },
  { fieldName: "verified", type: "boolean" }
]

Attach to your project

Use attach_custom_event to make it available for incentives:

customEventId: "<the event ID from step 1>"

Send event data

Use the ingestion API with your API key:

curl -X POST https://ingest.torque.so/events \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -d '{
    "userPubkey": "wallet-address",
    "timestamp": 1234567890000,
    "eventName": "content_share",
    "data": {
      "platform": "twitter",
      "reach": 1500,
      "verified": true
    }
  }'

Generate, preview, and create

Generate the query:

source: "custom_event"
customEventId: "<the event ID>"
valueExpression: "SUM(reach)"
filters: ["verified = true"]

Preview with preview_incentive_query, then create with create_recurring_incentive (include customEventId in the creation call).

Events must be ingested at least once before they become query-ready. Use list_project_events to check which events are ready.

IDL Instruction Incentives

IDL instruction incentives reward users for interacting with specific instructions in your Solana program.

Parse the IDL

Use parse_idl to inspect your Anchor IDL:

filePath: "/path/to/your/idl.json"

Upload the IDL

Use create_idl to upload and select instructions to track:

filePath: "/path/to/your/idl.json"
displayName: "My Program"
selectedInstructions: [
  {
    instructionName: "buy_exact_in",
    fields: [
      { fieldName: "amount_in", type: "number" },
      { fieldName: "min_amount_out", type: "number" }
    ],
    accounts: ["payer", "pool"]
  }
]

Generate, preview, and create

Generate the query:

source: "idl_instruction"
instructionId: "<the instruction ID from step 2>"
valueExpression: "SUM(amount_in)"

Preview with preview_incentive_query, then create with create_recurring_incentive (include instructionId in the creation call).

Use list_idls to see uploaded IDLs and their tracked instructions. Use create_instruction to add instructions to an existing IDL.

Reward Types

Once you have a query, choose how rewards are distributed:

Type	How It Works	Key Params
Leaderboard	Rank users by metric, distribute via formula	`customFormula`
Rebate	Return a % of each user's metric value	`rebatePercentage`
Raffle	Weighted random draw from qualifying users	`raffleBuckets`, `raffleWeighting`
Direct	Fixed amounts to specific wallets	`allocations`

See Incentive Types for full details on each type, formulas, and examples.