# 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

```bash
npm install @fuul/sdk
```

```typescript
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:

```typescript
// 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](https://docs.fuul.xyz/developer-guide/tracking-referrals-in-your-app) 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:

```typescript
// 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:**

```bash
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" }
      }
    }
  }'
```

{% hint style="danger" %}
Always send trigger events from the backend using a `send:trigger_event` key. Never expose this key in the frontend.
{% endhint %}

See [Sending Custom Events](https://docs.fuul.xyz/developer-guide/sending-custom-events-through-the-api) for batch events and advanced options.

## Step 4: Display the points leaderboard

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

```json
{
  "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 }
  ]
}
```

{% hint style="info" %}
Leaderboard responses are paginated. Use `page` and `page_size` (max 100) to retrieve the full list.
{% endhint %}

## Step 5: Show a user's points

```typescript
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:

```typescript
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.

{% hint style="info" %}
Rewards data is updated hourly. Recent conversions and payouts appear within a maximum of one hour.
{% endhint %}

## Next steps

| Feature                            | Guide                                                                                                  |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------ |
| Add badges for milestones          | [Badges](https://docs.fuul.xyz/core-concepts/badges)                                                   |
| Create tiered rewards              | [Tiers & Multipliers](https://docs.fuul.xyz/core-concepts/tiers-and-multipliers)                       |
| Target user segments               | [Managing Audiences](https://docs.fuul.xyz/developer-guide/managing-audiences)                         |
| Group points by conversion         | [Individual Rewards — Points](https://docs.fuul.xyz/developer-guide/getting-individual-rewards/points) |
| Add referrals to earn bonus points | [Tracking Referrals](https://docs.fuul.xyz/developer-guide/tracking-referrals-in-your-app)             |