Scallop Python SDK

A Python SDK for interacting with the Scallop Lending Protocol on Sui blockchain.

English | 繁體中文

Features

Core Lending Operations

• Supply/Withdraw: supply, withdraw (supply assets to earn interest)
• Borrow/Repay: borrow, repay
• Collateral Management: deposit_collateral, withdraw_collateral
• Liquidation: liquidate
• Flash Loans: borrow_flash_loan, repay_flash_loan

Quick Methods

• Auto Coin Selection: supply_quick, withdraw_quick, repay_quick
• Auto Price Update: borrow_quick, liquidate_quick
• Oracle Update: update_asset_prices_quick
• veSCA Lifecycle Helpers: lock_sca_quick, extend_lock_period_quick, extend_lock_amount_quick, renew_expired_vesca_quick, redeem_sca_quick, split_vesca_quick, merge_vesca_quick

Advanced Features

• Staking Pool (Spool): Stake market coins for rewards
• sCoin: Mint/burn sCoin
• veSCA: Lock SCA for veSCA
• Borrow Incentive: Stake obligations for rewards
• Referral: Referral system
• Loyalty Program: Loyalty rewards

Infrastructure

• Cryptography: Ed25519 signing, address derivation, Bech32 key import (suiprivkey1...)
• BCS Serialization: Full transaction serialization support (mainnet verified)
• Oracle Integration: Pyth + X Oracle

Installation

pip install sui-scallop-sdk

# Or install from source
git clone https://github.com/scallop-io/sui-scallop-sdk-python
cd sui-scallop-sdk-python
pip install -e .

Quick Start

Query Obligation

from sui_scallop_sdk import ScallopClient

# Initialize client
client = ScallopClient(network="mainnet")

# Query obligation
query = client.create_query()
obligation = query.get_obligation("0x...")

print(f"Risk Level: {obligation.risk_level}")
print(f"Is Liquidatable: {obligation.is_liquidatable}")
print(f"Total Debt USD: ${obligation.total_debt_usd}")
print(f"Total Collateral USD: ${obligation.total_collateral_usd}")

Query Market And TVL

from sui_scallop_sdk import ScallopClient

client = ScallopClient(network="mainnet")
query = client.create_query()

pool = query.get_market_pool("sui")
collateral = query.get_market_collateral("sui")
pool_address = query.get_pool_address("sui")
tvl = query.get_tvl()
prices = query.get_coin_prices(["sui", "sca", "usdc"])

print(pool.supply_amount, pool.borrow_amount, pool.supply_apy)
print(collateral.deposit_amount, collateral.collateral_factor)
print(pool_address.lending_pool_address, pool_address.flash_loan_fee_object)
print(tvl.total_value)
print(prices)

Query Portfolio And Lendings

from sui_scallop_sdk import ScallopClient

client = ScallopClient.from_env()
query = client.create_query()

portfolio = query.get_user_portfolio(client.wallet_address)
lendings = query.get_lendings(client.wallet_address)

print(portfolio.total_supply_value, portfolio.total_borrow_value, portfolio.net_apy)
print(portfolio.obligations)
print(lendings)

Query Spool, sCoin, veSCA, And Loyalty

from sui_scallop_sdk import ScallopClient

client = ScallopClient.from_env()
query = client.create_query()

spool = query.get_spool("ssui")
scoin_supply = query.get_scoin_total_supply("sui")
scoin_amounts = query.get_scoin_amounts(["ssui", "susdc"], client.wallet_address)
vescas = query.get_vescas(client.wallet_address, exclude_empty=True)

print(spool.reward_apr if spool else None)
print(scoin_supply, scoin_amounts)

if vescas:
    loyalty = query.get_loyalty_program_info(vescas[0].key_id)
    vesca_loyalty = query.get_vesca_loyalty_program_info(vescas[0].key_id)
    print(vescas[0].locked_sca_amount, vescas[0].current_vesca_balance)
    print(loyalty.pending_reward, vesca_loyalty.pending_vesca_reward)

For a runnable walkthrough, see examples/query_example.py.

Supply (Earn Interest)

from sui_scallop_sdk import ScallopClient

# Initialize with wallet credentials
# Supports: suiprivkey1... (bech32), base64, hex, or raw bytes
client = ScallopClient(
    secret_key="suiprivkey1...",
    network="mainnet",
)

# Create transaction
builder = client.create_builder()
tx = builder.create_tx_block()

# Supply 1 SUI to lending pool
market_coin_idx = tx.supply(coin_input_idx=0, coin_name="sui")
tx.transfer_objects([market_coin_idx], client.wallet_address)

# Execute
result = builder.sign_and_send_tx_block(tx)

if result.success:
    print(f"Success! TX: {result.digest}")
else:
    print(f"Failed: {result.error}")

Quick Supply (Auto Coin Selection)

tx = builder.create_tx_block()

# Use supply_quick for automatic coin selection
market_coin_idx = tx.supply_quick(
    amount=1_000_000_000,  # 1 SUI (9 decimals)
    coin_name="sui",
    sender=client.wallet_address
)
tx.transfer_objects([market_coin_idx], client.wallet_address)

result = builder.sign_and_send_tx_block(tx)

Initialize From Environment

export NETWORK=mainnet
export PRIVATE_KEY="suiprivkey1..."
# Optional when you want to override the derived address
export WALLET_ADDRESS="0x..."

from sui_scallop_sdk import ScallopClient

client = ScallopClient.from_env()

PRIVATE_KEY is supported for config-driven initialization. MNEMONIC is not yet supported.

Borrow

tx = builder.create_tx_block()

# Borrow with automatic oracle price update
borrowed_coin_idx = tx.borrow_quick(
    amount=100_000_000,  # 100 USDC (6 decimals)
    coin_name="usdc",
    obligation_id="0x...",
    obligation_key="0x...",
)
tx.transfer_objects([borrowed_coin_idx], client.wallet_address)

result = builder.sign_and_send_tx_block(tx)

Repay

tx = builder.create_tx_block()

# Auto coin selection for repay
tx.repay_quick(
    amount=50_000_000,  # Repay 50 USDC
    coin_name="usdc",
    obligation_id="0x...",
    sender=client.wallet_address,
)

result = builder.sign_and_send_tx_block(tx)

Flash Loan

tx = builder.create_tx_block()

# Borrow flash loan (returns TxResult objects for PTB tuple outputs)
coin_result, receipt_result = tx.borrow_flash_loan(
    amount=1_000_000_000,  # 1 SUI
    coin_name="sui"
)

# ... perform arbitrage or other operations ...

# Repay (must be in same transaction, includes fee)
tx.repay_flash_loan(coin_result, receipt_result, "sui")

result = builder.sign_and_send_tx_block(tx)

Liquidation

tx = builder.create_tx_block()

# Auto coin selection liquidation (auto updates oracle prices)
remaining_debt_idx, collateral_idx = tx.liquidate_quick(
    obligation_id="0x...",
    repay_amount=100_000_000,  # 100 USDC
    debt_coin_name="usdc",
    collateral_coin_name="sui",
    sender=client.wallet_address,
)

# Transfer received collateral
tx.transfer_objects(
    [{"kind": "NestedResult", "index": collateral_idx, "resultIndex": 1}],
    client.wallet_address,
)

result = builder.sign_and_send_tx_block(tx)

Advanced Features

Spool Staking

tx = builder.create_tx_block()

# Create stake account
stake_account_idx = tx.create_stake_account(stake_pool_id, "sui")

# Stake market coin
tx.stake_spool(
    stake_account_id="0x...",
    stake_pool_id="0x...",
    coin_input_idx=market_coin_idx,
    coin_name="sui"
)

# Claim rewards
reward_idx = tx.claim_spool_rewards(
    stake_account_id="0x...",
    stake_pool_id="0x...",
    reward_pool_id="0x...",
    coin_name="sca"
)
tx.transfer_objects([reward_idx], client.wallet_address)

result = builder.sign_and_send_tx_block(tx)

veSCA Lock

tx = builder.create_tx_block()

# Lock SCA to get veSCA key (365 days)
vesca_key_idx = tx.lock_sca(
    sca_coin_idx=sca_coin_input,
    lock_period_days=365
)
tx.transfer_objects([vesca_key_idx], client.wallet_address)

# Extend lock period
tx.extend_lock_period(
    vesca_key_id="0x...",
    new_unlock_at=new_unlock_timestamp  # Unix epoch in seconds
)

# Add more SCA to existing lock
tx.extend_lock_amount(
    vesca_key_id="0x...",
    sca_coin_idx=additional_sca_input
)

# Redeem SCA (after lock expires)
sca_idx = tx.redeem_sca(vesca_key_id="0x...")
tx.transfer_objects([sca_idx], client.wallet_address)

result = builder.sign_and_send_tx_block(tx)

veSCA Quick Methods

tx = builder.create_tx_block()

# Initial lock with automatic SCA coin selection
new_vesca_idx = tx.lock_sca_quick(
    amount=10_000_000_000,      # 10 SCA in raw units
    lock_period_days=365,
    sender=client.wallet_address,
)
tx.transfer_objects([new_vesca_idx], client.wallet_address)

# Extend only the lock duration of the highest-balance veSCA
tx.extend_lock_period_quick(
    lock_period_days=30,
    sender=client.wallet_address,
)

# Top up an existing veSCA with automatic coin selection
tx.extend_lock_amount_quick(
    sca_amount=1_000_000_000,   # 1 SCA in raw units
    sender=client.wallet_address,
    vesca_key_id="0x...",       # optional, defaults to the sender's highest-balance veSCA
)

# Renew an expired veSCA
tx.renew_expired_vesca_quick(
    sca_amount=10_000_000_000,
    lock_period_days=180,
    sender=client.wallet_address,
    vesca_key_id="0x...",
)

# Redeem unlocked SCA and auto-transfer it back to the sender
tx.redeem_sca_quick(
    sender=client.wallet_address,
    vesca_key_id="0x...",
)

# Split a veSCA key and auto-transfer the new key NFT
tx.split_vesca_quick(
    split_amount=5_000_000_000,
    vesca_key_id="0x...",
    sender=client.wallet_address,
)

# Merge two veSCA keys, aligning unlock times automatically when needed
tx.merge_vesca_quick(
    target_vesca_key_id="0x...",
    source_vesca_key_id="0x...",
)

result = builder.sign_and_send_tx_block(tx)

Notes:

• veSCA quick methods stay builder-first in Python, so methods that need coin selection or auto-transfer still require an explicit sender
• vesca_key_id is optional for lock_sca_quick, extend_lock_period_quick, extend_lock_amount_quick, renew_expired_vesca_quick, and redeem_sca_quick
• when vesca_key_id is omitted, the SDK uses the sender's highest-balance veSCA position
• amounts are raw on-chain units, so 1 SCA = 1_000_000_000

sCoin Operations

tx = builder.create_tx_block()

# Mint sCoin (from Market Coin)
scoin_idx = tx.mint_scoin(market_coin_idx=market_coin, coin_name="sui")
tx.transfer_objects([scoin_idx], client.wallet_address)

# Burn sCoin (get Market Coin back)
market_coin_idx = tx.burn_scoin(scoin_idx=scoin_input, coin_name="sui")
tx.transfer_objects([market_coin_idx], client.wallet_address)

result = builder.sign_and_send_tx_block(tx)

Borrow Incentive

tx = builder.create_tx_block()

# Stake obligation
tx.stake_obligation(
    obligation_id="0x...",
    obligation_key="0x..."
)

# Claim rewards
reward_idx = tx.claim_borrow_incentive(
    obligation_id="0x...",
    obligation_key="0x...",
    coin_name="sca"
)
tx.transfer_objects([reward_idx], client.wallet_address)

result = builder.sign_and_send_tx_block(tx)

Referral Program

tx = builder.create_tx_block()

# Bind to a referrer (using referrer's veSCA key ID)
tx.bind_referral(referrer_vesca_key_id="0x...")

# Claim referral rewards
reward_idx = tx.claim_referral_revenue(
    vesca_key_id="0x...",  # Your veSCA key ID
    coin_name="sui"
)
tx.transfer_objects([reward_idx], client.wallet_address)

result = builder.sign_and_send_tx_block(tx)

Loyalty Program

tx = builder.create_tx_block()

# Claim loyalty rewards
reward_idx = tx.claim_loyalty_revenue(vesca_key_id="0x...")
tx.transfer_objects([reward_idx], client.wallet_address)

result = builder.sign_and_send_tx_block(tx)

Configuration

Environment Variables

Create a .env file:

PRIVATE_KEY=suiprivkey1...  # or base64/hex format
NETWORK=mainnet
RPC_URL=https://fullnode.mainnet.sui.io:443

Then use from_env():

client = ScallopClient.from_env()

Supported Coins

Note: The supported coins list is fetched from Scallop API. Some coins may only support specific operations (lending, collateral, or borrowing). Check Scallop documentation for the latest availability.

API Reference

ScallopClient

Main entry point for SDK.

ScallopQuery

ScallopTxBlock - Core Methods

ScallopTxBlock - Quick Methods

ObligationInfo

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
make test

# Lint and format
make lint
make format

# Type checking
make typecheck

# Run all checks
make all

Mainnet Verification

All core operations have been verified on Sui mainnet (10/10 tests passed):

Total gas: ~0.027 SUI

Notes

1. Mainnet-only: Scallop is deployed on mainnet; network="testnet" / "devnet" raise ScallopConfigError rather than building transactions against placeholder addresses
2. Live addresses: Protocol package IDs change on every upgrade, and the protocol rejects calls into a superseded package, so the SDK refreshes addresses from the Scallop address API on first use. Set SCALLOP_LIVE_ADDRESSES=0 or pass resolve_live_addresses=False to pin the compiled-in values
3. Private Key Formats: Supports suiprivkey1... (Bech32), Base64, and Hex. Use environment variables instead of hardcoding
4. Gas Fees: Transactions consume SUI as gas; ensure sufficient balance. Supplying or repaying SUI is taken from the gas coin, so keep more than amount + gas_budget
5. Oracle Updates: Call update_asset_prices_quick() before borrow/liquidate operations; it raises OraclePriceError if a price cannot be posted
6. Retrying failures: check TransactionResult.error_kind — only validation and build are safe to retry blindly; submission means the transaction may already be on chain

License

Apache License 2.0 - see LICENSE for details.