derive.account

Documentation for eth_defi.derive.account Python module.

Derive account balance and collateral reading functions.

This module provides functions for reading account balances and collateral information from Derive.xyz accounts.

Functions

fetch_account_collaterals(client[, ...])

Fetch collateral balances for a Derive subaccount.

fetch_account_summary(client[, subaccount_id])

Fetch comprehensive account summary including collaterals and margin info.

fetch_subaccount_ids(client)

Fetch subaccount IDs for a Derive wallet.

Classes

AccountSummary

Complete summary of a Derive account.

CollateralBalance

Single collateral balance in a Derive account.
class CollateralBalance

Bases: object

Single collateral balance in a Derive account.

#: Token symbol (e.g., “USDC”, “WETH”) token: str

#: Available balance (not used in positions) available: Decimal

#: Total balance including locked total: Decimal

#: Balance locked in positions locked: Decimal

#: Token contract address on Derive Chain token_address: HexAddress | None = None

__init__(token, available, total, locked, token_address=None)
Parameters
Return type

None

class AccountSummary

Bases: object

Complete summary of a Derive account.

#: Derive wallet address (smart contract wallet) account_address: HexAddress

#: Subaccount ID subaccount_id: int

#: List of collateral balances collaterals: list[CollateralBalance]

#: Total account value in USD total_value_usd: Decimal

#: Account margin status (e.g., “healthy”, “warning”) margin_status: str | None = None

#: Initial margin requirement initial_margin: Decimal | None = None

#: Maintenance margin requirement maintenance_margin: Decimal | None = None

__init__(account_address, subaccount_id, collaterals, total_value_usd, margin_status=None, initial_margin=None, maintenance_margin=None)
Parameters
Return type

None

fetch_subaccount_ids(client)

Fetch subaccount IDs for a Derive wallet.

Parameters

client (DeriveApiClient) – Authenticated Derive API client with session key.

Returns

List of subaccount IDs (may be empty if no subaccounts exist).

Raises

ValueError – If authentication fails.

Return type

list[int]

fetch_account_collaterals(client, subaccount_id=None)

Fetch collateral balances for a Derive subaccount.

Requires authenticated client with session key (minimum scope: read_only).

Example:

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

client = DeriveApiClient(...)
client.session_key_private = "0x..."

collaterals = fetch_account_collaterals(client)
for col in collaterals:
    print(f"{col.token}: {col.available} available, {col.locked} locked")
Parameters

  • client (DeriveApiClient) – Authenticated Derive API client with session key

  • subaccount_id (int | None) – Subaccount ID (defaults to client.subaccount_id)

Returns

List of collateral balances

Raises

ValueError – If authentication fails or account not found

Return type

list[eth_defi.derive.account.CollateralBalance]

fetch_account_summary(client, subaccount_id=None)

Fetch comprehensive account summary including collaterals and margin info.

Combines multiple API calls to build a complete account picture.

Example:

from eth_defi.derive.authentication import DeriveApiClient
from eth_defi.derive.account import fetch_account_summary

client = DeriveApiClient(...)
client.session_key_private = "0x..."

summary = fetch_account_summary(client)
print(f"Total value: ${summary.total_value_usd}")
print(f"Margin status: {summary.margin_status}")
for col in summary.collaterals:
    print(f"  {col.token}: {col.total}")
Parameters

  • client (DeriveApiClient) – Authenticated Derive API client with session key

  • subaccount_id (int | None) – Subaccount ID (defaults to client.subaccount_id)

Returns

Complete account summary

Raises

ValueError – If authentication fails or account not found

Return type

eth_defi.derive.account.AccountSummary