# 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. {% hint style="info" %} All endpoints use `https://api.fuul.xyz/api` as the base URL. Authentication is via `Authorization: Bearer ` unless marked as public. {% endhint %} ## 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](https://docs.fuul.xyz/developer-guide/getting-leaderboard-data/tokens) | [View](https://fuul.readme.io/reference/get_v1-payouts-leaderboard-payouts) | | `GET /v1/payouts/leaderboard/points` | Rank users by points earned | [Points leaderboard](https://docs.fuul.xyz/developer-guide/getting-leaderboard-data/points) | [View](https://fuul.readme.io/reference/get_v1-payouts-leaderboard-points) | | `GET /v1/payouts/leaderboard/revenue` | Rank users by total revenue generated | [Volume leaderboard](https://docs.fuul.xyz/developer-guide/getting-leaderboard-data/volume) | [View](https://fuul.readme.io/reference/get_v1-payouts-leaderboard-revenue-1) | | `GET /v1/payouts/leaderboard/referred-volume` | Get referred volume (USD) for specific users | [Referred metrics](https://docs.fuul.xyz/developer-guide/referred-metrics) | [View](https://fuul.readme.io/reference/get_v1-payouts-leaderboard-referred-volume) | ## 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](https://docs.fuul.xyz/developer-guide/getting-individual-rewards/tokens) | [View](https://fuul.readme.io/reference/get_v1-payouts-1) | | `GET /v1/payouts/movements` | Get payout history (movements with dates, amounts, status) | [Claim flow](https://docs.fuul.xyz/developer-guide/claim-frontend) | [View](https://fuul.readme.io/reference/get_v1-payouts-movements) | | `GET /v1/payouts/totals/{userIdentifier}` | Get aggregated payout totals across all conversions | [Individual rewards](https://docs.fuul.xyz/developer-guide/getting-individual-rewards) | [View](https://fuul.readme.io/reference/get_v1-payouts-totals-useridentifier) | | `GET /v1/payouts/summary` | Get aggregated payout summary for the entire project | [Affiliate dashboard](https://docs.fuul.xyz/developer-guide/affiliate-dashboard) | [View](https://fuul.readme.io/reference/get_v1-payouts-summary-1) | | `GET /v1/payouts/by-referrer` | Get volume and earnings per referred user for an affiliate | [Referred metrics](https://docs.fuul.xyz/developer-guide/referred-metrics) | [View](https://fuul.readme.io/reference/get_v1-payouts-by-referrer) | ## 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](https://docs.fuul.xyz/developer-guide/claimable-rewards) | [View](https://fuul.readme.io/reference/get_v1-claimable-rewards) | | `GET /v1/claim-checks/totals` | Get claimed and unclaimed balances by currency | [Claim flow](https://docs.fuul.xyz/developer-guide/claim-frontend) | [View](https://fuul.readme.io/reference/get_v1-claim-checks-totals) | | `POST /v1/claim-checks/claim` | Get signed vouchers for onchain claiming | [Get claim checks](https://docs.fuul.xyz/developer-guide/claiming-onchain-rewards/get-claim-checks) | [View](https://fuul.readme.io/reference/post_v1-claim-checks-claim) | | `GET /v1/claim-checks/rewards-payouts` | List all claim checks for a project (admin, filterable) | [Claim flow](https://docs.fuul.xyz/developer-guide/claim-frontend) | [View](https://fuul.readme.io/reference/get_v1-claim-checks-rewards-payouts) | | `GET /v1/claim-checks/rewards-payouts/totals` | Get aggregated claim check totals by currency (admin) | [Claim flow](https://docs.fuul.xyz/developer-guide/claim-frontend) | [View](https://fuul.readme.io/reference/get_v1-claim-checks-rewards-payouts-totals) | ## 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](https://docs.fuul.xyz/developer-guide/claim-frontend) | [View](https://fuul.readme.io/reference/get_v1-payouts-pending-acceptance-1) | | `POST /v1/payouts/pending-acceptance/accept` | Accept pending payouts with a signed message | [Claim flow](https://docs.fuul.xyz/developer-guide/claim-frontend) | [View](https://fuul.readme.io/reference/post_v1-payouts-pending-acceptance-accept-1) | ## 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](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/get_v1-user-referrer) | | `PUT /v1/user-referrers` | Create or overwrite a referrer-user relationship via API | [Referral codes](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/put_v1-user-referrers) | ## 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](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/get_v1-referral-codes) | | `POST /v1/referral-codes` | Generate referral codes for a user (1-50 per request) | [Referral codes](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/post_v1-referral-codes) | | `GET /v1/referral-codes/{code}` | Check if a referral code is available | [Referral codes](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/get_v1-referral-codes-code) | | `PATCH /v1/referral-codes/{code}` | Update a referral code (e.g., max uses) | [Referral codes](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/patch_v1-referral-codes-code) | | `GET /v1/referral-codes/status` | Check if a user has used a referral code | [Referral codes](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/get_v1-referral-codes-status) | | `PATCH /v1/referral-codes/{code}/use` | Accept a referral code (requires signature) | [Referral codes](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/patch_v1-referral-codes-code-use) | | `DELETE /v1/referral-codes/{code}/referrals` | Remove a referral relationship | [Referral codes](https://docs.fuul.xyz/developer-guide/referral-codes) | [View](https://fuul.readme.io/reference/delete_v1-referral-codes-code-referrals) | ## 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](https://docs.fuul.xyz/developer-guide/creating-affiliate-links-or-codes) | [View](https://fuul.readme.io/reference/post_v1-affiliates-1) | | `GET /v1/affiliates/{userIdentifier}` | Get the affiliate code for a user | [Affiliate links](https://docs.fuul.xyz/developer-guide/creating-affiliate-links-or-codes) | [View](https://fuul.readme.io/reference/get_v1-affiliates-useridentifier) | | `POST /v1/affiliates/{userIdentifier}` | Update an affiliate code (requires signature) | [Affiliate links](https://docs.fuul.xyz/developer-guide/creating-affiliate-links-or-codes) | [View](https://fuul.readme.io/reference/post_v1-affiliates-useridentifier) | | `GET /v1/affiliates/codes/{code}` | Check if an affiliate code is free | [Affiliate links](https://docs.fuul.xyz/developer-guide/creating-affiliate-links-or-codes) | [View](https://fuul.readme.io/reference/get_v1-affiliates-codes-code) | | `GET /v1/affiliates/codes/{code}/availability` | Check if a code is available (exists + has uses left) | [Affiliate links](https://docs.fuul.xyz/developer-guide/creating-affiliate-links-or-codes) | [View](https://fuul.readme.io/reference/get_v1-affiliates-codes-code-availability) | ## 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](https://docs.fuul.xyz/developer-guide/affiliate-dashboard) | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-stats) | | `GET /v1/affiliate-portal/total-stats` | Get aggregated stats across all affiliates | [Affiliate dashboard](https://docs.fuul.xyz/developer-guide/affiliate-dashboard) | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-total-stats) | | `GET /v1/affiliate-portal/new-traders` | List users referred by a specific affiliate | [Affiliate dashboard](https://docs.fuul.xyz/developer-guide/affiliate-dashboard) | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-new-traders) | | `GET /v1/affiliate-portal/referral-tree` | Get the referral hierarchy (R1, R2, R3) | [Affiliate dashboard](https://docs.fuul.xyz/developer-guide/affiliate-dashboard) | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-referral-tree) | | `GET /v1/affiliate-portal/global-breakdown` | Get project-wide stats by audience, region, or status | [Affiliate dashboard](https://docs.fuul.xyz/developer-guide/affiliate-dashboard) | [View](https://fuul.readme.io/reference/get_v1-affiliate-portal-global-breakdown) | ## 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](https://docs.fuul.xyz/core-concepts/affiliate-applications) | [View](https://fuul.readme.io/reference/get_v1-projects-projectid-affiliate-application-form-config) | | `POST /v1/projects/{projectId}/affiliate-applications` | Submit an affiliate application | [Affiliate applications](https://docs.fuul.xyz/core-concepts/affiliate-applications) | [View](https://fuul.readme.io/reference/post_v1-projects-projectid-affiliate-applications) | ## 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](https://docs.fuul.xyz/developer-guide/managing-audiences) | [View](https://fuul.readme.io/reference/get_v1-audiences-audience-segments-user-1) | | `GET /v1/audiences/audience-segments` | List all audience segments for a project | [Managing audiences](https://docs.fuul.xyz/developer-guide/managing-audiences) | [View](https://fuul.readme.io/reference/get_v1-audiences-audience-segments) | | `GET /v1/audience-segments/{segmentId}/entries` | Get entries of an audience segment | [Managing audiences](https://docs.fuul.xyz/developer-guide/managing-audiences) | [View](https://fuul.readme.io/reference/get_v1-audience-segments-segmentid-entries-1) | | `POST /v1/audience-segments/{segmentId}/entries/batch` | Add up to 20 users to a segment | [Managing audiences](https://docs.fuul.xyz/developer-guide/managing-audiences) | [View](https://fuul.readme.io/reference/post_v1-audience-segments-segmentid-entries-batch-1) | | `DELETE /v1/audience-segments/{segmentId}/entries/{userIdentifier}` | Remove a user from a segment | [Managing audiences](https://docs.fuul.xyz/developer-guide/managing-audiences) | [View](https://fuul.readme.io/reference/delete_v1-audience-segments-segmentid-entries-useridentifier) | | `POST /v1/audience-segments/{segmentId}/badge` | Create a badge for a segment | [Managing audiences](https://docs.fuul.xyz/developer-guide/managing-audiences) | [View](https://fuul.readme.io/reference/post_v1-audience-segments-segmentid-badge) | | `PATCH /v1/audience-segments/{segmentId}/badge` | Update a badge | [Managing audiences](https://docs.fuul.xyz/developer-guide/managing-audiences) | [View](https://fuul.readme.io/reference/patch_v1-audience-segments-segmentid-badge) | | `DELETE /v1/audience-segments/{segmentId}/badge` | Delete a badge | [Managing audiences](https://docs.fuul.xyz/developer-guide/managing-audiences) | [View](https://fuul.readme.io/reference/delete_v1-audience-segments-segmentid-badge) | ## 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](https://docs.fuul.xyz/developer-guide/sending-custom-events-through-the-api) | [View](https://fuul.readme.io/reference/post_v1-events-1) | | `POST /v1/events/batch` | Send multiple events in one request | [Sending custom events](https://docs.fuul.xyz/developer-guide/sending-custom-events-through-the-api) | [View](https://fuul.readme.io/reference/post_v1-events-batch-1) | | `GET /v1/events/status` | Check if an event exists for a user | [Sending custom events](https://docs.fuul.xyz/developer-guide/sending-custom-events-through-the-api) | [View](https://fuul.readme.io/reference/get_v1-events-status-1) | ## 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](https://docs.fuul.xyz/developer-guide/sending-custom-events-through-the-api) | [View](https://fuul.readme.io/reference/get_v1-conversions-1) | | `GET /v1/conversions/status` | Check if a user has completed specific conversions | [Sending custom events](https://docs.fuul.xyz/developer-guide/sending-custom-events-through-the-api) | [View](https://fuul.readme.io/reference/get_v1-conversions-status) | ## 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](https://docs.fuul.xyz/developer-guide/webhooks) | [View](https://fuul.readme.io/reference/post_v1-webhooks) | | `GET /v1/webhooks` | List your webhook endpoints | [Webhooks](https://docs.fuul.xyz/developer-guide/webhooks) | [View](https://fuul.readme.io/reference/get_v1-webhooks) | | `GET /v1/webhooks/{id}` | Get a specific webhook | [Webhooks](https://docs.fuul.xyz/developer-guide/webhooks) | [View](https://fuul.readme.io/reference/get_v1-webhooks-id) | | `PATCH /v1/webhooks/{id}` | Update a webhook endpoint | [Webhooks](https://docs.fuul.xyz/developer-guide/webhooks) | [View](https://fuul.readme.io/reference/patch_v1-webhooks-id) | | `DELETE /v1/webhooks/{id}` | Delete a webhook endpoint | [Webhooks](https://docs.fuul.xyz/developer-guide/webhooks) | [View](https://fuul.readme.io/reference/delete_v1-webhooks-id) | | `GET /v1/webhooks/{id}/deliveries` | View delivery history | [Webhooks](https://docs.fuul.xyz/developer-guide/webhooks) | [View](https://fuul.readme.io/reference/get_v1-webhooks-id-deliveries) | ## 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](https://docs.fuul.xyz/core-concepts/types-of-rewards/email-payouts) | [View](https://fuul.readme.io/reference/get_v1-payouts-pending-recipient-resolution) | | `POST /v1/payouts/recipient-mappings` | Create email-to-wallet mappings (up to 100/request) | [Email payouts](https://docs.fuul.xyz/core-concepts/types-of-rewards/email-payouts) | [View](https://fuul.readme.io/reference/post_v1-payouts-recipient-mappings) | ## 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](https://docs.fuul.xyz/developer-guide/build-your-incentives-hub) | [View](https://fuul.readme.io/reference/get_explorer-v1-listings-incentive-rewards-1) | | `GET /explorer/v1/listings/referral-rewards` | List referral programs ranked by payouts | [Build your hub](https://docs.fuul.xyz/developer-guide/build-your-incentives-hub) | [View](https://fuul.readme.io/reference/get_explorer-v1-listings-referral-rewards-1) | | `GET /explorer/v1/projects/{projectId}` | Get project details | [Build your hub](https://docs.fuul.xyz/developer-guide/build-your-incentives-hub) | [View](https://fuul.readme.io/reference/get_explorer-v1-projects-projectid-1) | | `GET /explorer/v1/projects/{idOrSlug}/users-count` | Get total user count for a project | [Build your hub](https://docs.fuul.xyz/developer-guide/build-your-incentives-hub) | [View](https://fuul.readme.io/reference/get_explorer-v1-projects-idorslug-users-count) | ## Public Incentives | Endpoint | What it does | Docs | API ref | | -------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `GET /v1/incentives` | List incentive programs with TVL and APR (no auth) | [Whitelabel TVL & APR](https://docs.fuul.xyz/developer-guide/whitelabel-tvl-apr) | [View](https://fuul.readme.io/reference/get_v1-incentives) |