🪙Tokens

This article shows how to get onchainindividual rewards

Fuul simplifies blockchain data for you. We take complex onchain information, clean it up, and present it in a format that's more readable. Projects then can choose to get the data from Fuul's indexed data, or directly from the subgraph.

Fuul's Indexed Data

Payouts for a specific Address

Rewards data is not updated in real time due to performance considerations. Recent conversions and payouts will appear on the leaderboard within a maximum of one hour.

To get the rewards use the getPayoutsLeaderboard method filtered by user address.

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

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

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
    },
  ]
}

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
    }
  ]
}

Payouts history for a specific address

To get all points history for an address use the getUserPayoutMovements method.

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

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

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

{
    "total_results": 2,
    "page": 1,
    "page_size": 25,
    "results": [
        {
            "payout_id": "52b380da-7347-4e7e-a050-49e65504ed53",
            "project_name": "Project name",
            "date": "2025-04-15T20:11:55.291Z",
            "currency_address": "0x00CECf7EF55efe32b75207b2462aE5c911896978",
            "chain_id": 84532,
            "is_referrer": false,
            "conversion_id": "851e9d7d-1e09-4324-affc-9c2cda60450e",
            "conversion_name": "Conversion name",
            "total_amount": "17.594",
            "payout_status": "confirmed",
            "payout_status_details": null
        },
        {
            "payout_id": "c9e4bab1-fe17-4531-95ec-03b387c6a9ab",
            "project_name": "Project name",
            "date": "2025-04-15T19:58:11.199Z",
            "currency_address": "0x00CECf7EF55efe32b75207b2462aE5c911896978",
            "chain_id": 84532,
            "is_referrer": false,
            "conversion_id": "1b1361c1-959d-4fd7-8468-d43c1f9e679c",
            "conversion_name": "Conversion name",
            "total_amount": "16.668",
            "payout_status": "confirmed",
            "payout_status_details": null
        },
    ]
}

Fuul Subgraphs

Every payout reward has an onchain record on the project's FuulProject contract. This information can be retrieved from any indexer, but using our aggregated subgraphs makes it much easier.

To get the total, claimed and unclaimed rewards for a specific user and Fuul projects, use the following query.

userBalances(
  where: { 
    owner_contains_nocase: "0x12345", 
    project_: {
      deployedAddress:"0x12345"
    }}
) {
  availableToClaim
  claimed
  currency
  project {
    id
    deployedAddress
  }
}

You can also filter out by currency like this:

userBalances(
  where: { 
    owner_contains_nocase: "0x12345", 
    currency_contains: "0x0000000000000000000000000000000000000000",
    project_: {
      deployedAddress:"0x12345"
    }}
) {
  availableToClaim
  claimed
  currency
  project {
    id
    deployedAddress
  }
}

Please visit the Subgraph section of the documentation to get the endpoints and know more about the schema