Scallop Referral

Referral Program

Earn rewards by referring users to Scallop lending protocol.

Overview

Scallop's referral program rewards:

• Referrers: Earn a percentage of referred users' fees
• Referred Users: May receive bonus rewards

How It Works

1. Referrer shares their referral address/link
2. New user binds referrer to their obligation
3. New user uses Scallop (borrows, etc.)
4. Referrer earns portion of fees
5. Referrer claims accumulated revenue

Bind Referrer

New users bind a referrer to their obligation:

tx = builder.create_tx_block()

# Bind to a referrer using their veSCA key
tx.bind_referral(
    referrer_vesca_key_id=referrer_vesca_key_id  # Referrer's veSCA key
)

result = builder.sign_and_send_tx_block(tx)

Requirements

• Referrer must have veSCA (locked SCA)
• Can only bind once per obligation
• Must bind before activity generates fees

Claim Referral Revenue

Referrers claim accumulated revenue:

tx = builder.create_tx_block()

# Claim referral revenue
revenue = tx.claim_referral_revenue(
    vesca_key_id=ve_sca_key_id,  # Your veSCA key
    coin_name="sca",              # Reward token type
)

tx.transfer_objects([revenue], wallet_address)
result = builder.sign_and_send_tx_block(tx)

Complete Referral Flow

For Referrers

from sui_scallop_sdk import ScallopClient

client = ScallopClient(secret_key="...", network="mainnet")
builder = client.create_builder()

# Step 1: Lock SCA to get veSCA (required for referrals)
tx1 = builder.create_tx_block()
sca_coin_idx = tx1.add_object_input("0xSCA_COIN_OBJECT_ID")
ve_sca_key = tx1.lock_sca(
    sca_coin_idx=sca_coin_idx,
    lock_period_days=365,  # 1 year
)
tx1.transfer_objects([ve_sca_key], client.wallet_address)
result1 = builder.sign_and_send_tx_block(tx1)
ve_sca_key_id = parse_created_object(result1)

print(f"Your referral key: {ve_sca_key_id}")
print("Share this with users to earn referral rewards!")

# Step 2: Wait for referred users to generate fees...

# Step 3: Claim revenue
tx2 = builder.create_tx_block()
revenue = tx2.claim_referral_revenue(ve_sca_key_id, "sca")
tx2.transfer_objects([revenue], client.wallet_address)
builder.sign_and_send_tx_block(tx2)
print("Claimed referral revenue!")

For Referred Users

# Step 1: Create obligation
tx1 = builder.create_tx_block()
obligation_idx = tx1.create_obligation()
tx1.transfer_objects([obligation_idx], wallet_address)
result1 = builder.sign_and_send_tx_block(tx1)
# Parse obligation_id and obligation_key from result1.created_objects

# Step 2: Bind referrer (do this early!)
tx2 = builder.create_tx_block()
tx2.bind_referral(referrer_vesca_key_id=referrer_vesca_key_id)
builder.sign_and_send_tx_block(tx2)
print("Bound referrer")

# Step 3: Use Scallop normally
# Your referrer earns from your activity

Query Referral Data

Note: The Python SDK (sui-scallop-sdk >= 0.3.0a1) exposes referral-binding reads on ScallopQuery: get_vesca_key_id_from_referral_bindings(address), get_binded_obligation_id(vesca_key), and get_binded_vesca_key(obligation_id). As of TS v4.3.0 / Python 0.3.0a1, neither SDK has an aggregated "referral revenue" query — revenue objects must be read via query.get_object().

Revenue Calculation

referral_share = referred_user_fees * referral_rate

# Example:
# Referred user pays 100 USDC in borrow fees
# Referral rate: 10%
# Referrer earns: 10 USDC

The referrer's cut comes out of protocol fees — the referred user pays the same either way. The 10% rate is illustrative; it is a protocol parameter, so read it from state. Revenue tracks fee volume, not user count, so a bound obligation that never borrows earns nothing. See referral-mechanics.md.

Multi-Level Strategy

Build a referral network:

def share_referral_link(ve_sca_key_id):
    """Generate shareable referral info."""
    referral_info = f"""
    🔗 Scallop Referral

    Referrer veSCA Key: {ve_sca_key_id}

    How to use:
    1. Create an obligation on Scallop
    2. Call bind_referral with this veSCA key
    3. Start earning on Scallop!

    Both you and I benefit from this referral!
    """
    return referral_info

Best Practices

For Referrers

1. Lock SCA First: You need veSCA to be a referrer
2. Share Early: Users should bind before activity
3. Claim Regularly: Don't let revenue accumulate too long
4. Build Community: More referrals = more revenue

For Referred Users

1. Bind Early: Bind referrer before any activity
2. One-Time Binding: Cannot change referrer later
3. Verify Referrer: Ensure referrer's veSCA is valid

Integration Example

Website referral integration:

// Frontend code
async function handleReferral(referrerVeScaKey) {
  // Get from URL params: ?ref=0x123...
  const urlParams = new URLSearchParams(window.location.search);
  const referrerKey = urlParams.get('ref');

  if (referrerKey) {
    // Store for later binding
    localStorage.setItem('referrer', referrerKey);
  }
}

async function bindReferrerOnObligationCreate(obligationId) {
  const referrerKey = localStorage.getItem('referrer');

  if (referrerKey) {
    // Bind referrer to new obligation
    const tx = builder.createTxBlock();
    tx.bindReferral(obligationId, referrerKey);
    await builder.signAndSendTxBlock(tx);
  }
}

Error Handling

References

• Referral Mechanics - How referrals work
• veSCA - Required for referrers