Scallop client setup

Client Setup & Configuration

Install, initialize, and configure the Scallop Python SDK (sui-scallop-sdk).

Installation

pip install --pre sui-scallop-sdk

Requires Python 3.10+. The current release is 0.3.0a1, an alpha pre-release, so --pre (or an explicit sui-scallop-sdk==0.3.0a1) is required — a plain pip install sui-scallop-sdk resolves no release.

Quick Start

from sui_scallop_sdk import ScallopClient

# Minimal setup (read-only queries)
client = ScallopClient(network="mainnet")

# With wallet (for transactions)
client = ScallopClient(
    secret_key="suiprivkey1...",  # or hex, or base64
    network="mainnet",
)

ScallopClient Constructor

ScallopClient(
    network: str = "mainnet",         # "mainnet", "testnet", or "devnet"
    rpc_url: str | None = None,       # Custom RPC endpoint (overrides default)
    wallet_address: str | None = None, # Default wallet for queries
    secret_key: str | bytes | None = None,  # Private key (auto-derives address)
)

When secret_key is provided, the client automatically:

1. Creates a SuiKeypair from the key
2. Derives the wallet address
3. Enables transaction signing

Key Formats Accepted

The secret_key parameter accepts multiple formats:

Format	Example
Bech32	suiprivkey1qp...
Hex	0x1a2b3c... (64 hex chars)
Base64	Gis7... (32 or 33 bytes encoded)
Raw bytes	b'\x1a\x2b...' (32 bytes)

Alternative Constructors

From Config Object

from sui_scallop_sdk import ScallopConfig

config = ScallopConfig(
    network="mainnet",
    rpc_url="https://my-custom-rpc.com",
)

# Note: from_config() only passes network and rpc_url to the client.
# For signing, pass secret_key directly to ScallopClient constructor instead.
client = ScallopClient.from_config(config)

From Environment Variables

# Set environment variables first:
# NETWORK=mainnet
# PRIVATE_KEY=suiprivkey1...
# MNEMONIC=word1 word2 ...  (alternative to PRIVATE_KEY)
# RPC_URL=https://my-rpc.com  (optional)

client = ScallopClient.from_env()

Or using ScallopConfig:

config = ScallopConfig.from_env()
client = ScallopClient.from_config(config)

ScallopConfig

from dataclasses import dataclass

@dataclass
class ScallopConfig:
    network: str = "mainnet"          # Network name
    secret_key: str | None = None     # Private key
    mnemonic: str | None = None       # Mnemonic phrase (alternative to secret_key)
    rpc_url: str | None = None        # Custom RPC URL
    addresses: ScallopAddresses       # Protocol addresses (auto-set from network)

Methods:

• ScallopConfig.from_env() — Load from environment variables (NETWORK, PRIVATE_KEY, MNEMONIC, RPC_URL)
• config.validate() — Verify credentials are present (either secret_key or mnemonic), raises ValueError if neither is set

Client Properties

client.network          # str: "mainnet", "testnet", or "devnet"
client.addresses        # ScallopAddresses: all protocol contract addresses
client.wallet_address   # str | None: derived from secret_key or explicitly set
client.rpc_client       # SuiRpcClient: underlying RPC connection
client.keypair          # SuiKeypair | None: signing keypair

Client Methods

Creating Interfaces

# Query interface (read-only)
query = client.create_query()

# Transaction builder
builder = client.create_builder()

Convenience Methods

# Get obligation (shortcut for query.get_obligation)
obligation = client.get_obligation(obligation_id)

# Get balance
balance = client.get_balance(
    address=wallet_address,  # Optional, defaults to client.wallet_address
    coin_type=coin_type,     # Optional, defaults to SUI
)

# List all obligations
obligation_ids = client.list_obligations(address=wallet_address)

Setting Keypair After Init

from sui_scallop_sdk import SuiKeypair

# Generate a new keypair
keypair = SuiKeypair.generate()
client.set_keypair(keypair)

# Or from an existing key
keypair = SuiKeypair.from_bech32("suiprivkey1...")
client.set_keypair(keypair)

Context Manager

ScallopClient supports with statements for automatic cleanup:

with ScallopClient(secret_key="...", network="mainnet") as client:
    query = client.create_query()
    balance = query.get_balance(client.wallet_address)
    print(f"Balance: {balance}")
# HTTP connections automatically closed

Or manually:

client = ScallopClient(network="mainnet")
try:
    # ... use client
finally:
    client.close()

Network Configuration

Supported Networks

Network	RPC Default	Use Case
mainnet	Sui mainnet RPC	Production
testnet	Sui testnet RPC	Development, testing
devnet	Sui devnet RPC	Experimental

Custom RPC

client = ScallopClient(
    network="mainnet",
    rpc_url="https://my-premium-rpc.example.com",
)

Protocol Addresses

Protocol addresses are pre-configured per network in ScallopAddresses. Key fields:

addresses = client.addresses

addresses.protocol_package     # Core protocol package ID
addresses.market_object        # Market object ID
addresses.version_object       # Version object ID
addresses.x_oracle             # X Oracle object
addresses.spool_package        # Staking pool package
addresses.vesca_package        # veSCA package
addresses.scoin_package        # sCoin package
addresses.referral_package     # Referral package
addresses.loyalty_package      # Loyalty package
# ... and many more

Complete Setup Pattern

import os
from sui_scallop_sdk import ScallopClient

def create_client() -> ScallopClient:
    """Create Scallop client from environment."""
    secret_key = os.environ.get("PRIVATE_KEY")
    network = os.environ.get("NETWORK", "mainnet")
    rpc_url = os.environ.get("RPC_URL")

    client = ScallopClient(
        secret_key=secret_key,
        network=network,
        rpc_url=rpc_url,
    )

    print(f"Connected to {client.network}")
    if client.wallet_address:
        print(f"Wallet: {client.wallet_address}")

    return client

# Usage
with create_client() as client:
    query = client.create_query()
    builder = client.create_builder()

    # Read-only operations
    markets = query.get_market_data()

    # Transaction operations (requires secret_key)
    tx = builder.create_tx_block()
    # ...

Error Handling

from sui_scallop_sdk.exceptions import ScallopConfigError, NetworkError

try:
    client = ScallopClient(
        secret_key="invalid_key",
        network="mainnet",
    )
except ScallopConfigError as e:
    print(f"Config error: {e}")
except NetworkError as e:
    print(f"Network error: {e} (RPC: {e.rpc_url})")

References

• Addresses - Protocol contract addresses
• Crypto Keys - Key generation and formats
• Sui Basics - Sui blockchain fundamentals