derive.authentication

Documentation for eth_defi.derive.authentication Python module.

Derive API client with session key authentication.

This module provides the DeriveApiClient for authenticating with Derive.xyz API using session keys and EIP-191 personal-sign authentication.

Authentication uses the encode_defunct(text=timestamp) pattern: the client signs a millisecond timestamp string with either a session key or the owner wallet key, and sends the signature in X-LYRASIGNATURE / X-LYRAWALLET / X-LYRATIMESTAMP headers.

Note

Header names use uppercase (X-LYRAWALLET etc.) to match the canonical format used by the official derive_action_signing package.

Classes

DeriveApiClient

Derive API client with session key authentication.
class DeriveApiClient

Bases: object

Derive API client with session key authentication.

This client handles:

  • Authenticated JSON-RPC 2.0 requests via HTTP

  • Signing requests with EIP-191 personal-sign (encode_defunct)

Authentication headers follow the Derive convention:

X-LYRAWALLET:    <smart contract wallet address>
X-LYRATIMESTAMP: <UTC timestamp in milliseconds>
X-LYRASIGNATURE: <EIP-191 signature of the timestamp string>

Example:

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

# Initialise with owner account
owner = Account.from_key("0x...")
client = DeriveApiClient(
    owner_account=owner,
    derive_wallet_address="0x...",
    is_testnet=True,
)

# Make authenticated request using owner key directly
result = client._make_jsonrpc_request(
    method="private/get_subaccounts",
    params={"wallet": client.derive_wallet_address},
    authenticated=True,
)

Initialise Derive API client.

Parameters

  • owner_account – Owner wallet (EOA) for signing session key registrations.

  • derive_wallet_address – Derive wallet address (LightAccount smart contract wallet on Derive Chain). For manual onboarding this equals the counterfactual LightAccount address derived from the owner EOA.

  • subaccount_id – Subaccount ID to use for requests (defaults to 1).

  • is_testnet – Whether to use testnet API endpoint.

  • session_key_private – Private key of registered session key (hex string starting with 0x).

__init__(owner_account=None, derive_wallet_address=None, subaccount_id=1, is_testnet=False, session_key_private='')

Initialise Derive API client.

Parameters

  • owner_account (eth_account.signers.local.LocalAccount | None) – Owner wallet (EOA) for signing session key registrations.

  • derive_wallet_address (Optional[eth_typing.evm.HexAddress]) – Derive wallet address (LightAccount smart contract wallet on Derive Chain). For manual onboarding this equals the counterfactual LightAccount address derived from the owner EOA.

  • subaccount_id (int) – Subaccount ID to use for requests (defaults to 1).

  • is_testnet (bool) – Whether to use testnet API endpoint.

  • session_key_private (str) – Private key of registered session key (hex string starting with 0x).