Account Management Examples¶

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

Setup¶

All examples on this page use the AsyncRESTClient with a private key for authentication. Here's the basic pattern:

import asyncio
from meridian import AsyncRESTClient

async def main():
    # Initialize client with your private key
    client = await AsyncRESTClient.create({
        "base_url": "https://api.meridian.xyz",
        "chain_config": {
            "rpc_url": "https://rpc.mainnet.chain.robinhood.com",
            "private_key": "your_private_key"
        }
    })

    # Your code here

    await client.close()

asyncio.run(main())

The examples below show the code that goes in the "Your code here" section. For a complete standalone example, see Managing subaccounts.

Managing subaccounts¶

This complete example shows the full pattern including imports, initialization, and cleanup:

import asyncio
from meridian import AsyncRESTClient

async def manage_subaccounts():
    # Initialize client with your private key
    client = await AsyncRESTClient.create({
        "base_url": "https://api.meridian.xyz",
        "chain_config": {
            "rpc_url": "https://rpc.mainnet.chain.robinhood.com",
            "private_key": "your_private_key"
        }
    })

    # Subaccounts are fetched from the API
    subaccounts = await client.subaccounts()

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

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

    await client.close()

asyncio.run(manage_subaccounts())

Creating Accounts¶

Subaccounts are created when a token is deposited. A private key is required for this operation.

deposit_usd deposits into the exchange's USD collateral (mUSD), which is a wrapper token. The exchange pulls mUSD's underlying wrapped token from your wallet via transferFrom and wraps it on deposit, so you must approve the exchange to spend that underlying token before depositing.

Creating a new subaccount¶

# The token the exchange actually pulls (mUSD's underlying wrapped token)
deposit_token = client.chain.usd_deposit_token

# Approve the exchange to spend it (one-time, or whenever the allowance is low)
client.chain.approve_token(amount=100, token_address=deposit_token, submit=True)

# Deposit USD to create a new subaccount
deposit_tx_hash = client.chain.deposit_usd(
    amount=100,
    account_name='trading',
    submit=True
)
print(f"Deposit transaction hash: {deposit_tx_hash}")

Depositing to an existing subaccount¶

# Deposit using the bytes name from an existing subaccount
subaccounts = await client.subaccounts()
subaccount = subaccounts[0]

# Assumes the exchange already has sufficient allowance (see above)
deposit_tx_hash = client.chain.deposit_usd(
    amount=100,
    account_name=subaccount.name,
    submit=True
)
print(f"Deposit transaction hash: {deposit_tx_hash}")

Checking balances¶

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

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

Managing positions¶

# Get all positions
subaccounts = await client.subaccounts()
subaccount_id = subaccounts[0].id
positions = await 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 = await client.get_position(id=position_id)
    print(position.model_dump())

Token operations¶

# List all tokens
tokens = await client.list_tokens()

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

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

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

Token conversions¶

convert_token converts one token balance into another inside a subaccount. Its main use is funding isolated margin trading.

subaccounts = await client.subaccounts()
sub = subaccounts[0]

tokens = await client.list_tokens()
usd = next(t for t in tokens if t.name == "USD")
xauusd = next(t for t in tokens if t.name == "XAUUSD")

# Convert 100 USD into XAUUSD
conversion = await client.convert_token(
    from_token_id=usd.id,
    to_token_id=xauusd.id,
    amount=100,
    subaccount=sub.name,
)
print(conversion.model_dump())

Like orders and withdrawals, conversions are EIP-712 signed and support the same workflow controls: pass sign=False or submit=False to inspect or externally sign the payload, or use the advanced prepare_convert_token -> sign_convert_token -> submit_convert_token flow described in Message Signing.

Withdrawals¶

subaccounts = await client.subaccounts()
subaccount = subaccounts[0]
usd_address = client.chain.usd.address

# Get the USD token id
tokens = await client.list_tokens(withdraw_enabled=True)
usd_token = next((token for token in tokens if token.address == usd_address), None)

# Submit a withdrawal request (destination_endpoint=0 for a same-chain withdrawal)
withdrawal = await client.withdraw_token(
    token_id=usd_token.id,
    amount=100,
    destination_address=client.chain.address,
    destination_endpoint=0,
    subaccount=subaccount.name,
    account=client.chain.address,
)