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. For example, 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 a network 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 a network 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.

async def get_balance(address: str) -> float

Parameter	Type	Required	Default	Description
address	str	Yes	-	SOMA address

Returns: float. Balance in SOMA.

Example

balance = await client.get_balance("0x1234...")
print(f"{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")

get_next_epoch_timestamp

Get the estimated UNIX timestamp (ms) when the next epoch starts. Computed as epoch_start_timestamp_ms + epoch_duration_ms from the current system state.

async def get_next_epoch_timestamp() -> int

Returns: int. Estimated UNIX timestamp in milliseconds.

get_following_epoch_timestamp

Get the estimated UNIX timestamp (ms) when the epoch after next starts. Computed as epoch_start_timestamp_ms + 2 * epoch_duration_ms. Useful for scheduling actions that require two epoch boundaries (e.g., claim_rewards after submit_data).

async def get_following_epoch_timestamp() -> int

Returns: int. Estimated UNIX timestamp in milliseconds.