Skip to main content

​
Overview

This document explains the complete user flow for integrating with Lighter DEX through HyperDEX. The process involves creating a server wallet, registering with exchanges, depositing funds, and executing trades.
Important for Lighter DEX Users: Before using Lighter DEX through HyperDEX, you must:
  1. Create an account on Lighter DEX
  2. Deposit funds into your Lighter account
  3. Generate API keys from the Lighter platform
  4. Use those API keys in HyperDEX API calls

​
Complete User Flow Diagrams

​
Aster DEX Flow

​
Hyperliquid DEX Flow

​
Lighter DEX Flow

​
Avantis DEX Flow

Avantis Architecture: Unlike other exchanges, Avantis uses a split architecture. The Tide backend provides data only (positions, orders, history, balances). All trade execution happens client-side via wallet signing on the Base network through the useAvantisTrade React hook.

​
Step-by-Step Flow

​
Step 1: Create Server Wallet

Create a server-side wallet secured with MPC (Multi-Party Computation) key management through Dynamic Labs. Endpoint: POST /api/wallets Request: 
{
  "userId": "user_123"
}
What Happens:
  • Dynamic Labs creates a wallet with 2-of-2 MPC threshold scheme
  • Wallet includes: private key shares, public key, and address
  • Wallet is stored securely in the database
Response: 
{
  "success": true,
  "userId": "user_123",
  "address": "0x173404aAAa4d6539e2C7dbcC1931Cf41b3A3D5c7",
  "walletId": "29dd4dc0-1ff9-4df6-a19f-936f997cbc5a",
  "publicKey": "04090ce18936a64a24c48624d5734edf96d33a5f3d79bb014f27ebfa2197a813cfc46009ac278f4de56afc3e48733d1adf1a6cf804e6b20ddf55a9f5d4f651104a"
}
Key Information to Store:
  • userId - User identifier for wallet lookup
  • address - Wallet address (0x…) needed for deposits & transactions
  • walletId - Wallet UUID needed for API registration & signing
  • publicKey - Public key for verification

​
Step 2: Register API Keys with Exchanges

After wallet creation, register the wallet with exchanges to get API credentials for trading.

​
Aster Exchange

Endpoint: POST /api/trading/aster/apikey Request: 
{
  "walletIdOrAddress": "29dd4dc0-1ff9-4df6-a19f-936f997cbc5a"
}
Can use any of these identifiers:
  • userId: “user_123”
  • walletId: “29dd4dc0-1ff9-4df6-a19f-936f997cbc5a”
  • address: “0x173404aAAa4d6539e2C7dbcC1931Cf41b3A3D5c7”
Response: 
{
  "success": true,
  "message": "API key generated successfully",
  "data": {
    "signerAddress": "0x173404aAAa4d6539e2C7dbcC1931Cf41b3A3D5c7",
    "createdAt": "2025-11-27T02:00:00Z"
  }
}

​
Hyperliquid Exchange

Endpoint: POST /api/trading/hyperliquid/apikey Request: 
{
  "walletIdOrAddress": "user_123"
}
Response: 
{
  "success": true,
  "data": {
    "apiWalletAddress": "0xa95B2862DF3896cA5c284725D71Ab373e78de96b",
    "apiPrivateKey": "0x01c6baa2be13089ff710c2f037fdb7aec2fdc5faf2e12afe6ff99cc8d5fe7c5a",
    "mainWalletAddress": "0x07943f0f79097572451601e768c329a2765f2ea2",
    "expiryTimestamp": 1779903620779
  }
}

​
Lighter Exchange

Lighter DEX Requirement: You do NOT need to register API keys through HyperDEX for Lighter. Instead:
  1. Create an account on Lighter DEX
  2. Deposit funds directly on Lighter
  3. Generate API keys from your Lighter account dashboard
  4. Provide these credentials as query parameters when making order requests

​
Step 3: Fund the Server Wallet

Before depositing to exchanges, your server wallet must have:
  1. USDT - Trading token on BSC
  2. BNB - Native currency for gas fees
How to Fund: 
User's Personal Wallet
    ↓ (transfer USDT + BNB)
Server Wallet (0x173404aAAa4d6539e2C7dbcC1931Cf41b3A3D5c7)

​
Step 4: Deposit to Exchange

Endpoint: POST /api/trading/:exchange/deposit

​
Aster Deposit Example

Request: 
{
  "walletIdOrAddress": "user_123",
  "tokenSymbol": "USDT",
  "amount": "100",
  "broker": 1000,
  "network": "bnb"
}
Parameters:
FieldTypeRequiredDescription
walletIdOrAddressstringYesCan be userId, walletId, or address
tokenSymbolstringYesToken to deposit (e.g., “USDT”)
amountstringYesAmount in token units (e.g., “100” = 100 USDT)
brokernumberYesBroker ID (default: 1000)
networkstringYesNetwork (“ethereum”, “arbitrum”, “bnb”)
What Happens:
  1. Check Balance - Verify server wallet has sufficient USDT and BNB for gas
  2. Approve Token (if needed) - Sign approval transaction and broadcast
  3. Deposit Transaction - Sign deposit transaction to exchange contract
  4. Internal Transfer (optional) - Transfer from Spot to Futures/Perp account
Response: 
{
  "success": true,
  "data": {
    "txHash": "0x1234abcd...",
    "txUrl": "https://bscscan.com/tx/0x1234abcd...",
    "amount": "100",
    "token": "USDT",
    "network": "bsc",
    "decimals": 6,
    "blockNumber": "12345678"
  }
}

​
Transfer Between Spot and Perp Accounts

Endpoint: POST /api/aster/wallet/transfer Request: 
{
  "walletId": "29dd4dc0-1ff9-4df6-a19f-936f997cbc5a",
  "amount": "50",
  "asset": "USDT",
  "clientTranId": "transfer_001",
  "kindType": "SPOT_FUTURE"
}
Direction Options:
  • SPOT_FUTURE - Transfer from Spot → Futures
  • FUTURE_SPOT - Transfer from Futures → Spot

​
Step 5: Trading Operations

​
Aster Trading

Endpoint: POST /api/trading/aster/orders Headers: 
x-wallet-id: ee337309-3e77-4278-b21a-4681468168ba
Request: 
{
  "userId": "0x07943f0f79097572451601e768c329a2765f2ea2",
  "symbol": "BTCUSDT",
  "side": "BUY",
  "type": "MARKET",
  "quantity": "0.1",
  "reduceOnly": true
}

​
Hyperliquid Trading

Endpoint: POST /api/trading/hyperliquid/orders Request: 
{
  "userId": "ee337309-3e77-4278-b21a-4681468168ba",
  "symbol": "BTC-PERP",
  "side": "BUY",
  "type": "MARKET",
  "quantity": "0.1",
  "price": "1",
  "reduceOnly": true
}

​
Lighter Trading

Lighter DEX Trading: Lighter requires API credentials as query parameters in the order request.
Endpoint: POST /api/trading/lighter/orders?apiKeyPrivateKey=<key>&apiKeyIndex=<index>&accountIndex=<account> Query Parameters:
  • apiKeyPrivateKey - Your Lighter API key private key (hex format)
  • apiKeyIndex - API key index from Lighter
  • accountIndex - Your Lighter account index
Request: 
{
  "userId": "0x07943f0f79097572451601e768c329a2765f2ea2",
  "symbol": "USDC",
  "side": "BUY",
  "type": "MARKET",
  "quantity": "1.1",
  "price": "1",
  "reduceOnly": true
}

​
Step 6: Withdraw from Exchange

Endpoint: POST /api/trading/:exchange/withdraw

​
Aster Withdrawal

Request: 
{
  "walletAddress": "0x07943f0f79097572451601e768c329a2765f2ea2",
  "chainId": 56,
  "asset": "USDT",
  "amount": "50",
  "broker": 1000,
  "receiver": "0x07943f0f79097572451601e768c329a2765f2ea2",
  "accountType": "perp"
}
Important: The receiver address should match the wallet address for signature verification. Response: 
{
  "success": true,
  "withdrawalId": "4c93dfe1-8c62-40ae-93d7-f02a999ab2f7",
  "status": "submitted",
  "timestamp": 1698840000000
}

​
Hyperliquid Withdrawal

Request: 
{
  "walletIdOrAddress": "0x07943f0f79097572451601e768c329a2765f2ea2",
  "destination": "0x07943f0f79097572451601e768c329a2765f2ea2",
  "amount": "5",
  "feeBuffer": "1.1",
  "chainId": 42161
}
Response: 
{
  "success": true,
  "withdrawalId": 9183374,
  "status": "accepted",
  "network": "arbitrum",
  "timestamp": 1698840000000
}

​
Summary

The complete flow for using HyperDEX with exchange integrations:
  1. Create Wallet - Generate MPC-secured server wallet via Dynamic Labs
  2. Register API Keys - Link wallet to exchanges (Aster, Hyperliquid)
  3. Fund Wallet - Transfer USDT and gas tokens to server wallet
  4. Deposit - Move funds from wallet to exchange accounts
  5. Trade - Execute orders across multiple exchanges
  6. Withdraw - Move funds back to server wallet or personal wallet
For Avantis, the flow is simpler: fund your wallet with USDC on Base, then use the Tide backend for data queries and the frontend useAvantisTrade hook for on-chain trade execution. No server wallet or API key registration is required.
For Lighter DEX specifically, remember to create your account and generate API keys directly on their platform before using HyperDEX APIs.