Chain & State

Chain Information

get_chain_identifier

Get the unique identifier of the connected chain.

async def get_chain_identifier() -> str

Returns: str — chain identifier

get_server_version

Get the server’s software version.

async def get_server_version() -> str

Returns: str

get_protocol_version

Get the current protocol version number.

async def get_protocol_version() -> int

Returns: int

get_architecture_version

Get the current model architecture version required by the protocol.

async def get_architecture_version() -> int

Returns: int — must match ARCHITECTURE_VERSION in soma-models

get_embedding_dim

Get the required embedding dimension for the current architecture.

async def get_embedding_dim() -> int

Returns: int — e.g., 2048 for V1

get_model_min_stake

Get the minimum stake required to register a model, in shannons.

async def get_model_min_stake() -> int

Returns: int — minimum stake in shannons

check_api_version

Verify that the SDK and server API versions are compatible. Raises an exception on mismatch.

async def check_api_version() -> None

Example

await client.check_api_version()  # raises on mismatch

Objects & Balances

get_object

Fetch an on-chain object by ID.

async def get_object(object_id: str) -> ObjectRef

Parameter	Type	Required	Default	Description
object_id	str	Yes	—	Hex-encoded object ID

Returns: ObjectRef

get_object_with_version

Fetch a specific version of an on-chain object.

async def get_object_with_version(object_id: str, version: int) -> ObjectRef

Parameter	Type	Required	Default	Description
object_id	str	Yes	—	Hex-encoded object ID
version	int	Yes	—	Object version number

Returns: ObjectRef

get_balance

Get the SOMA balance for an address, in shannons.

async def get_balance(address: str) -> int

Parameter	Type	Required	Default	Description
address	str	Yes	—	SOMA address

Returns: int — balance in shannons

Example

balance = await client.get_balance("0x1234...")
print(f"{SomaClient.to_soma(balance)} SOMA")

list_owned_objects

List objects owned by an address.

async def list_owned_objects(
    owner: str,
    object_type: Optional[str] = None,
    limit: Optional[int] = None,
) -> list[ObjectRef]

Parameter	Type	Required	Default	Description
owner	str	Yes	—	Owner address
object_type	str	No	None	Filter by object type
limit	int	No	None	Maximum number of results

Returns: list[ObjectRef]

System State

get_latest_system_state

Fetch the full system state for the current epoch, including validators, parameters, and model registry.

async def get_latest_system_state() -> SystemState

Returns: SystemState

get_epoch

Get information about a specific epoch, or the current epoch if not specified.

async def get_epoch(epoch: Optional[int] = None) -> EpochInfo

Parameter	Type	Required	Default	Description
epoch	int	No	None	Epoch number (current if omitted)

Returns: EpochInfo

Checkpoints

get_latest_checkpoint

Get the most recent finalized checkpoint.

async def get_latest_checkpoint() -> CheckpointSummary

Returns: CheckpointSummary

get_checkpoint_summary

Get a checkpoint by sequence number.

async def get_checkpoint_summary(sequence_number: int) -> CheckpointSummary

Parameter	Type	Required	Default	Description
sequence_number	int	Yes	—	Checkpoint sequence number

Returns: CheckpointSummary

Epoch Helpers

wait_for_next_epoch

Block until the next epoch begins.

async def wait_for_next_epoch(timeout: float = 120.0) -> int

Parameter	Type	Required	Default	Description
timeout	float	No	120.0	Maximum seconds to wait

Returns: int — the new epoch number

Example

new_epoch = await client.wait_for_next_epoch(timeout=300)
print(f"Epoch {new_epoch} started")