derive.onboarding

Documentation for eth_defi.derive.onboarding Python module.

Derive.xyz account onboarding and session key management.

This module provides onboarding helpers for the Derive.xyz exchange.

Important

Account creation and initial session key require the Derive web interface at https://testnet.derive.xyz/ (testnet) or https://derive.xyz/ (mainnet). The web UI deploys an ERC-4337 LightAccount smart contract wallet via a gas-sponsored UserOperation and registers the initial session key. This step cannot be automated programmatically due to bot detection on the SIWE (Sign-In with Ethereum) endpoint and paymaster access controls.

Once an account and session key exist, this module provides:

1. Wallet address resolution – Derives the counterfactual LightAccount address from an owner EOA using LightAccountFactory.getAddress(owner, 0)

2. Session key verification – Confirms the session key works by reading account data

Typical workflow:

from eth_account import Account
from eth_defi.derive.authentication import DeriveApiClient
from eth_defi.derive.account import fetch_account_collaterals

# Step 1: Create account via web UI at https://testnet.derive.xyz/
# Step 2: Get credentials from the developer page (Home → Developers):
#   - Derive Wallet address
#   - Session Key private key
# Step 3: Export your wallet private key from MetaMask:
#   Account menu → "Account details" → "Show private key"

client = DeriveApiClient(
    owner_account=Account.from_key("0x..."),  # Owner wallet private key
    derive_wallet_address="0x...",  # From developer page
    session_key_private="0x...",  # From developer page
    is_testnet=True,
)

collaterals = fetch_account_collaterals(client)

See also:

• Derive API documentation

• Manual onboarding

Functions

create_owner_key()	Create a fresh Ethereum EOA for use as Derive owner wallet.
create_session_key()	Create a fresh Ethereum EOA for use as Derive session key.
fetch_derive_wallet_address(owner_address[, ...])	Derive the counterfactual LightAccount wallet address for an owner EOA.
verify_session_key(client)	Verify that the session key works by reading account data.

create_owner_key()

Create a fresh Ethereum EOA for use as Derive owner wallet.

Returns

Tuple of (private_key_hex, address)

Return type

tuple[str, eth_typing.evm.HexAddress]

create_session_key()

Create a fresh Ethereum EOA for use as Derive session key.

Returns

Tuple of (private_key_hex, address)

Return type

tuple[str, eth_typing.evm.HexAddress]

fetch_derive_wallet_address(owner_address, is_testnet=True, salt=0)

Derive the counterfactual LightAccount wallet address for an owner EOA.

Calls LightAccountFactory.getAddress(owner, salt) on Derive Chain to get the deterministic CREATE2 address. The contract does not need to be deployed – the address is computed from create2(factory, salt, initCodeHash).

Parameters

• owner_address (eth_typing.evm.HexAddress) – Owner EOA address.

• is_testnet (bool) – Whether to use the Derive testnet RPC.

• salt (int) – CREATE2 salt (defaults to 0, matching the web UI).

Returns

Counterfactual LightAccount address.

Return type

eth_typing.evm.HexAddress

verify_session_key(client)

Verify that the session key works by reading account data.

Makes an authenticated API call to private/get_subaccounts to confirm the session key is valid and can access the account. This endpoint works even when no subaccounts exist yet.

Parameters

client (eth_defi.derive.authentication.DeriveApiClient) – Derive API client with session_key_private set.

Returns

True if the session key works, False otherwise.

Return type

bool