Python SDK Reference

Quick Reference

Method	Category	Returns	Page
`Keypair.generate()`	Keypair	`Keypair`	Keypair
`Keypair.from_secret_key()`	Keypair	`Keypair`	Keypair
`Keypair.from_mnemonic()`	Keypair	`Keypair`	Keypair
`get_chain_identifier()`	Chain	`str`	Chain & State
`get_server_version()`	Chain	`str`	Chain & State
`get_protocol_version()`	Chain	`int`	Chain & State
`get_architecture_version()`	Chain	`int`	Chain & State
`get_embedding_dim()`	Chain	`int`	Chain & State
`get_model_min_stake()`	Chain	`int`	Chain & State
`check_api_version()`	Chain	`None`	Chain & State
`get_object()`	Objects	`ObjectRef`	Chain & State
`get_object_with_version()`	Objects	`ObjectRef`	Chain & State
`get_balance()`	Objects	`float`	Chain & State
`list_owned_objects()`	Objects	`list[ObjectRef]`	Chain & State
`get_latest_system_state()`	System	`SystemState`	Chain & State
`get_epoch()`	System	`EpochInfo`	Chain & State
`get_latest_checkpoint()`	Checkpoints	`CheckpointSummary`	Chain & State
`get_checkpoint_summary()`	Checkpoints	`CheckpointSummary`	Chain & State
`wait_for_next_epoch()`	Epoch	`int`	Chain & State
`get_next_epoch_timestamp()`	Epoch	`int`	Chain & State
`get_following_epoch_timestamp()`	Epoch	`int`	Chain & State
`list_targets()`	Targets	`ListTargetsResponse`	Targets
`get_targets()`	Targets	`list[Target]`	Targets
`get_model_manifests()`	Targets	`list[ModelManifest]`	Targets
`fetch_model()`	Targets	`bytes`	Targets
`fetch_submission_data()`	Targets	`bytes`	Targets
`execute_transaction()`	Transactions	`TransactionEffects`	Transactions
`simulate_transaction()`	Transactions	`TransactionEffects`	Transactions
`get_transaction()`	Transactions	`TransactionEffects`	Transactions
`create_model()`	Models	`str`	Scoring & Admin
`commit_model()`	Models	`None`	Scoring & Admin
`reveal_model()`	Models	`None`	Scoring & Admin
`deactivate_model()`	Models	`None`	Scoring & Admin
`set_model_commission_rate()`	Models	`None`	Scoring & Admin
`report_model()`	Models	`None`	Scoring & Admin
`undo_report_model()`	Models	`None`	Scoring & Admin
`submit_data()`	Submissions	`None`	Scoring & Admin
`claim_rewards()`	Submissions	`None`	Scoring & Admin
`report_submission()`	Submissions	`None`	Scoring & Admin
`undo_report_submission()`	Submissions	`None`	Scoring & Admin
`score()`	Scoring	`ScoreResult`	Scoring & Admin
`transfer_coin()`	Transfers	`None`	Scoring & Admin
`transfer_objects()`	Transfers	`None`	Scoring & Admin
`pay_coins()`	Transfers	`None`	Scoring & Admin
`request_faucet()`	Admin	`FaucetResponse`	Scoring & Admin
`add_stake()`	Staking	`None`	Scoring & Admin
`withdraw_stake()`	Staking	`None`	Scoring & Admin
`add_stake_to_model()`	Staking	`None`	Scoring & Admin

Installation

pip install soma-sdk

Client Construction

Use named presets for common networks:

from soma_sdk import SomaClient

client = await SomaClient(chain="testnet")    # testnet with faucet
client = await SomaClient(chain="localnet")   # local dev with all services

Or provide explicit URLs:

client = await SomaClient(
    rpc_url="http://127.0.0.1:9000",
    scoring_url="http://127.0.0.1:9124",
    faucet_url="http://127.0.0.1:9123",
)

Parameter	Type	Required	Default	Description
`rpc_url`	`str`	No	-	gRPC endpoint for the SOMA fullnode
`chain`	`str`	No	`None`	Network preset (`"testnet"` or `"localnet"`)
`scoring_url`	`str`	No	`None`	Scoring service URL (required for `score()`)
`admin_url`	`str`	No	`None`	Admin endpoint (required for `advance_epoch()`)
`faucet_url`	`str`	No	`None`	Faucet endpoint (required for `request_faucet()`)

Provide either chain or rpc_url, not both. The constructor is async. Use await to initialize the client.

Async Patterns

All query and transaction methods are async. Use asyncio.run() for scripts:

import asyncio
from soma_sdk import SomaClient

async def main():
    client = await SomaClient(chain="localnet")
    balance = await client.get_balance("0x1234...")
    print(f"Balance: {balance} SOMA")

asyncio.run(main())

Static Methods

These methods are available on SomaClient without instantiation.

encrypt_weights

Encrypt data with AES-256-CTR (zero IV). If no key is provided, one is generated.

encrypted, key_base58 = SomaClient.encrypt_weights(data)
encrypted_with_key, _ = SomaClient.encrypt_weights(data, key=my_key)

Parameter	Type	Required	Default	Description
`data`	`bytes`	Yes	-	Raw data to encrypt
`key`	`bytes \| str`	No	`None`	32-byte AES key as bytes or Base58 string (generated if omitted)

Returns: tuple[bytes, str]. (encrypted_bytes, key_base58).

decrypt_weights

Decrypt data encrypted with encrypt_weights.

decrypted = SomaClient.decrypt_weights(encrypted, key_hex)

Parameter	Type	Required	Default	Description
`data`	`bytes`	Yes	-	Encrypted data
`key`	`bytes \| str`	Yes	-	AES key (bytes or Base58 string)

Returns: bytes

commitment

Compute a Blake2b-256 hash of data.

digest = SomaClient.commitment(data)  # Base58 string

Parameter	Type	Required	Default	Description
`data`	`bytes`	Yes	-	Data to hash

Returns: str. Base58-encoded Blake2b-256 hash.

to_shannons

Convert SOMA to shannons (1 SOMA = 1,000,000,000 shannons).

shannons = SomaClient.to_shannons(1.5)  # 1_500_000_000

to_soma

Convert shannons to SOMA.

soma = SomaClient.to_soma(1_500_000_000)  # 1.5