# create\_wallet\_client

Create a synchronous `Web3` instance with full Seismic wallet capabilities.

## Overview

`create_wallet_client()` is the primary factory function for creating a sync client that can perform shielded writes, signed reads, and deposits. It fetches the TEE public key, derives encryption state via [ECDH](https://en.wikipedia.org/wiki/Elliptic-curve_Diffie%E2%80%93Hellman), and attaches a fully-configured [`w3.seismic`](https://docs.seismic.systems/clients/python/namespaces/seismic-namespace) namespace to a standard `Web3` instance.

The returned client works with all standard `web3.py` APIs (`w3.eth.get_block()`, `w3.eth.send_raw_transaction()`, etc.) plus the additional `w3.seismic` namespace for Seismic-specific operations.

## Signature

```python
def create_wallet_client(
    rpc_url: str,
    private_key: PrivateKey,
    *,
    encryption_sk: PrivateKey | None = None,
) -> Web3
```

## Parameters

| Parameter       | Type                                                                                        | Required | Description                                                                                                                      |
| --------------- | ------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `rpc_url`       | `str`                                                                                       | Yes      | HTTP(S) URL of the Seismic node (e.g., `"https://gcp-1.seismictest.net/rpc"`). WebSocket URLs are not supported — see note below |
| `private_key`   | [`PrivateKey`](https://docs.seismic.systems/clients/python/api-reference/types/private-key) | Yes      | 32-byte secp256k1 private key for signing transactions                                                                           |
| `encryption_sk` | [`PrivateKey`](https://docs.seismic.systems/clients/python/api-reference/types/private-key) | No       | Optional 32-byte key for ECDH. If `None`, a random ephemeral key is generated                                                    |

## Returns

| Type   | Description                                                                                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Web3` | A `Web3` instance with `w3.seismic` namespace attached ([`SeismicNamespace`](https://docs.seismic.systems/clients/python/namespaces/seismic-namespace)) |

## Examples

### Basic Usage

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

# Load private key
private_key = PrivateKey.from_hex_str(os.environ["PRIVATE_KEY"])

# Create wallet client
w3 = create_wallet_client(
    "https://gcp-1.seismictest.net/rpc",
    private_key=private_key,
)

# Now use w3.seismic for Seismic operations
contract = w3.seismic.contract(address, abi)
tx_hash = contract.swrite.transfer(recipient, 1000)
receipt = w3.eth.wait_for_transaction_receipt(tx_hash)
```

### Using Chain Configuration

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

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

# Recommended: use chain config instead of raw URL
w3 = SEISMIC_TESTNET.wallet_client(private_key)

# Equivalent to:
# w3 = create_wallet_client(SEISMIC_TESTNET.rpc_url, private_key=private_key)
```

### With Custom Encryption Key

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

signing_key = PrivateKey.from_hex_str(os.environ["PRIVATE_KEY"])
encryption_key = PrivateKey(os.urandom(32))  # Custom encryption keypair

w3 = create_wallet_client(
    "https://gcp-1.seismictest.net/rpc",
    private_key=signing_key,
    encryption_sk=encryption_key,
)
```

### Standard Web3 Operations

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

private_key = PrivateKey.from_hex_str(os.environ["PRIVATE_KEY"])
w3 = create_wallet_client("https://gcp-1.seismictest.net/rpc", private_key=private_key)

# All standard web3.py operations work
block = w3.eth.get_block("latest")
balance = w3.eth.get_balance("0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266")
chain_id = w3.eth.chain_id
```

## How It Works

The function performs five steps:

1. **Create Web3 instance**

   ```python
   w3 = Web3(Web3.HTTPProvider(rpc_url))
   ```
2. **Fetch TEE public key** (synchronous RPC call)

   ```python
   network_pk = get_tee_public_key(w3)
   ```
3. **Generate encryption keypair** (if `encryption_sk` is `None`, a random ephemeral key is created)

   ```python
   encryption_sk = encryption_sk or PrivateKey(os.urandom(32))
   ```
4. **Derive encryption state** (ECDH + [HKDF](https://en.wikipedia.org/wiki/HKDF))

   ```python
   encryption = get_encryption(network_pk, encryption_sk)
   ```
5. **Attach Seismic namespace**

   ```python
   w3.seismic = SeismicNamespace(w3, encryption, private_key)
   ```

## Client Capabilities

The returned client provides:

### Standard Web3 Methods (e.g. `w3.eth`, `w3.net`)

* `get_block()`, `get_transaction()`, `get_balance()`
* `send_raw_transaction()`, `wait_for_transaction_receipt()`
* All other standard `web3.py` functionality

### Seismic Methods (`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
* [`deposit()`](https://docs.seismic.systems/clients/python/namespaces/methods/deposit) - Deposit ETH/tokens
* [`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

## Encryption

The client automatically:

* Fetches the network's TEE public key
* Performs ECDH key exchange using `encryption_sk` (or generates a random one)
* Derives a shared AES-GCM key via HKDF
* Uses this key to encrypt all shielded transaction calldata and signed reads

Access the encryption state at `w3.seismic.encryption` if needed for advanced use cases.

## Notes

* **HTTP only** — Sync clients use `Web3` with `HTTPProvider`, which does not support WebSocket connections. This is a limitation of the underlying `web3.py` library (`WebSocketProvider` is async-only). If you need WebSocket support (persistent connections, subscriptions), use [`create_async_wallet_client()`](https://docs.seismic.systems/clients/python/client/create-async-wallet-client) with `ws=True`
* The function makes one synchronous RPC call to fetch the TEE public key
* If `encryption_sk` is `None`, a random ephemeral key is generated
* The encryption key is separate from the transaction signing key
* The returned `Web3` instance is fully compatible with all `web3.py` APIs
* For async operations, use [`create_async_wallet_client()`](https://docs.seismic.systems/clients/python/client/create-async-wallet-client)

## Warnings

* **Private key security** - Never log or expose private keys. Use environment variables or secure key management
* **RPC URL validation** - Ensure the RPC URL is correct and accessible
* **Network connectivity** - The function will fail if it cannot reach the RPC endpoint
* **HTTPS recommended** - Use HTTPS URLs in production to prevent MITM attacks

## See Also

* [create\_async\_wallet\_client](https://docs.seismic.systems/clients/python/client/create-async-wallet-client) - Async variant with WebSocket support
* [create\_public\_client](https://docs.seismic.systems/clients/python/client/create-public-client) - Read-only client without private key
* [EncryptionState](https://docs.seismic.systems/clients/python/client/encryption-state) - Encryption state class
* [get\_encryption](https://docs.seismic.systems/clients/python/client/get-encryption) - Encryption derivation function
* [SeismicNamespace](https://docs.seismic.systems/clients/python/namespaces/seismic-namespace) - The `w3.seismic` namespace
* [Chains Configuration](https://docs.seismic.systems/clients/python/chains) - Pre-configured chain constants