Getting started with Fuul SDK

Installation & minimum set up

1. Installation

Run one of the following commands to add Fuul SDK to your project:

Npm:

npm install @fuul/sdk

Yarn:

yarn add @fuul/sdk

2. Set up

Before using the SDK you must initialize it by supplying your Fuul issued API key.

NOTE: Be sure to do this at the root of your app so you have the SDK ready for use just by importing it at the usage point.

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

Fuul.init({ apiKey: "your-fuul-api-key" });

Now you can start sending events.

3. Sending events

For Fuul to attribute conversion events you'll need to report the following tracking events

Page view event

Projects must send this event every time a user visits a page on their website.

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

await Fuul.sendPageview();

Identify user

Projects must send this event every time users connect a wallet to their website.

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

await Fuul.identifyUser({
  userIdentifier: "0xe06099DbbF626892397f9A74C7f42F16748292Db",
  identifierType: UserIdentifierType.EvmAddress,
  signature: "0xb823038d78e541470946e5125b74878c226a84f891671946f18fbe7e5995171731b92f569c3e83f1c9fb89c5351245494c5d2ce6273f74c853a2cace6073f09c1c",
  message: "Connect wallet"
});

NOTE: Make sure to send the event when connecting a wallet for the first time as well as when changing wallets during the session.

Claim Checks

The SDK provides methods to retrieve claim checks for users - these are claimable rewards that users can redeem on-chain.

Get Claimable Checks

Retrieve all claimable claim checks for a user. This returns only unclaimed checks with valid (non-expired) deadlines.

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

const claimableChecks = await Fuul.getClaimableChecks({
  user_identifier: '0xe06099DbbF626892397f9A74C7f42F16748292Db',
  user_identifier_type: UserIdentifierType.EvmAddress
});

// Process each claimable check
claimableChecks.forEach(check => {
  console.log(`Amount: ${check.amount}`);
  console.log(`Currency: ${check.currency}`);
  console.log(`Deadline: ${new Date(check.deadline * 1000).toISOString()}`);
  console.log(`Proof: ${check.proof}`);
  console.log(`Signatures:`, check.signatures);
});

The response includes all the data needed for on-chain claim verification including cryptographic proofs and signatures.

Get Claim Check Totals

Get aggregated totals of claim checks for a user, one row per currency per state.

Every row carries a status label. The unclaimed array is the umbrella for two states: 'open' (still accumulating rewards — must be closed before it can be claimed) and 'closed' (ready to claim on-chain right now). A "ready to claim" figure must only sum rows with status: 'closed'. Note: other endpoints (e.g. getClaimChecks) use the stored status value unclaimed to mean what this endpoint labels closed.

import { ClaimCheckTotalsStatusFilter, Fuul, UserIdentifierType } from '@fuul/sdk';

const totals = await Fuul.getClaimCheckTotals({
  user_identifier: '0xe06099DbbF626892397f9A74C7f42F16748292Db',
  user_identifier_type: UserIdentifierType.EvmAddress
});

// Display claimed totals
console.log('Claimed:');
totals.claimed.forEach(item => {
  console.log(`  ${item.currency_name}: ${item.amount} (${item.currency_address})`);
});

// Display unclaimed totals, split by state
console.log('Ready to claim:');
totals.unclaimed
  .filter(item => item.status === 'closed')
  .forEach(item => {
    console.log(`  ${item.currency_name}: ${item.amount} (${item.currency_address})`);
  });

console.log('Still accumulating:');
totals.unclaimed
  .filter(item => item.status === 'open')
  .forEach(item => {
    console.log(`  ${item.currency_name}: ${item.amount} (${item.currency_address})`);
  });

An optional status filter of type ClaimCheckTotalsStatusFilter limits the response to a single state — for example status: ClaimCheckTotalsStatusFilter.Closed returns only the ready-to-claim rows. ClaimCheckTotalsStatusFilter.Unclaimed filters to the umbrella (both open and closed rows). The enum members map to the wire values 'claimed' | 'unclaimed' | 'open' | 'closed'; invalid values return a 400 listing the valid ones.

An optional reason filter of type ClaimCheckTotalsReasonFilter narrows which rows are summed by earning type: AffiliatePayout is commission earned for referring others, EndUserPayout is the rebate a user earned on their own activity, AgencyPayout is an agency's share. When omitted, all earning types are merged into one figure per currency and state.

The filter does not change the response shape — rows carry no reason field — so showing commission and rebates as separate figures means calling twice:

import { ClaimCheckTotalsReasonFilter, Fuul, UserIdentifierType } from '@fuul/sdk';

const ids = {
  user_identifier: '0xe06099DbbF626892397f9A74C7f42F16748292Db',
  user_identifier_type: UserIdentifierType.EvmAddress
};

const commission = await Fuul.getClaimCheckTotals({ ...ids, reason: ClaimCheckTotalsReasonFilter.AffiliatePayout });
const rebates = await Fuul.getClaimCheckTotals({ ...ids, reason: ClaimCheckTotalsReasonFilter.EndUserPayout });

reason combines with status — pass both to get, for example, only the ready-to-claim rebate rows.

Expired checks are excluded from open and closed rows, so closed sums are always claimable right now. Claimed totals are the user's claim history.