# Scallop Referral

> Scallop referral program. Use when user says "referral", "refer a friend", "referral revenue", "bind referrer", "referral code", or asks about Scallop's referral rewards.

- Skill: `scallop-io/scallop-referral` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add scallop-io/scallop-referral`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scallop-io/scallop-referral/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Finance & Business
- License: MIT
- Author: scallop-io (https://skillmd.com/u/scallop-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/scallop-io/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:

```python
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:

```python
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

```python
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

```python
# 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

```python
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](references/referral-mechanics.md).

## Multi-Level Strategy

Build a referral network:

```python
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:

```javascript
// 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

| Error | Cause | Solution |
|-------|-------|----------|
| `ReferrerNotVeSCA` | Invalid referrer key | Use valid veSCA key |
| `AlreadyBound` | Referrer already set | Cannot rebind |
| `NoRevenueToClaim` | No pending revenue | Wait for activity |

## References

- [Referral Mechanics](references/referral-mechanics.md) - How referrals work
- [veSCA](../scallop-vesca/SKILL.md) - Required for referrers