Getting leaderboards and individual token earnings using Fuul SDK

This article shows how to get onchain payout rewards - individually or in a leaderboard format

Projects can decide to show a leaderboard or a user profile on their own website.

Leaderboard

To get the affiliate leaderboard for your project use the getPayoutsLeaderboard method.

import { Fuul } from ('@fuul/sdk');

await Fuul.getPayoutsLeaderboard({ currency_address: '0x12345' });

currency_address is the address of the currency on the chain that the project is distributing payouts. Remember projects can payout different tokens for different conversions.

A simple response for retrieving this information would be the following:

{
  "total_results": 100,
  "page": 1,
  "page_size": 10,
  "results": [
    {
      "address": "0xBfBAdD58B65B54D1a5cEa6d9c730fbd57c182d32",
      "total_amount": 200, // Already formatted with the corresponding decimals
      "rank": 1,
      "total_attributions": 10
    },
    {
      "address": "0xg9BAdD58B65B54D1a5c216d9c730fbd57c182d56",
      "total_amount": 170,  // Already formatted with the corresponding decimals
      "rank": 2,
      "total_attributions": 9
    }
  ]
}

You can also filter out this information for a specific user by passing on the user_address, dates with the from and to parameters, type of users with user_type and spefific conversions with their ids.

import { Fuul } from ('@fuul/sdk');

await Fuul.getPayoutsLeaderboard({ 
    currency_address: '0x12345',
    user_address: '0x12345' ,
    from: new Date('2021-01-01'),
    to: new Date('2022-01-01'),
    user_type: 'all', // all, affiliate or end_user
    conversions: '1,2,3'
});

You can retrieve the tier and the volume information of users by adding them on the fields parameter as follows:

import { Fuul } from ('@fuul/sdk');

await Fuul.getPayoutsLeaderboard({ 
    currency_address: '0x12345',
    fields: 'tier,referred_volume,referred_users'
});

The referred_volume parameter will be returned in USD values.

Payouts for a specific address per conversion

To get all payouts for an address use the getUserPayoutsByConversion method.

import { Fuul } from ('@fuul/sdk');

await Fuul.getUserPayoutsByConversion({ user_address: '0x12345' });

You can also filter out dates as follows:

import { Fuul } from ('@fuul/sdk');

await Fuul.getUserPayoutsByConversion({
      user_address: '0x12345',
      from: new Date('2021-01-01'),
      to: new Date('2022-01-01'),
});

A simple response for retrieving this information would be the following:

{
  "total_results": 100,
  "page": 1,
  "page_size": 10,
  "results": [
    {
      "currency_address": "0x2a61f17d6Ab1288627D8E21D75712df07007dafb",
      "chain_id": 1,
      "is_referrer": true,
      "conversion_id": "4bdabf2c-271a-4d66-afd0-a9f24119810a",
      "conversion_name": "Buy",
      "total_amount": 200
    }
  ]
}

You can also get the data directly from the API. Please check out our interactive documentation here