🌟Points

Retrieve point rewards for individual users.

Points for a specific user

Use getPointsLeaderboard filtered by user_identifier:

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

await Fuul.getPointsLeaderboard({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
});

Example response:

{
  "total_results": 1,
  "page": 1,
  "page_size": 10,
  "results": [
    {
      "address": "0x1234...",
      "total_amount": 15000,
      "rank": 42,
      "total_attributions": 85
    }
  ]
}

Points grouped by conversion

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

await Fuul.getUserPointsByConversion({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
  from: '2024-01-01',
  to: '2024-12-31',
});

Paginating the response

Field	Behavior
total_results	The number of rows matching the query. Compare it against how many rows you have fetched, not against a sum of point amounts
Page size	Pages fill to page_size even on a program paying several currencies — the filter to point rows runs in the query, not after it
Ordering	Stable. Point amounts tie constantly, so rows are ordered with conversion_external_id and reason as tiebreakers

Page through until you have collected total_results rows. Earlier behavior made total_results and the returned row count disagree, so drop any workaround you built around that.

Points history (movements)

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

await Fuul.getUserPointsMovements({
  user_identifier: '0x1234...',
  identifier_type: 'evm_address',
});

Each movement includes a payout_status field. For point-type movements, this is always confirmed since no on-chain transaction is needed.

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

API reference

SDK method	API endpoint	Reference
getPointsLeaderboard	GET /v1/payouts/leaderboard/points	View
getUserPointsByConversion	GET /v1/payouts	View
getUserPointsMovements	GET /v1/payouts/movements	View