> For the complete documentation index, see [llms.txt](https://docs.seismic.systems/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.seismic.systems/clients/python/client/create-wallet-client.md).

# create\_wallet\_client

Create sync Web3 instance with full Seismic wallet capabilities

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

> **Balance RPC migration:** On reth with PR #502, `w3.eth.get_balance()` returns a compatibility placeholder, not native or sUSDC holdings. A signing wallet does not change this RPC's behavior. See [Balance RPCs](/reference/balance-rpcs.md) for explicit native queries.

## 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`](/clients/python/namespaces/seismic-namespace.md) 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://testnet-1.seismictest.net/rpc"`). WebSocket URLs are not supported — see note below |
| `private_key`   | [`PrivateKey`](/clients/python/api-reference/types/private-key.md) | Yes      | 32-byte secp256k1 private key for signing transactions                                                                               |
| `encryption_sk` | [`PrivateKey`](/clients/python/api-reference/types/private-key.md) | 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`](/clients/python/namespaces/seismic-namespace.md)) |

## 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://testnet-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://testnet-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://testnet-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()`](/clients/python/namespaces/methods/send-shielded-transaction.md) - Send shielded transactions
* [`debug_send_shielded_transaction()`](/clients/python/namespaces/methods/debug-send-shielded-transaction.md) - Debug shielded transactions
* [`signed_call()`](/clients/python/namespaces/methods/signed-call.md) - Execute signed reads
* [`deposit()`](/clients/python/namespaces/methods/deposit.md) - Deposit ETH/tokens
* [`get_tee_public_key()`](/clients/python/namespaces/methods/get-tee-public-key.md) - Get TEE public key
* [`get_deposit_root()`](/clients/python/namespaces/methods/get-deposit-root.md) - Query deposit merkle root
* [`get_deposit_count()`](/clients/python/namespaces/methods/get-deposit-count.md) - Query deposit count
* [`contract()`](/clients/python/contract.md) - 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()`](/clients/python/client/create-async-wallet-client.md) 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()`](/clients/python/client/create-async-wallet-client.md)

## 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](/clients/python/client/create-async-wallet-client.md) - Async variant with WebSocket support
* [create\_public\_client](/clients/python/client/create-public-client.md) - Read-only client without private key
* [EncryptionState](/clients/python/client/encryption-state.md) - Encryption state class
* [get\_encryption](/clients/python/client/get-encryption.md) - Encryption derivation function
* [SeismicNamespace](/clients/python/namespaces/seismic-namespace.md) - The `w3.seismic` namespace
* [Chains Configuration](/clients/python/chains.md) - Pre-configured chain constants


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.seismic.systems/clients/python/client/create-wallet-client.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.