How Referrals Work

A campaign can reserve a referral pool when it is created. Referrers then earn a share of what the users they referred (their referees) earn in that campaign, paid from that pool. This page covers the rules behind the /v1/referrals endpoints and client.referrals.*. For the step-by-step integration, see Add Referrals. For the business view (where the pool comes from and how it is sized), see Referrals in the Campaigns section.

​

The Referral Code

A referral code is the referrer’s wallet address, or their Rabbithole username. There is nothing to mint or register: a referral link just carries one of the two.

• Address. Pass it straight to referrals.bind.
• Username. Resolve it to the account’s payout wallet first with GET /v1/referrals/usernames/{username}, then bind to the address that comes back. Users can re-point their payout wallet, so resolve when you bind rather than caching it. See Accept a Username Link.

Smart-wallet proxies (Polymarket-style Safes) are canonicalized to their owner EOA on the server. Stats, proofs, and payouts always use that owner address, which can differ from the address the link carried.

​

Binding

The referee links to a referrer once by signing an EIP-712 message. The bind is global: it names no campaign and applies to every campaign on every chain. The signed domain carries no chainId, so the wallet can sign while connected to any network. The per-campaign timing check runs when each campaign’s final distribution is built. It allows five minutes of grace for a deposit that lands just before its bind, which covers the race between signing and the deposit confirming. It does not cover a referee who deposited hours ago. The signature carries a deadline in unix seconds. The SDK defaults it to ten minutes from now and rejects anything more than an hour out (REFERRAL_BIND_MAX_DEADLINE_SECONDS) before asking the wallet to sign.

​

Earnings

A referrer earns 25% of what their referees earned in a campaign, scaled into that campaign’s referral pool. referrals.stats(address) returns one entry per referral campaign where at least one of the referrer’s referees first deposited after binding. All amounts are in rewardToken base units. The pool is a hard cap. When the sum of every referrer’s uncappedAmount exceeds referralPool, every payout scales down pro rata to fit. That is why amount can be less than uncappedAmount, and why an "estimated" amount moves as other referrers’ referees earn, not just your own.

​

Claiming Payouts

Referral payouts are a separate flow from reward claims. tbi.claim and tbi.claimAll do not apply.

1. Each referral campaign deploys its own ReferralDistributor contract on the reward chain, which holds the pool.
2. After the campaign finalizes, Rabbithole builds the referral merkle tree and publishes its root to the distributor. That publication starts the claim window.
3. referrals.proof(id, referrer) returns the proof, the payout amount, and the distributor’s address. It throws TbiNotFoundError until the distribution exists, which is the normal state for any campaign that is still running.
4. The claim is submitted to the TBI Manager’s claimReferral, which forwards it to the distributor. The distributor only accepts calls from the Manager, so calling it directly reverts.

Three differences from reward claims matter in a UI:

• One-shot. The proof’s amount is the full payout, claimed exactly once per campaign. It is not a cumulative total that grows over time.
• Claim window. Once the window closes, the unclaimed pool is swept back to the protocol and the payout is gone. Surface referral claims prominently and show claimWindowEnd.
• Permissionless submission. Anyone can submit the transaction; the payout always goes to the referrer named in the proof, so relayers work without special support.

claimTxHash and claimedAt lag the chain by the indexer’s confirmation delay. To decide whether a claim button should be enabled right after a claim, read claimed(referrer) on the distributor instead. See Contracts.

​

Keep Exploring