Fuul
  • INTRO
    • ⚑What is Fuul?
    • πŸ’ͺWhy use Fuul?
    • πŸ€”Use Cases
    • βš™οΈIntegration
    • πŸ”—Main Links
  • HOW IT WORKS
    • πŸ’ΈTypes of Rewards
    • βœ…Conversion Events
      • 1️⃣CLAMM LPs (e.g. Uniswap V3)
      • 2️⃣Constant LPs (e.g., Uniswap V2)
      • 3️⃣Lending & Borrowing
      • 4️⃣Staking
      • 5️⃣Token Holders
      • 6️⃣Custom Onchain Events
      • 7️⃣Custom Offchain Events
  • πŸ€‘Incentive Payouts
    • πŸ—ΏFixed Rewards
    • 🌊Variable Rewards
    • πŸ’°Pool Distribution
  • πŸ§‘β€πŸ€β€πŸ§‘Referrals
  • ♾️Attribution Methods
  • πŸ’²Budgets
  • ⚑Fuul Incentives Manager
  • πŸŽ–οΈLeaderboards
  • πŸ’»Incentives Hub
    • πŸ‘¨β€πŸ’»White-Label Implementation
    • πŸ‘No-Code
  • FOR DEVS
    • ⭐Getting started with Fuul Web SDK
    • βš™οΈSending Custom Events through the API
    • πŸ“„Tracking referrals in your app
    • πŸ‘¨β€πŸ’»API Key Management
    • πŸ› οΈBuilding your incentives hub in your app (white-label)
      • ℹ️Getting all incentives information
      • πŸ”—Creating affiliate links or codes
      • πŸ’―Getting Leaderboard Data
        • πŸͺ™Tokens
        • 🌟Points
      • πŸ™‹Getting Individual Rewards
        • πŸͺ™Tokens
        • 🌟Points
      • πŸ€™Claiming Onchain Rewards
    • πŸ”§Building widgets
    • πŸ“’Managing Audiences and Segments
      • πŸ‘€Getting User Audiences using Fuul SDK
      • πŸ‘₯Updating Audience Segments using Fuul API
    • ✈️Migration from older SDK versions
    • πŸ†˜Troubleshooting
  • PROTOCOL
    • ⛓️Smart Contracts
    • 🧡Subgraphs
  • Guides
    • ✏️Getting Started
      • Creating Your First Incentive Program
      • How to Add a Budget in Fuul
  • 🏁Creating Triggers & Conversions
    • Understanding Triggers Types
    • Creating an Event with CSV file
  • 🎨Program Incentive Page
    • Building no code landing pages
  • πŸ“ŠAnalytics
    • Understanding Sybil Detection
Powered by GitBook
On this page
  • Fuul's Indexed Data
  • Payouts for a specific Address
  • Payouts for a specific address per conversion
  • Payouts history for a specific address
  • Fuul Subgraphs
  1. FOR DEVS
  2. Building your incentives hub in your app (white-label)
  3. Getting Individual Rewards

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
  }
}
PreviousGetting Individual RewardsNextPoints

Last updated 29 days ago

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

πŸ› οΈ
πŸ™‹
πŸͺ™
Subgraph