Quickstart

This guide will help you get started with the Ethereal Python SDK.

Initialize a client

The SDK provides a RESTClient class that allows you to interact with the Ethereal API. Each endpoints is mapped to a corresponding method in the client. You can use the client to fetch market data, create and manage accounts, and place orders.

from ethereal import RESTClient

# Create client with optional private key for requests that require signatures
config = {
    "base_url": "https://api.etherealtest.net",
    "chain_config": {
        "rpc_url": "https://rpc.etherealtest.net",
        "address": "your_address",          # optional
        "private_key": "your_private_key",  # optional
    }
}
client = RESTClient(config)

Fetch market data

The client has a mapping for each endpoint on the API. For example, client.list_products() corresponds to the /products endpoint. See the API Reference for a full list of methods, or visit the Ethereal API to explore available endpoints.

# Get all available products
products = client.list_products()

# Get current prices for all products
product_ids = [product.product_id for product in client.products]
prices = client.list_market_prices(product_ids=product_ids)

# Get market liquidity for a specific product
btc_id = client.products_by_ticker['BTCUSD'].id
liquidity = client.get_market_liquidity(product_id=btc_id)

Accounts and balances

Private Key Required

Some of the following code snippets require a private key to be provided at initialization. This is necessary for signing transactions for deposits and withdrawals, as well as any POST requests like placing orders.

If the connected address already has subaccounts, you can view positions and balances for each subaccount. If the address does not have any subaccounts there are two options:

1. Visit the example for Creating Accounts to create a subaccount.
2. Deposit using the Ethereal frontend. This will create an account named primary.

# Get all subaccounts
subaccounts = client.subaccounts

# Get current positions
positions = client.list_positions(
    subaccount_id=subaccounts[0].id,
    open=True
)

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

Place an order

Orders and other POST requests require that the user provides an EIP-712 signature. The SDK will handle signatures for you if you provide a private key when initializing the client.

# Select a subaccount
subaccount = client.subaccounts[0]

# Place a limit order
limit_order = client.create_order(
    order_type="LIMIT",
    quantity=0.01,
    side=0,  # 0 for buy, 1 for sell
    price=50000.0,
    time_in_force="GTC",
    ticker="BTCUSD",
    subaccount=subaccount.name,
)

# Place a market order
market_order = client.create_order(
    order_type="MARKET",
    quantity=0.01,
    side=0,
    ticker="BTCUSD",
    subaccount=subaccount.name,
)

# Refresh the order
market_order = client.get_order(market_order.order_id)

# Cancel the limit order
cancel_order = client.cancel_order(
    order_id=limit_order.order_id,
    sender=client.chain.address,
    subaccount=subaccount.name,
)