Skip to main content

Referrals

The DeepBook referral system allows users to earn fees by referring traders to the platform. Referrers can mint a DeepBookPoolReferral object for a specific pool, and traders can associate their BalanceManager with a referral. When traders with an associated referral execute trades, a portion of their trading fees is allocated to the referrer based on the referral multiplier.

How referrals work​

  1. Mint a referral: Anyone can mint a DeepBookPoolReferral for a specific pool with a specified multiplier. The referral permanently ties to the pool you minted it from and can only earn fees from trades in that pool.
  2. Set referral: Traders associate their BalanceManager with a pool-specific referral using a TradeCap. Each BalanceManager can be associated with different referrals from different pools simultaneously.
  3. Earn fees: When the balance manager executes taker orders in that pool, the system automatically allocates referral fees based on the multiplier. Maker orders do not generate referral fees.
  4. Claim rewards: Referrers can claim their accumulated fees in base, quote, and DEEP tokens.

API​

The following are the referral-related functions that DeepBook exposes.

Click to open
Mint a referral

Mint a new DeepBookPoolReferral object for a specific pool with a given multiplier. The multiplier determines the portion of trading fees allocated to the referrer. The multiplier must be a multiple of 0.1 (such as 0.1, 0.2, or 0.3) and cannot exceed 2.0. Returns the ID of the created referral.

Click to open
Update referral multiplier

Update the multiplier for an existing pool referral. Only the referral owner can update the multiplier. The new multiplier must be a multiple of 0.1 and cannot exceed 2.0.

Click to open
Claim referral rewards

Claim your accumulated referral fees for a pool referral. Only you, as the referral owner, can claim rewards. Returns three Coin objects representing the accumulated fees in base asset, quote asset, and DEEP tokens.

Click to open
Get referral balances

View the current accumulated balances for a pool referral without claiming them. Returns the amounts in base, quote, and DEEP tokens.

Click to open
Get referral multiplier

Get the current multiplier for a pool referral.

BalanceManager referral functions​

These functions are available on the BalanceManager to associate or disassociate a referral.

Click to open
Set referral

Associate a BalanceManager with a pool-specific referral. Requires a TradeCap to authorize the operation. Once set, all trades that this balance manager executes in the referral's pool generate referral fees according to the referral's multiplier. This replaces any previously set referral for the same pool.

Click to open
Unset referral

Remove the referral association from a BalanceManager for a specific pool. Requires a TradeCap to authorize the operation. After unsetting, trades in that pool no longer generate referral fees.

Click to open
Get referral ID

Retrieve the referral ID currently associated with a BalanceManager for a specific pool, if any. Returns Option<ID> which is none if no referral is set for that pool.

Click to open
Get referral owner

Get the owner address of a pool referral object.

Click to open
Get referral pool ID

Get the pool ID associated with a pool referral object.

Events​

Click to open
DeepBookReferralCreatedEvent

The system emits this event when you mint a new referral.

Click to open
DeepBookReferralSetEvent

The system emits this event when you set or unset a referral on a balance manager.

Click to open
ReferralClaimed

The system emits this event when the referral owner claims accumulated fees.

Click to open
ReferralFeeEvent

The system emits this event when it allocates referral fees during trade execution.