# Python SDK Reference

**Note:** The Python SDK is a native extension built with PyO3. All async methods return coroutines compatible with `asyncio`.

## Quick Reference

| Method | Category | Returns | Page |
|--------|----------|---------|------|
| `Keypair.generate()` | Keypair | `Keypair` | [Keypair](https://docs.soma.org/reference/sdk/keypair/) |
| `Keypair.from_secret_key()` | Keypair | `Keypair` | [Keypair](https://docs.soma.org/reference/sdk/keypair/) |
| `Keypair.from_mnemonic()` | Keypair | `Keypair` | [Keypair](https://docs.soma.org/reference/sdk/keypair/) |
| `get_chain_identifier()` | Chain | `str` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_server_version()` | Chain | `str` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_protocol_version()` | Chain | `int` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_architecture_version()` | Chain | `int` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_embedding_dim()` | Chain | `int` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_model_min_stake()` | Chain | `int` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `check_api_version()` | Chain | `None` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_object()` | Objects | `ObjectRef` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_object_with_version()` | Objects | `ObjectRef` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_balance()` | Objects | `float` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `list_owned_objects()` | Objects | `list[ObjectRef]` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_latest_system_state()` | System | `SystemState` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_epoch()` | System | `EpochInfo` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_latest_checkpoint()` | Checkpoints | `CheckpointSummary` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_checkpoint_summary()` | Checkpoints | `CheckpointSummary` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `wait_for_next_epoch()` | Epoch | `int` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_next_epoch_timestamp()` | Epoch | `int` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `get_following_epoch_timestamp()` | Epoch | `int` | [Chain & State](https://docs.soma.org/reference/sdk/chain-state/) |
| `list_targets()` | Targets | `ListTargetsResponse` | [Targets](https://docs.soma.org/reference/sdk/targets-challenges/) |
| `get_targets()` | Targets | `list[Target]` | [Targets](https://docs.soma.org/reference/sdk/targets-challenges/) |
| `get_model_manifests()` | Targets | `list[ModelManifest]` | [Targets](https://docs.soma.org/reference/sdk/targets-challenges/) |
| `fetch_model()` | Targets | `bytes` | [Targets](https://docs.soma.org/reference/sdk/targets-challenges/#fetching-data) |
| `fetch_submission_data()` | Targets | `bytes` | [Targets](https://docs.soma.org/reference/sdk/targets-challenges/#fetching-data) |
| `execute_transaction()` | Transactions | `TransactionEffects` | [Transactions](https://docs.soma.org/reference/sdk/transactions/) |
| `simulate_transaction()` | Transactions | `TransactionEffects` | [Transactions](https://docs.soma.org/reference/sdk/transactions/) |
| `get_transaction()` | Transactions | `TransactionEffects` | [Transactions](https://docs.soma.org/reference/sdk/transactions/) |
| `create_model()` | Models | `str` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#model-management) |
| `commit_model()` | Models | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#model-management) |
| `reveal_model()` | Models | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#model-management) |
| `deactivate_model()` | Models | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#model-management) |
| `set_model_commission_rate()` | Models | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#model-management) |
| `report_model()` | Models | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#model-management) |
| `undo_report_model()` | Models | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#model-management) |
| `submit_data()` | Submissions | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#data-submission) |
| `claim_rewards()` | Submissions | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#data-submission) |
| `report_submission()` | Submissions | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#data-submission) |
| `undo_report_submission()` | Submissions | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#data-submission) |
| `score()` | Scoring | `ScoreResult` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#scoring) |
| `transfer_coin()` | Transfers | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#transfers--payments) |
| `transfer_objects()` | Transfers | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#transfers--payments) |
| `pay_coins()` | Transfers | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#transfers--payments) |
| `request_faucet()` | Admin | `FaucetResponse` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#admin) |
| `add_stake()` | Staking | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#staking) |
| `withdraw_stake()` | Staking | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#staking) |
| `add_stake_to_model()` | Staking | `None` | [Scoring & Admin](https://docs.soma.org/reference/sdk/scoring-admin/#staking) |

## Installation

```
pip install soma-sdk
```
**Note:** `soma-sdk` is a native extension built with PyO3 and Rust. Pre-built wheels are available for Linux and macOS. Building from source requires a Rust toolchain.

## Client Construction

Use named presets for common networks:

```python
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:

```python
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:

```python
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.

```python
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`.

```python
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.

```python
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).

```python
shannons = SomaClient.to_shannons(1.5)  # 1_500_000_000
```

### to_soma

Convert shannons to SOMA.

```python
soma = SomaClient.to_soma(1_500_000_000)  # 1.5
```