Ctrlk
Page cover
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Token Transfers

Overview

Token transfers encompass the management and tracking of supported tokens moving between your wallet and subaccounts on the Ethereal exchange. These movements primarily fall into two categories: deposits and withdrawals.

How Do I Deposit?

Deposits allow you to move tokens from your wallet into a specified subaccount on the Ethereal exchange. The process follows these steps:

  1. Token approval: ERC20 token approval to allow Ethereal to transfer tokens on your behalf

  2. Transact: Execute the deposit transaction, specifying the token, amount, and target subaccount

  3. Pending: Once deposited, tokens enter a pending state while confirmation occurs

  4. Confirmation: The deposit is synchronised with offchain systems

  5. Availability: After confirmation, funds become available for trading

Token deposits to a fresh subaccount will also automatically create a subaccount. See subaccounts and signers section to learn more.

Default gas estimation can occasionally be too low, where explicit setting the gas limit for the transaction will be needed. If you encounter the DelegationFailed() error when depositing, try adding gas: 250_000n to the viem deposit call.

Here's an example of how you could deposit using viem in TypeScript:

import {
  defineChain,
  erc20Abi,
  toHex,
  parseUnits,
  createWalletClient,
  http,
  createPublicClient,
  getAddress,
} from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { exchangeContractAbi } from './sample/exchange.abi';

// @see: docs.ethereal.trade for chain details
export const ETHEREAL_TESTNET_CHAIN = defineChain({
  id: 13374202,
  name: 'Ethereal Testnet',
  nativeCurrency: {
    decimals: 18,
    name: 'USDe',
    symbol: 'USDe',
  },
  rpcUrls: {
    default: {
      http: ['https://rpc.etherealtest.net'],
      webSocket: ['wss://rpc.etherealtest.net'],
    },
  },
  testnet: true,
});

const DEFAULT_SUBACCOUNT = toHex('primary', { size: 32 });

// Retrieve the token address via `GET /v1/token`.
const USDE_ADDRESS = '0xa1623E0AA40B142Cf755938b325321fB2c61Cf05';

const MAKER_MAKER_PK = '0x...'; // Your test private key

// `verifyingContract` can be found via `HTTP GET /v1/rpc/config`
const exchangeContract = getAddress(domain.verifyingContract);

const wallet = createWalletClient({
  account: privateKeyToAccount(MAKER_MAKER_PK),
  chain: ETHEREAL_TESTNET_CHAIN,
  transport: http(),
});
const publicClient = createPublicClient({ chain: ETHEREAL_TESTNET_CHAIN, transport: http() });

const deposit = async (amount: string) => {
  const nativeAmount = parseUnits(amount, 18); // USDe has 18 deciamls.
  const approveHash = await wallet.writeContract({
    address: USDE_ADDRESS,
    abi: erc20Abi,
    functionName: 'approve',
    args: [exchangeContract, nativeAmount],
  });
  await publicClient.waitForTransactionReceipt({ hash: approveHash });
  const hash = await wallet.writeContract({
    address: exchangeContract,
    abi: exchangeContractAbi,
    functionName: 'deposit',
    args: [DEFAULT_SUBACCOUNT, USDE_ADDRESS, nativeAmount, toHex('refCode', { size: 32 })],
  });
  await publicClient.waitForTransactionReceipt({ hash });
  console.log('Deposited!');
};

deposit('1000') // Deposit 1000 USDe

Once your deposit is confirmed, you can view your subaccount balance by calling:

Each token in your subaccount has two balance components:

  • Available (free): Tokens that can be used to open new positions or withdraw

  • TotalUsed (locked): Tokens currently allocated as margin for open positions and resting orders

Visit supported tokens and subaccounts and signers to learn more.

Important to raise that the trading API does NOT allow users to withdraw unrealized profits. Any unrealized profits must be realized before they become available margin. Refer to margin health to learn more about initial and maintenance margin.

Depositing USDe

Ethereal is designed to support any approved ERC20 token, though USDe will be the only depositable token available at launch. Since USDe serves as the native gas token on the Ethereal appchain, it requires an additional wrapping step before deposit.

Users must first wrap their USDe to WUSDe using our immutable wrapping contract, which implements the same interface as WETH for familiar functionality. The WUSDe contract address can be retrieved by querying the USD endpoint in our API, and once wrapped, the tokens can be deposited normally into the platform.

However, this process can be cumbersome, so we recommend using the provided depositUsd convenience method instead, which handles the wrapping and deposit process automatically.

Initiate Token Withdrawals

Withdrawals move tokens from your subaccount back to your wallet. The process follows these steps:

  1. Initiation: Withdrawals begin with a request through the trading API

  2. Deduction: Once request is processed, funds are immediately deducted from the subaccount

  3. Onchain relay: The initiate withdrawal request is relayed onchain

  4. Finalize: Users can claim their withdrawal after the lockout period expires

When the wrapped native token (WUSDe) is withdrawn it is unwrapped back to the native USDe as part of the withdrawal process.

To initiate a token withdrawal:

You can query any pending or past withdrawals by:

Once relayed onchain and after the lockout period has past, users can finalize their withdrawal:

An offchain withdraw claimer automatically finalizes withdrawals on users behalf but using the digest a user is always able to finalizeWithdraw() without the claimer.

Retrieve Transfer History

To view all historical transfers for a specific subaccount, query:

Token Transfer Fees

Fees on transfers primarily serve to deter spam and minimize network congestion, rather than as a revenue source. Fee structures are configurable per token and may be adjusted over time.

Both deposit and withdrawals can be configured to charge fees (denomianted in native token units). As of writing right now, there are zero deposit fees however USDe is configured to charge a nominal withdrawal fee of 2.

PreviousProductsNextSupported Tokens

Last updated