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_balance()`	Objects	`int`	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
`wait_for_next_epoch()`	Epoch	`int`	Chain & State
`list_targets()`	Targets	`ListTargetsResponse`	Targets & Challenges
`get_targets()`	Targets	`list[Target]`	Targets & Challenges
`get_model_manifests()`	Targets	`list[ModelManifest]`	Targets & Challenges
`get_challenge()`	Challenges	`ChallengeInfo`	Targets & Challenges
`list_challenges()`	Challenges	`ListChallengesResponse`	Targets & Challenges
`execute_transaction()`	Transactions	`TransactionEffects`	Transactions
`simulate_transaction()`	Transactions	`TransactionEffects`	Transactions
`get_transaction()`	Transactions	`TransactionEffects`	Transactions
`build_transfer_coin()`	Builders	`bytes`	Transactions
`build_add_stake()`	Builders	`bytes`	Transactions
`build_commit_model()`	Builders	`bytes`	Transactions
`build_submit_data()`	Builders	`bytes`	Transactions
`score()`	Scoring	`ScoreResult`	Scoring & Admin
`request_faucet()`	Faucet	`FaucetResponse`	Scoring & Admin
`commit_model()`	Convenience	`str`	Scoring & Admin
`reveal_model()`	Convenience	`None`	Scoring & Admin
`submit_data()`	Convenience	`None`	Scoring & Admin
`claim_rewards()`	Convenience	`None`	Scoring & Admin

Installation

pip install soma-sdk

Client Construction

from soma_sdk import SomaClient

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`	Yes	—	gRPC endpoint for the SOMA fullnode
`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()`)

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("http://127.0.0.1:9000")
    balance = await client.get_balance("0x1234...")
    print(f"Balance: {balance} shannons")

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_hex = 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`	No	`None`	32-byte AES key (generated if omitted)

Returns: tuple[bytes, str] — (encrypted_bytes, key_hex)

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 hex string)

Returns: bytes

commitment

Compute a Blake2b-256 hash of data.

digest = SomaClient.commitment(data)  # 64-char hex string

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

Returns: str — 64-character hex string

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