Python SDK - Trading With Sub-Accounts

You can use the Sub-Account feature to trade with different accounts with the same L1 address.

client = zklighter.SignerClient(BASE_URL, PRIVATE_KEY)

accounts = await zklighter.AccountApi(client.api_client).accounts_by_l1_address(
    l1_address=client.l1_address
)

print(accounts.sub_accounts)

When you register a new address it returns only the main account as sub_accounts

Output:

[
Account(
  code=0, 
  message=None, 
  account_type=0, 
  index=168, 
  l1_address='0xF333b4CEF5426dE4968caa620d9d487450d8BBdE', 
  cancel_all_time=0, 
  open_order_count=0, 
  status=1, 
  collateral='500.000000')
]

You can start trading with that account. But when it comes to more complex trading strategies you may want to create sub-accounts with separated collaterals.

Creating Sub-Account

await client.create_sub_account()

time.sleep(5)

accounts = await zklighter.AccountApi(client.api_client).accounts_by_l1_address(
    l1_address=client.l1_address
)

Output:

    [
        Account(
            code=0,
            message=None,
            account_type=0,
            index=168,
            l1_address="0xF333b4CEF5426dE4968caa620d9d487450d8BBdE",
            cancel_all_time=0,
            open_order_count=0,
            status=1,
            collateral="500.000000",
        ),
        Account(
            code=0,
            message=None,
            account_type=1,
            index=281474976710599,
            l1_address="0xF333b4CEF5426dE4968caa620d9d487450d8BBdE",
            cancel_all_time=0,
            open_order_count=0,
            status=0,
            collateral="0.000000",
        ),
]

The sub-accounts are indexed from last to end. So you can assume that the largest index is your first sub-account.

It's 281474976710599 in this example.

You need to create another client to manage orders from that account.

Let's create an order from the sub-account:

sub_client = zklighter.SignerClient(
    BASE_URL, PRIVATE_KEY, account_index=281474976710599
)

tx = await sub_client.create_order(
    market_index=0,
    client_order_index=0,
    base_amount=100000,
    price=100,
    is_ask=0,
    order_type=zklighter.SignerClient.ORDER_TYPE_LIMIT,
    time_in_force=zklighter.SignerClient.ORDER_TIME_IN_FORCE_GOOD_TILL_TIME,
)

print(tx)

Output:

code=100 
message='{"ratelimit": "998 volume tokens remained"}' 
tx_hash='26b42638362bcf3abc13c1cf3019906ba3e2f8085691a80542a4341c4fb08e96'

Managing Collaterals

Since the sub-accounts have separated collaterals and they don't share when the sub-account is liquidated you need to manage them by yourself with transfer feature.

Transfer to Sub-Account Example:

client = zklighter.SignerClient(BASE_URL, PRIVATE_KEY)

accounts = await zklighter.AccountApi(client.api_client).accounts_by_l1_address(
    l1_address=client.l1_address
)
print(accounts.sub_accounts)

await client.transfer(to_account_index=281474976710599, usdc_amount=25)

time.sleep(5)

accounts = await zklighter.AccountApi(client.api_client).accounts_by_l1_address(
    l1_address=client.l1_address
)
print(accounts.sub_accounts)

Collaterals before the transfer:

[
    Account(
        index=168,
        .
        .
        collateral="1500.000000",
    ),
    Account(
        index=281474976710599,
        .
        .
        collateral="0.000000",
    ),
]

Collaterals after the transfer:

[
    Account(
        index=168,
        .
        .
        collateral="1475.000000",
    ),
    Account(
        index=281474976710599,
        .
        .
        collateral="25.000000",
    ),
]

Let's create another sub-account and transfer between the sub-accounts.

sub_client = zklighter.SignerClient(
    BASE_URL, PRIVATE_KEY, account_index=281474976710599
)

await sub_client.transfer(to_account_index=281474976710598, usdc_amount=15)

time.sleep(5)

accounts = await zklighter.AccountApi(sub_client.api_client).accounts_by_l1_address(
    l1_address=sub_client.l1_address
)
print(accounts.sub_accounts)

Output:

[
    Account(
        index=168,
        collateral="2475.000000",
    ),
    Account(
        index=281474976710599,
        collateral="10.000000",
    ),
    Account(
        index=281474976710598,
        collateral="15.000000",
    ),
]