🌟Points Program with Leaderboard

Build a points-based loyalty program where users earn points for actions — with a leaderboard and per-user rewards view.

Prerequisites

A Fuul account with a project created
Conversion events configured with point-based payouts
API keys: send:tracking_event (frontend) and send:trigger_event (backend)

Step 1: Install and initialize

npm install @fuul/sdk

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

Fuul.init({ apiKey: 'your-send-tracking-event-key' });

Step 2: Track users

Set up pageview tracking and wallet identification so Fuul can attribute points to the right users:

// On every page load
await Fuul.sendPageview();

// On wallet connect
await Fuul.identifyUser({
  identifier: address,
  identifierType: 'evm_address',
  signature,
  message: 'Sign to verify your identity',
});

See Tracking Referrals for full details.

Step 3: Send custom events from your backend

When a user completes an action that should earn points, send an event from your backend:

// Backend — use the send:trigger_event API key
const response = await fetch('https://api.fuul.xyz/api/v1/events', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-send-trigger-event-key',
  },
  body: JSON.stringify({
    name: 'task_completed',
    user: {
      identifier: '0x1234...',
      identifier_type: 'evm_address',
    },
    args: {
      value: {
        amount: '100',
        currency: { name: 'POINT' },
      },
    },
  }),
});

cURL equivalent:

curl -X POST https://api.fuul.xyz/api/v1/events \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-send-trigger-event-key" \
  -d '{
    "name": "task_completed",
    "user": {
      "identifier": "0x1234...",
      "identifier_type": "evm_address"
    },
    "args": {
      "value": {
        "amount": "100",
        "currency": { "name": "POINT" }
      }
    }
  }'

Always send trigger events from the backend using a send:trigger_event key. Never expose this key in the frontend.

See Sending Custom Events for batch events and advanced options.

Step 4: Display the points leaderboard

const leaderboard = await Fuul.getPointsLeaderboard({});

{
  "total_results": 240,
  "page": 1,
  "page_size": 10,
  "results": [
    { "address": "0x1234...", "total_amount": 15000, "rank": 1, "total_attributions": 85 },
    { "address": "0x5678...", "total_amount": 12300, "rank": 2, "total_attributions": 62 }
  ]
}

Leaderboard responses are paginated. Use page and page_size (max 100) to retrieve the full list.

Step 5: Show a user's points

const points = await Fuul.getPointsLeaderboard({
  user_identifier: address,
  identifier_type: 'evm_address',
});
// Shows the user's total points, rank, and attribution count

Step 6: Show points history

Display a breakdown of how the user earned their points:

const history = await Fuul.getUserPointsMovements({
  user_identifier: address,
  identifier_type: 'evm_address',
});

Each movement includes the amount, conversion name, and timestamp. For points, payout_status is always confirmed since no onchain transaction is needed.

Rewards data is updated hourly. Recent conversions and payouts appear within a maximum of one hour.