Account Management Examples

This page provides examples of account management operations with the Ethereal Python SDK.

Managing subaccounts

from ethereal import RESTClient

# Initialize client with your private key
client = RESTClient({
    "base_url": "https://api.etherealtest.net",
    "chain_config": {
        "rpc_url": "https://rpc.etherealtest.net",
        "private_key": "your_private_key"
    }
})

# Subaccounts are fetched from the API and stored in the client
subaccounts = client.subaccounts

for subaccount in subaccounts:
    print(subaccount.model_dump())

# Get a specific subaccount
if subaccounts:
    subaccount_id = subaccounts[0].id
    subaccount = client.get_subaccount(id=subaccount_id)
    print(subaccount.model_dump())

Creating Accounts

Subaccounts are created when a token is deposited, specifying a name for that account. The SDK provides a method to prepare and submit these deposit transactions to an RPC. In order to use this feature, you must have provided a private key when initializing the client.

# Step 1: Approve USDe tokens for the exchange
# Get the exchange contract address from the RPC config
exchange_proxy_address = client.rpc_config.domain.verifying_contract

# Create approval transaction parameters
approve_params = client.chain._get_tx()
# Approve 100 USDe tokens
approve_params = client.chain.usde.functions.approve(
    exchange_proxy_address,
    client.chain.provider.to_wei(100, "ether")
).build_transaction(approve_params)

# Submit the approval transaction
approve_tx_hash = client.chain.submit_tx(approve_params)
print(f"Approval transaction hash: {approve_tx_hash}")

# Wait for the approval transaction to be mined
client.chain.provider.eth.wait_for_transaction_receipt(approve_tx_hash)

# Step 2: Deposit USDe to create/fund a subaccount
# Option 1: Quick deposit with default parameters
deposit_tx_hash = client.chain.deposit_usde(
    amount=100,                   # Amount in USDe
    account_name='trading',       # Name for the subaccount
    submit=True                   # Automatically submit the transaction
)
print(f"Deposit transaction hash: {deposit_tx_hash}")

Checking balances

# Get balances for a subaccount
subaccount_id = client.subaccounts[0].id
balances = client.get_subaccount_balances(subaccount_id=subaccount_id)

for balance in balances:
    print(balance.model_dump())

Managing positions

# Get all positions
subaccount_id = client.subaccounts[0].id
positions = client.list_positions(subaccount_id=subaccount_id)

for position in positions:
    print(position.model_dump())

# Get a specific position
if positions:
    position_id = positions[0].id
    position = client.get_position(id=position_id)
    print(position.model_dump())

Token operations

# List all tokens
tokens = client.list_tokens()

for token in tokens:
    print(token.model_dump())

# List token withdrawals
subaccount_id = client.subaccounts[0].id
withdrawals = client.list_token_withdraws(subaccount_id=subaccount_id)
for withdrawal in withdrawals:
    print(withdrawal.model_dump())

# List token transfers
transfers = client.list_token_transfers(subaccount_id=subaccount_id)
for transfer in transfers:
    print(transfer.model_dump())

Withdrawals

Withdrawals are carried out in two steps. First, a withdrawal is submitted to the API using a POST request signed by the user's private key. When the delay period is over, the user can submit a finalizeWithdraw transaction to the exchange to complete the withdrawal.

subaccount = client.subaccounts[0]
usde_address = client.chain.usde.address

# Get the USDe token id
tokens = client.list_tokens(withdrawEnabled=True)
usde_token = next((token for token in tokens if token.address == usde_address), None)

# Step 1: Submit a withdrawal request
withdrawal = client.withdraw_token(
    subaccount=subaccount.name,
    token_id=usde_token.id,
    token=usde_token.address,
    amount=100,
    account=client.chain.address,
)

# Step 2: Check the withdrawal status
withdrawal_status = client.list_token_withdraws(
    subaccount_id=subaccount.id,
)
# if `is_ready` is True, the withdrawal is ready to be finalized...

# Step 3: Finalize the withdrawal
clean_account_name = client.chain.provider.to_text(subaccount.name).strip('\x00')
finalize_tx_hash = client.chain.finalize_withdraw(
    account_name=clean_account_name,
    submit=True
)