SDK Reference
Python SDK
Pre-launch
Section
SDK Reference
Documentation category
Type
Guide
Technical reference
Summary
Complete reference for the SwssChain Python SDK including installation, client setup, transaction handling, Deed settlement, and async support.
SWSS Foundation Notice

This documentation is restricted to authorised members of the SWSS Developer Community. Access is granted exclusively through SWSS DevHub, after KYB and SWSS Foundation approval.

All SwssChain GitHub repositories are private. Significant updates are currently deploying across the full SWSS Ecosystem. SDK and API specifications are subject to change at any time in accordance with security requirements and SwssChain Foundation governance decisions.

Join SWSS DevHub →Have a question? Use the Need Help? button below.
SDK Update Notice

SWSS SDK v2.1 is deploying across the ecosystem. API signatures may change during this period. Ensure your integration uses the latest schema from SWSS DevHub.

Article Content

Python SDK

The swsschain-sdk Python package provides both synchronous and asynchronous interfaces to the SwssChain network. The synchronous client uses requests under the hood; the async client uses aiohttp. Both expose identical method signatures, differing only in whether calls are awaited.

Installation

pip install swsschain-sdk

# With async support (includes aiohttp)
pip install swsschain-sdk[async]

# With all extras
pip install swsschain-sdk[async,dev]

Python 3.9 or later is required. The package has been tested on CPython 3.9 to 3.13 and PyPy 3.10.

Synchronous Client

from swsschain import SwssChain, networks
import os

client = SwssChain(
    network=networks.testnet,           # or networks.mainnet
    private_key=os.environ['PRIVATE_KEY'],
    rpc_url=os.environ['SWSSCHAIN_TESTNET_RPC_URL'],  # optional override, issued by SWSS DevHub
)

# Check connection
block = client.get_block_number()
print(f'Connected. Current block: {block}')

Reading Chain State

# Current block number
block_number = client.get_block_number()

# Block details
block = client.get_block(block_number)
print(block.hash, block.timestamp, len(block.transactions))

# Account balance
balance = client.get_balance('0xYourAddress')
print(client.format_swss_coin(balance), 'SWSS')

# Transaction
tx = client.get_transaction('0xTxHash')
print(tx.from_address, tx.to_address, tx.value)

# Transaction receipt
receipt = client.get_transaction_receipt('0xTxHash')
print(receipt.status)  # 'success' or 'reverted'
print(receipt.block_number, receipt.gas_used)

Sending Transactions

from swsschain import SwssChain, networks
from decimal import Decimal
import os

client = SwssChain(
    network=networks.mainnet,
    private_key=os.environ['PRIVATE_KEY'],
)

# Parse human-readable SWSS Coin amount to wei
amount_wei = client.parse_swss_coin(Decimal('2.5'))  # 2.5 SWSS

# Send transaction
tx_hash = client.send_transaction(
    to='0xRecipientAddress',
    value=amount_wei,
    gas_limit=21000,  # optional; auto-estimated if omitted
)

print(f'Submitted: {tx_hash}')

# Wait for receipt (blocks until confirmed or timeout)
receipt = client.wait_for_transaction(tx_hash, timeout=30)
print(f'Confirmed in block {receipt.block_number}')

Contract Interaction

from swsschain import SwssChain, networks

ABI = [
    {
        "name": "balanceOf",
        "type": "function",
        "stateMutability": "view",
        "inputs": [{"name": "account", "type": "address"}],
        "outputs": [{"name": "", "type": "uint256"}]
    },
    {
        "name": "transfer",
        "type": "function",
        "inputs": [
            {"name": "to", "type": "address"},
            {"name": "amount", "type": "uint256"}
        ],
        "outputs": [{"name": "", "type": "bool"}]
    }
]

client = SwssChain(network=networks.mainnet)
contract = client.get_contract(
    address='0xContractAddress',
    abi=ABI,
)

# Read call (no gas)
balance = contract.functions.balance_of('0xHolderAddress').call()
print(f'Balance: {balance}')

# Write call (requires private key)
tx_hash = contract.functions.transfer(
    '0xRecipientAddress',
    10 ** 18  # 1 token (18 decimals)
).send()

Deed Settlement

from swsschain import SwssChain, networks, DeedType
from decimal import Decimal
import os

client = SwssChain(
    network=networks.mainnet,
    private_key=os.environ['PRIVATE_KEY'],
)

# Submit a Home Deed settlement
settlement = client.deed.submit(
    deed_type=DeedType.HOME_DEED,
    property_id='PROP-2025-00142',
    parcel_ref='SG-00142-A',
    settlement_value=client.parse_swss_coin(Decimal('250000')),
    from_address='0xSellerAddress',
    to_address='0xBuyerAddress',
    metadata={
        'jurisdiction': 'SG',
        'registration_ref': 'REF-2025-00142',
    },
)

print(f'Settlement ID: {settlement.id}')
print(f'Transaction hash: {settlement.tx_hash}')

# Wait for Finality Certificate
certificate = client.deed.get_finality_certificate(
    settlement.id,
    wait_timeout=60,  # seconds
)
print(f'Certificate hash: {certificate.certificate_hash}')
print(f'Signatures: {len(certificate.signatures)}')

Asynchronous Client

import asyncio
from swsschain.async_client import AsyncSwssChain, networks
import os

async def main():
    async with AsyncSwssChain(
        network=networks.mainnet,
        private_key=os.environ['PRIVATE_KEY'],
    ) as client:
        block = await client.get_block_number()
        print(f'Block: {block}')

        # Concurrent requests — much faster than sequential
        balance, tx_count = await asyncio.gather(
            client.get_balance('0xAddress'),
            client.get_transaction_count('0xAddress'),
        )
        print(f'Balance: {client.format_swss_coin(balance)} SWSS')
        print(f'Nonce: {tx_count}')

asyncio.run(main())

WebSocket Subscriptions

import asyncio
from swsschain.async_client import AsyncSwssChain, networks

async def handle_blocks():
    async with AsyncSwssChain(
        network=networks.mainnet,
        ws_url=os.environ['SWSSCHAIN_WS_URL'],
    ) as client:
        async for block in client.subscribe_to_blocks():
            print(f'New block: {block.number} | txs: {len(block.transactions)}')
            # Break after 10 blocks for this example
            if block.number % 10 == 0:
                break

asyncio.run(handle_blocks())

Error Handling

from swsschain.exceptions import (
    SwssChainError,
    RpcError,
    DeedError,
    InsufficientFundsError,
    TransactionRevertedError,
)

try:
    tx_hash = client.send_transaction(to='0x...', value=10**18)
except InsufficientFundsError as e:
    print(f'Not enough SWSS Coin: {e}')
except DeedError as e:
    print(f'Deed settlement failed — code {e.code}: {e.message}')
except RpcError as e:
    print(f'RPC error {e.code}: {e.message}')
except SwssChainError as e:
    print(f'SDK error: {e}')
    raise

Configuration Reference

Parameter Type Default Description
networkNetworkrequiredNetwork configuration object
private_keystrNoneAccount private key for signing
rpc_urlstrnetwork defaultOverride RPC endpoint
ws_urlstrnetwork defaultWebSocket endpoint for subscriptions
timeoutint30Default request timeout in seconds
max_retriesint3Retry count for transient RPC failures