Distribute Rewards

Distribute rewards to token holders using TIP-20's built-in reward distribution mechanism. Rewards allow parties to incentivize holders of a token by distributing tokens proportionally based on their balance.

Rewards can be distributed by anyone on any TIP-20 token, and claimed by any holder who has opted in. This guide covers both the reward distributor and token holder use cases. While the demo below uses a token you create, the same principles apply to any token.

Demo

Try out the complete rewards flow: create a token, opt in to receive rewards on it, create a reward for yourself, and claim it.

Distribute Rewards

demo

Create an account, or use an existing one.

Add testnet funds to your account.

Create & deploy a token to testnet.

Grant issuer role on token.

Mint 100 tokens to yourself.

Opt in to receive token rewards.

Start a reward of 50 tokens.

Claim your rewards.

Steps

[Optional] Create a Stablecoin

If you would like to distribute rewards on a token you have created, follow the Create a Stablecoin guide to deploy your token.

Tell Your Users to Opt In to Rewards

Token holders must opt in to receive rewards by setting their reward recipient address. This is typically set to their own address.

import React from 'react'
import {  } from 'wagmi/tempo'
import {  } from 'wagmi'
 
export function () {
  const {  } = ()
  const  = '0x...' // Your token address
 
  const  = ..()
 
  const  = () => { 
    if (!) return
    .({ 
      : , 
      : , 
    }) 
  } 
 
  return (
    < 
      ={.}
      ={}
      ="button"
    >
      {. ? 'Opting in...' : 'Opt In to Rewards'}
    </>
  )
}

Make a Reward Distribution

Anyone can make a reward distribution that allocates tokens to all opted-in holders proportionally based on their balance.

import React from 'react'
import {  } from 'wagmi/tempo'
import {  } from 'viem'
 
export function () {
  const  = '0x...' // Your token address
 
  const { :  } = ..({
    : ,
  })
 
  const  = ..useStartSync()
 
  const  = () => { 
    if (!) return
    .mutate({ 
      : ('50', .), 
      : , 
    }) 
  } 
 
  return (
    <
      ={.isPending || !}
      ={}
      ="button"
    >
      {.isPending ? 'Starting...' : 'Start Reward'}
    </>
  )
}

Your Users Can Claim Rewards

Once a reward is distributed, opted-in holders can claim their share.

import React from 'react'
import {  } from 'wagmi/tempo'
 
export function () {
  const  = '0x...' // Your token address
 
  const  = ..()
 
  const  = () => { 
    .({ 
      : , 
    }) 
  } 
 
  return (
    <
      ={.}
      ={}
      ="button"
    >
      {. ? 'Claiming...' : 'Claim Rewards'}
    </>
  )
}

Recipes

Watch for new reward distributions

Use useWatchRewardDistributed to listen for new reward distributions on a token. This is useful for updating your UI when a reward is distributed.

import {  } from 'wagmi/tempo'
 
function () {
  const  = '0x...' // Your token address
 
  ..({ 
    : , 
    () { 
      .('New reward scheduled:', ) 
      // Update UI, refetch balances, show notification, etc.
    }, 
  }) 
 
  return <>Watching for reward distributions...</>
}

Watch for reward opt-ins

Use useWatchRewardRecipientSet to listen for when users opt in to rewards by setting their recipient address. This is useful for tracking opt-in activity.

import {  } from 'wagmi/tempo'
 
function () {
  const  = '0x...' // Your token address
 
  ..({ 
    : , 
    () { 
      .('User opted in:', ) 
      // Update UI, track analytics, etc.
    }, 
  }) 
 
  return <>Watching for reward opt-ins...</>
}

Learning Resources

TIP-20 Rewards Spec

See the TIP-20 rewards spec

TIP-20 Rewards Overview

Read an overview of TIP-20 rewards