# Scallop Client Setup

> Initialize and configure the Scallop Python SDK client. Use when user says "setup Scallop", "initialize client", "ScallopClient", "ScallopConfig", "connect to Scallop", "configure SDK", "environment variables", "network config", "mainnet", "testnet", or asks about setting up, installing, or configuring the sui-scallop-sdk Python SDK.

- Skill: `scallop-io/scallop-client-setup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add scallop-io/scallop-client-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/scallop-io/scallop-client-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: scallop-io (https://skillmd.com/u/scallop-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/scallop-io/scallop-client-setup

---


# Client Setup & Configuration

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

## Installation

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

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

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

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

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

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

## ScallopConfig

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

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

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

# Transaction builder
builder = client.create_builder()
```

### Convenience Methods

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

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

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

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

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

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

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

```python
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](../../references/addresses.md) - Protocol contract addresses
- [Crypto Keys](../scallop-crypto-keys/SKILL.md) - Key generation and formats
- [Sui Basics](../../references/sui-basics.md) - Sui blockchain fundamentals