Referral Fee Share Claim Tool

WHAT IT DOES

This tool enables DeFi protocol users, community members, and referrers to claim referral fees they have earned by referring new users to a protocol or application. It connects to your wallet and reads the referral contract address, referrer address, referred users count, referral fee balance, claimable amount, fee rate, referral history, last claim timestamp, claim window, and eligibility status. The tool signs and submits transactions to claim referral fees, transfer fee tokens to the user's wallet, update claim status, record claim metadata with timestamps, and emit claim events for transparency.

HOW TO USE

1. Connect your wallet using the wallet bridge (supports MetaMask, WalletConnect, and other EVM-compatible wallets).

2. Select the target network that matches your referral contract deployment.

3. Enter the referral contract address and the fee token address (use 0x0 for native token fees), then click "load contract" to initialize the connection.

4. Click "fetch claim data" to retrieve your current referral fee balance, claimable amount, fee rate, referred users count, last claim timestamp, claim window, and eligibility status.

5. Review the displayed information including your claimable amount in native token equivalents, fee rate (e.g., 2.5%), and number of referred users.

6. If you are eligible and have a claimable amount greater than zero, the claim button will become active.

7. Click "claim referral fees" to sign and submit the transaction that transfers your accrued referral fees to your wallet.

8. The claim history section will update to show your previous claims including amounts and transaction hashes.

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 to interact with any EVM-compatible referral contract that implements a standard interface (getReferrer(address) view, getReferredCount(address) view, getFeeBalance(address) view, claimableAmount(address) view, getFeeRate(address) view, getLastClaim(address) view, getClaimWindow(address) view, isEligible(address) view, claimReferralFees(address) external, getClaimHistory(address) view, getReferralHistory(address) view). It reads on-chain state directly from the contract rather than relying on off-chain indexes, ensuring data freshness and accuracy. The claimable amount is computed on-chain by the contract, typically as (referred_user_fees * fee_rate) minus previously claimed amounts, ensuring referrers can only claim what they have rightfully earned. The claim function supports both native token fees (using 0x0 address) and ERC-20 fee tokens, providing flexibility for different program designs. Transaction handling follows EIP-1559 gas price calculations using receipt.effectiveGasPrice for accurate cost reporting. Claim metadata, including amounts and timestamps, is recorded in the contract's claim history mapping, providing an auditable trail of all claims. Referral history tracking allows referrers to see which users they have referred.

WHAT IT CANNOT SEE

This tool operates purely on-chain and cannot verify off-chain referral accuracy — it relies on the contract's internal referral tracking, which may not capture all referral relationships if users were referred through off-chain channels. It cannot validate referral relationships — the tool does not check that referred users actually completed required actions, made qualifying transactions, or met participation criteria. The tool cannot detect sybil accounts, identity fraud, or duplicate referrals that might unfairly claim referral fees. It cannot ensure fair fee distribution — the tool does not verify that the fee rate is appropriate or that referrals are genuine. The tool also cannot verify that referred users actually generated the fees being shared — all referral and fee data is accepted from the contract and may reflect activity from users who were not genuinely referred.

PLEASE NOTE

This tool works exclusively with EVM-compatible blockchain networks (Ethereum, Polygon, Arbitrum, Optimism, Base, etc.). It requires the referral contract to implement the interface described above. All transactions incur gas fees paid by the connected wallet. The tool maintains no persistent storage — all state is refreshed from the blockchain on each session. Always verify your claimable amount and eligibility before claiming, and ensure your wallet has sufficient native tokens to pay the claim transaction gas fees. For production deployments, ensure your referral contract has been professionally audited and that referral tracking is resistant to gaming.