🗂️API Endpoint Directory

Complete index of all Fuul API endpoints, organized by what you need to do. Each entry links to the documentation page with full context and SDK examples, plus the API reference for request/response details.

All endpoints use https://api.fuul.xyz/api as the base URL. Authentication is via Authorization: Bearer <api_key> unless marked as public.

Leaderboards & Rankings

Show how users rank by tokens earned, points earned, or volume generated.

Endpoint	What it does	Docs	API ref
GET /v1/payouts/leaderboard/payouts	Rank users by onchain token rewards earned	Tokens leaderboard	View
GET /v1/payouts/leaderboard/points	Rank users by points earned	Points leaderboard	View
GET /v1/payouts/leaderboard/volume	Rank users by transaction volume generated (USD)	Volume leaderboard	—
GET /v1/payouts/leaderboard/revenue	Rank users by total revenue generated	Volume vs revenue	View
GET /v1/leaderboard/referred	Rank users by number of users referred	Leaderboard data	—
GET /v1/payouts/leaderboard/referred-volume	Get referred volume (USD) for specific users	Referred metrics	View

Individual User Rewards

Retrieve reward data for a specific user — earnings, payout history, and totals.

Endpoint	What it does	Docs	API ref
GET /v1/payouts	Get payouts grouped by conversion for a user	Token rewards	View
GET /v1/payouts/movements	Get payout history (movements with dates, amounts, status)	Claim flow	View
GET /v1/payouts/totals/{userIdentifier}	Get aggregated payout totals across all conversions	Individual rewards	View
GET /v1/payouts/summary	Get aggregated payout summary for the entire project	Affiliate dashboard	View
GET /v1/payouts/by-referrer	Get volume and earnings per referred user for an affiliate	Referred metrics	View

Claiming Onchain Rewards

Fetch claimable balances, generate signed vouchers, and manage the claim flow.

Endpoint	What it does	Docs	API ref
GET /v1/claimable-rewards	Show unclaimed rewards for a user (public, no auth)	Claimable rewards	View
GET /v1/claim-checks/totals	Get claimed and unclaimed balances by currency	Claim flow	View
GET /v1/claim-checks	List a user's claim checks, filterable by status (open, unclaimed, claimed)	Get claim checks	—
POST /v1/claim-checks/claim	Get signed vouchers for onchain claiming	Get claim checks	View
POST /v1/claim-checks/close	Sign and finalize a user's open checks when aggregation is enabled	Get claim checks	—
GET /v1/claim-checks/claim-history	Paginated history of a user's completed onchain claims, per (hash, currency)	Claim flow	View
GET /v1/claim-checks/rewards-payouts	List all claim checks for a project (admin, filterable)	Claim flow	View
GET /v1/claim-checks/rewards-payouts/totals	Get aggregated claim check totals by currency (admin)	Claim flow	View

Pending Acceptance Payouts

For programs that require users to accept rewards before they become claimable.

Endpoint	What it does	Docs	API ref
GET /v1/payouts/pending-acceptance	List payouts waiting for user acceptance	Claim flow	View
POST /v1/payouts/pending-acceptance/accept	Accept pending payouts with a signed message	Claim flow	View

Referral Tracking & Attribution

Manage referral relationships — who referred whom.

Endpoint	What it does	Docs	API ref
GET /v1/user/referrer	Get the referrer for a specific user	Referral codes	View
PUT /v1/user-referrers	Create or overwrite a referrer-user relationship via API	Referral codes	View
DELETE /v1/user-referrers	Remove a referrer-user relationship via API (add ?force=true to bypass attribution guard)	Referral codes	View
GET /v1/user-referrers	List the project-wide referral bridge (L1 + referral_chain L2–L4) for incremental ingestion; cursor paginated	Referral codes	—

Referral Codes

Project-generated codes that users share to establish referral relationships.

Endpoint	What it does	Docs	API ref
GET /v1/referral-codes	List all referral codes owned by a user	Referral codes	View
POST /v1/referral-codes	Generate referral codes for a user (1-50 per request)	Referral codes	View
GET /v1/referral-codes/{code}	Check if a referral code is available	Referral codes	View
PATCH /v1/referral-codes/{code}	Update a referral code (e.g., max uses)	Referral codes	View
GET /v1/referral-codes/status	Check if a user has used a referral code	Referral codes	View
PATCH /v1/referral-codes/{code}/use	Accept a referral code (requires signature)	Referral codes	View
DELETE /v1/referral-codes/{code}/referrals	Remove a referral relationship	Referral codes	View

Affiliate Codes

Custom codes created by affiliates for branded referral links.

Endpoint	What it does	Docs	API ref
POST /v1/affiliates	Create an affiliate code (requires signature)	Affiliate links	View
GET /v1/affiliates/{userIdentifier}	Get affiliate info and stats (code, rebate rate, tier, totals)	Affiliate links	View
POST /v1/affiliates/{userIdentifier}	Update an affiliate code (requires signature)	Affiliate links	View
GET /v1/affiliates/codes/{code}	Check if an affiliate code is free	Affiliate links	View
GET /v1/affiliates/codes/{code}/availability	Check if a code is available (exists + has uses left)	Affiliate links	View

Affiliate Portal (Admin)

Analytics and management for affiliate programs. Requires service_role API key.

Endpoint	What it does	Docs	API ref
GET /v1/affiliate-portal/stats	Get earnings, volume, revenue, referred users for an affiliate	Affiliate dashboard	View
GET /v1/affiliate-portal/total-stats	Get aggregated stats across all affiliates	Affiliate dashboard	View
GET /v1/affiliate-portal/new-traders	List users referred by a specific affiliate	Affiliate dashboard	View
GET /v1/affiliate-portal/referral-tree	Get the referral hierarchy (Level 1-4)	Affiliate dashboard	View
GET /v1/affiliate-portal/global-breakdown	Get project-wide stats by audience, region, or status	Affiliate dashboard	View
GET /v1/affiliate-portal/stats-breakdown	Time series of one affiliate's volume, revenue, and earnings by day, week, or month	Affiliate dashboard	—
GET /v1/affiliate-portal/paid-volumes-by-level	Payout-eligible volume, revenue, and attribution counts per referral level (L1–L4)	Affiliate dashboard	View
GET /v1/affiliate-portal/qualified-user-bonus	Count referred users that qualified over a window and the USD bonus owed	Affiliate dashboard	—
GET /v1/affiliate-portal/high-volume-taker-bonus	Aggregate taker volume and the formatted high-volume bonus	Affiliate dashboard	—

Affiliate Applications

Let potential affiliates apply to join your program. Public — no auth required.

Endpoint	What it does	Docs	API ref
GET /v1/projects/{projectId}/affiliate-application-form-config	Get application form fields and validation rules	Affiliate applications	View
POST /v1/projects/{projectId}/affiliate-applications	Submit an affiliate application	Affiliate applications	View

Audiences & Badges

Manage user segments for tiered rewards and badges. Requires service_role API key.

Endpoint	What it does	Docs	API ref
GET /v1/audiences/audience-segments/user	Get which audiences a user belongs to	Managing audiences	View
GET /v1/audiences/audience-segments	List all audience segments for a project	Managing audiences	View
GET /v1/audience-segments/{segmentId}/entries	Get entries of an audience segment	Managing audiences	View
POST /v1/audience-segments/{segmentId}/entries/batch	Add up to 20 users to a segment	Managing audiences	View
DELETE /v1/audience-segments/{segmentId}/entries/{userIdentifier}	Remove a user from a segment	Managing audiences	View
POST /v1/audience-segments/{segmentId}/badge	Create a badge for a segment	Managing audiences	View
PATCH /v1/audience-segments/{segmentId}/badge	Update a badge	Managing audiences	View
DELETE /v1/audience-segments/{segmentId}/badge	Delete a badge	Managing audiences	View

Custom Events

Send offchain events to trigger rewards. Requires send:trigger_event API key.

Endpoint	What it does	Docs	API ref
POST /v1/events	Send a single custom event	Sending custom events	View
POST /v1/events/batch	Send multiple events in one request	Sending custom events	View
GET /v1/events/status	Check if an event exists for a user	Sending custom events	View

Conversions

Query conversion configurations and check user completion status.

Endpoint	What it does	Docs	API ref
GET /v1/conversions	List all conversions for your project	Sending custom events	View
GET /v1/conversions/status	Check if a user has completed specific conversions	Sending custom events	View

Webhooks

Real-time notifications when rewards are distributed. Requires service_role API key.

Endpoint	What it does	Docs	API ref
POST /v1/webhooks	Create a webhook endpoint	Webhooks	View
GET /v1/webhooks	List your webhook endpoints	Webhooks	View
GET /v1/webhooks/{id}	Get a specific webhook	Webhooks	View
PATCH /v1/webhooks/{id}	Update a webhook endpoint	Webhooks	View
DELETE /v1/webhooks/{id}	Delete a webhook endpoint	Webhooks	View
GET /v1/webhooks/{id}/deliveries	View delivery history	Webhooks	View

Email-to-Wallet Resolution

Resolve pending payouts for email recipients by mapping to wallet addresses.

Endpoint	What it does	Docs	API ref
GET /v1/payouts/pending-recipient-resolution	List emails with pending unresolved payouts	Email payouts	View
POST /v1/payouts/recipient-mappings	Create email-to-wallet mappings (up to 100/request)	Email payouts	View

Explorer (Public Listings)

Public endpoints for discovery pages and aggregator integrations.

Endpoint	What it does	Docs	API ref
GET /explorer/v1/listings/incentive-rewards	List incentive programs ranked by payouts	Build your hub	View
GET /explorer/v1/listings/referral-rewards	List referral programs ranked by payouts	Build your hub	View
GET /explorer/v1/projects/{projectId}	Get project details	Build your hub	View
GET /explorer/v1/projects/{idOrSlug}/users-count	Get total user count for a project	Build your hub	View

Public Incentives

Endpoint	What it does	Docs	API ref
GET /v1/incentives	List incentive programs with TVL and APR (no auth)	Whitelabel TVL & APR	View
GET /v1/payouts/terms-by-tier	Get payout terms grouped by project tier, with display-ready amount/currency/unit strings (SDK: getIncentivesByTier)	Tiers & Multipliers	—

Incentive Analytics

Per-incentive performance data — active users, volume, earnings, and trends per conversion. Requires OAuth JWT (dashboard login) or Fuul MCP authentication.

Endpoint	What it does	Docs	API ref
GET /api/v1/projects/:projectId/incentives/breakdown	Rank all project incentives by a metric (unique_users, volume, earnings, revenue)	Affiliate Analytics via MCP	—
GET /api/v1/projects/:projectId/incentives/:conversionId/stats	Snapshot for one incentive — users, volume, revenue, earnings, deltas vs prior period	Affiliate Analytics via MCP	—
GET /api/v1/projects/:projectId/incentives/:conversionId/history	Time series for one incentive (daily | weekly | monthly)	Affiliate Analytics via MCP	—