# Client

The Seismic Python SDK provides two client types for interacting with Seismic nodes:

* [**Wallet client**](https://docs.seismic.systems/clients/python/client/create-wallet-client) — Full capabilities (shielded writes, signed reads, deposits). Requires a private key.
* [**Public client**](https://docs.seismic.systems/clients/python/client/create-public-client) — Read-only (transparent reads, TEE public key, deposit queries). No private key needed.

Both clients are available in **sync** and **async** variants.

## Quick Start

### Installation

```bash
pip install seismic-web3
```

Or with [uv](https://docs.astral.sh/uv/):

```bash
uv add seismic-web3
```

### Wallet Client (Sync)

```python
import os
from seismic_web3 import SEISMIC_TESTNET, PrivateKey

pk = PrivateKey.from_hex_str(os.environ["PRIVATE_KEY"])
w3 = SEISMIC_TESTNET.wallet_client(pk)
```

This gives you a standard `Web3` instance with an extra `w3.seismic` namespace. Everything from `web3.py` works as usual — `w3.eth.get_block(...)`, `w3.eth.wait_for_transaction_receipt(...)`, etc.

### Wallet Client (Async)

```python
import os
from seismic_web3 import SEISMIC_TESTNET, PrivateKey

pk = PrivateKey.from_hex_str(os.environ["PRIVATE_KEY"])

# HTTP
w3 = await SEISMIC_TESTNET.async_wallet_client(pk)

# WebSocket (auto-selects ws_url from chain config)
w3 = await SEISMIC_TESTNET.async_wallet_client(pk, ws=True)
```

Every method on `w3.seismic` and on `ShieldedContract` is `await`-able when using the async client.

### Public Client

```python
from seismic_web3 import SEISMIC_TESTNET

# Sync
public = SEISMIC_TESTNET.public_client()

# Async
public = SEISMIC_TESTNET.async_public_client()
```

The public client's `w3.seismic` namespace has limited methods: `get_tee_public_key()`, `get_deposit_root()`, `get_deposit_count()`, and `contract()` (with `.tread` only).

## Client Factory Functions

### Wallet Clients (Require Private Key)

| Function                                                                                                       | Type  | Description                             |
| -------------------------------------------------------------------------------------------------------------- | ----- | --------------------------------------- |
| [create\_wallet\_client](https://docs.seismic.systems/clients/python/client/create-wallet-client)              | Sync  | Create sync wallet client from RPC URL  |
| [create\_async\_wallet\_client](https://docs.seismic.systems/clients/python/client/create-async-wallet-client) | Async | Create async wallet client from RPC URL |

### Public Clients (No Private Key)

| Function                                                                                                       | Type  | Description                             |
| -------------------------------------------------------------------------------------------------------------- | ----- | --------------------------------------- |
| [create\_public\_client](https://docs.seismic.systems/clients/python/client/create-public-client)              | Sync  | Create sync public client from RPC URL  |
| [create\_async\_public\_client](https://docs.seismic.systems/clients/python/client/create-async-public-client) | Async | Create async public client from RPC URL |

## Chain-Based Creation

The recommended approach is to use chain configuration objects:

```python
import os
from seismic_web3 import SEISMIC_TESTNET, SANVIL, PrivateKey

# Seismic testnet
pk = PrivateKey.from_hex_str(os.environ["PRIVATE_KEY"])
w3 = SEISMIC_TESTNET.wallet_client(pk)

# Sanvil testnet
w3 = SANVIL.wallet_client(pk)
```

See [Chains Configuration](https://docs.seismic.systems/clients/python/chains) for more details.

## Encryption

The wallet client automatically handles encryption setup:

1. Fetches the network's TEE public key
2. Derives a shared [AES-GCM](https://en.wikipedia.org/wiki/Galois/Counter_Mode) key via [ECDH](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman)
3. Uses this key to encrypt calldata for all shielded transactions and signed reads

You don't need to manage this manually, but the encryption state is accessible at `w3.seismic.encryption` if needed.

### Encryption Components

| Component                                                                              | Description                                  |
| -------------------------------------------------------------------------------------- | -------------------------------------------- |
| [EncryptionState](https://docs.seismic.systems/clients/python/client/encryption-state) | Holds AES key and encryption keypair         |
| [get\_encryption](https://docs.seismic.systems/clients/python/client/get-encryption)   | Derives encryption state from TEE public key |

## Client Capabilities

### Wallet Client (`w3.seismic`)

* [`send_shielded_transaction()`](https://docs.seismic.systems/clients/python/namespaces/methods/send-shielded-transaction) - Send shielded transactions
* [`debug_send_shielded_transaction()`](https://docs.seismic.systems/clients/python/namespaces/methods/debug-send-shielded-transaction) - Debug shielded transactions
* [`signed_call()`](https://docs.seismic.systems/clients/python/namespaces/methods/signed-call) - Execute signed reads
* [`get_tee_public_key()`](https://docs.seismic.systems/clients/python/namespaces/methods/get-tee-public-key) - Get TEE public key
* [`deposit()`](https://docs.seismic.systems/clients/python/namespaces/methods/deposit) - Deposit ETH/tokens
* [`get_deposit_root()`](https://docs.seismic.systems/clients/python/namespaces/methods/get-deposit-root) - Query deposit merkle root
* [`get_deposit_count()`](https://docs.seismic.systems/clients/python/namespaces/methods/get-deposit-count) - Query deposit count
* [`contract()`](https://docs.seismic.systems/clients/python/contract) - Create contract wrappers

### Public Client (`w3.seismic`)

* [`get_tee_public_key()`](https://docs.seismic.systems/clients/python/namespaces/methods/get-tee-public-key) - Get TEE public key
* [`get_deposit_root()`](https://docs.seismic.systems/clients/python/namespaces/methods/get-deposit-root) - Query deposit merkle root
* [`get_deposit_count()`](https://docs.seismic.systems/clients/python/namespaces/methods/get-deposit-count) - Query deposit count
* [`contract()`](https://docs.seismic.systems/clients/python/contract) - Create contract wrappers (`.tread` only)

## See Also

* [Contract Instances](https://docs.seismic.systems/clients/python/contract) - Working with shielded and public contracts
* [Namespaces](https://docs.seismic.systems/clients/python/namespaces) - Detailed `w3.seismic` namespace documentation
* [Chains Configuration](https://docs.seismic.systems/clients/python/chains) - Chain configs and constants
* [Shielded Write Guide](https://docs.seismic.systems/clients/python/guides/shielded-write) - Step-by-step shielded transaction guide