Skip to main content
Complete TypeScript interfaces and enums for all DEXAGG API data structures.

Enums

OrderSide

export enum OrderSide {
  BUY = 'BUY',
  SELL = 'SELL'
}

OrderType

export enum OrderType {
  LIMIT = 'LIMIT',
  MARKET = 'MARKET',
  STOP_MARKET = 'STOP_MARKET',
  STOP_LIMIT = 'STOP_LIMIT'
}

OrderStatus

export enum OrderStatus {
  OPEN = 'OPEN',
  FILLED = 'FILLED',
  PARTIALLY_FILLED = 'PARTIALLY_FILLED',
  CANCELED = 'CANCELED',
  REJECTED = 'REJECTED',
  UNKNOWN = 'UNKNOWN'
}

PositionSide

export enum PositionSide {
  LONG = 'LONG',
  SHORT = 'SHORT'
}

ExchangeName

export enum ExchangeName {
  HYPERLIQUID = 'hyperliquid',
  ASTER = 'aster',
  LIGHTER = 'lighter',
  AVANTIS = 'avantis'
}

SystemStatus

export enum SystemStatus {
  OPERATIONAL = 'operational',
  DEGRADED = 'degraded',
  PARTIAL_OUTAGE = 'partial_outage',
  MAJOR_OUTAGE = 'major_outage',
  MAINTENANCE = 'maintenance'
}

ExchangeStatus

export enum ExchangeStatus {
  OPERATIONAL = 'operational',
  DEGRADED = 'degraded',
  LIMITED = 'limited',
  UNAVAILABLE = 'unavailable',
  MAINTENANCE = 'maintenance'
}

TimeInForce

export enum TimeInForce {
  GTC = 'GTC', // Good Till Canceled
  IOC = 'IOC', // Immediate Or Cancel
  FOK = 'FOK'  // Fill Or Kill
}

MarginMode

export enum MarginMode {
  CROSS = 'CROSS',
  ISOLATED = 'ISOLATED'
}

Core Trading Interfaces

Order

export interface Order {
  orderId: string;
  symbol: string;
  side: OrderSide;
  type: OrderType;
  status: OrderStatus;
  price: string;
  quantity: string;
  filledQuantity: string;
  averagePrice?: string;
  timestamp: number;
  exchange: ExchangeName;
  clientOrderId?: string;
  timeInForce?: TimeInForce;
  reduceOnly?: boolean;
  triggerPrice?: string;
}

PlaceOrderRequest

export interface PlaceOrderRequest {
  symbol: string;
  side: OrderSide;
  type: OrderType;
  quantity: string;
  price?: string;
  timeInForce?: TimeInForce;
  reduceOnly?: boolean;
  clientOrderId?: string;
  triggerPrice?: string;
  preferredExchange?: ExchangeName;
  credentials: ExchangeCredentials;
}

OpenPositionRequest

export interface OpenPositionRequest {
  symbol: string;
  direction: 'LONG' | 'SHORT';
  size: string;
  leverage?: number;
  orderType: 'MARKET' | 'LIMIT';
  limitPrice?: string;
  preferredExchange?: 'lighter' | 'aster' | 'hyperliquid';
  credentials: ExchangeCredentials;
}

ClosePositionRequest

export interface ClosePositionRequest {
  symbol: string;
  direction: 'LONG' | 'SHORT';
  size: string;
  orderType?: 'MARKET' | 'LIMIT';
  limitPrice?: string;
  preferredExchange?: 'lighter' | 'aster' | 'hyperliquid';
  credentials: ExchangeCredentials;
}

SmartOrderRequest

export interface SmartOrderRequest {
  symbol: string;
  side: 'BUY' | 'SELL';
  type: 'MARKET' | 'LIMIT';
  quantity: string;
  price?: string;
  reduceOnly?: boolean;
  preferredExchange?: 'lighter' | 'aster' | 'hyperliquid';
}

Position

export interface Position {
  symbol: string;
  exchange: ExchangeName;
  walletAddress?: string;
  direction: PositionSide;
  size: string;
  entryPrice: string;
  markPrice?: string;
  liquidationPrice?: string;
  unrealizedPnl: string;
  unrealizedPnlPercent?: string;
  leverage: number;
  collateral?: string;
  margin?: string;
  marginMode?: MarginMode;
  timestamp?: number;
}

Balance

export interface Balance {
  asset: string;
  free: string;
  locked?: string;
  total: string;
  crossWalletBalance?: string;
  crossUnPnl?: string;
  maxWithdrawAmount?: string;
}

Exchange Balance Responses

export interface HyperliquidBalanceResponse {
  success: boolean;
  data: {
    success: boolean;
    exchange: 'hyperliquid';
    address: string;
    balances: Balance[];
    withdrawable: string;
    accountValue: string;
  };
  timestamp: number;
}

export interface LighterBalanceResponse {
  success: boolean;
  data: {
    success: boolean;
    exchange: 'lighter';
    address: string;
    accountIndex: number;
    balances: Balance[];
    collateral: string;
    availableBalance: string;
    accountType: 'standard' | 'isolated';
  };
  timestamp: number;
}

export interface AsterBalanceResponse {
  success: boolean;
  data: {
    success: boolean;
    exchange: 'aster';
    address: string;
    balances: Balance[];
    accountType: 'futures' | 'spot';
  };
  timestamp: number;
}

ExchangeCredentials

export interface ExchangeCredentials {
  lighter?: {
    apiKeyPrivateKey: string;
    accountIndex: number;
  };
  aster?: {
    apiKey: string;
    apiSecret: string;
    walletAddress: string;
  };
  hyperliquid?: {
    privateKey: string;
  };
  avantis?: {
    apiKey: string;
    apiSecret: string;
    walletAddress: string;
  };
}

Market Data Interfaces

Ticker

export interface Ticker {
  success: boolean;
  exchange: ExchangeName;
  symbol: string;
  markPrice?: string;
  lastPrice?: string;
  prevDayPrice?: string;
  change24h?: string;
  change24hAbs?: string;
  volume24h?: string;
  openInterest?: string;
  high24h?: string;
  low24h?: string;
  indexPrice?: string;
  openPrice?: string;
  fundingRate?: string;
  nextFundingTime?: number;
  volumeBase?: string;
  marketId?: number;
  note?: string;
  asterSymbol?: string;
  error?: string;
  timestamp?: number;
}

AggregatedTicker

export interface AggregatedTicker {
  symbol: string;
  exchanges: {
    hyperliquid?: Ticker;
    lighter?: Ticker;
    aster?: Ticker;
    [exchange: string]: Ticker | undefined;
  };
}

Trade

export interface Trade {
  id: string;
  symbol: string;
  exchange: ExchangeName;
  price: string;
  size: string;
  side: OrderSide;
  timestamp: number;
}

OrderBook

export interface OrderBook {
  symbol: string;
  timestamp: number;
  bids: OrderBookLevel[];
  asks: OrderBookLevel[];
}

export interface OrderBookLevel {
  price: string;
  size: string;
  exchange: ExchangeName;
  count: number;
}

Routing and Execution Interfaces

RoutingRecommendation

export interface RoutingRecommendation {
  symbol: string;
  side: 'BUY' | 'SELL';
  routing: RoutingInfo;
}

export interface RoutingInfo {
  recommended: 'lighter' | 'aster' | 'hyperliquid';
  price: number;
  reason: string;
  savings: number;
  savingsPercent: number;
  alternatives: Record<string, AlternativeVenue>;
}

export interface AlternativeVenue {
  price: number;
  available: boolean;
  reason?: string;
}

export interface RoutingRecommendationResponse {
  success: boolean;
  data: RoutingRecommendation;
  timestamp: number;
}

### ExecutionResponse

```typescript
export interface ExecutionResponse {
  success: boolean;
  data: {
    executedOn: 'lighter' | 'aster' | 'hyperliquid';
    order: SmartOrderResult;
    routing: RoutingInfo;
    execution: ExecutionMetadata;
  };
  timestamp: number;
}

export interface SmartOrderResult {
  orderId: string;
  symbol: string;
  status: 'FILLED' | 'PARTIALLY_FILLED' | 'NEW' | 'CANCELED';
  price: number;
  quantity: number;
  side: 'BUY' | 'SELL';
  timestamp: number;
}

export interface ExecutionMetadata {
  timestamp: number;
  latencyMs: number;
}

export interface Fill {
  price: string;
  quantity: string;
  timestamp: number;
  fee?: string;
  feeAsset?: string;
}

System Status Interfaces

SystemStatusResponse

export interface SystemStatusResponse {
  status: SystemStatus;
  timestamp: number;
  adapters: Record<ExchangeName, ExchangeStatusInfo>;
  uptime: number;
  version: string;
}

export interface ExchangeStatusInfo {
  status: ExchangeStatus;
  latency: number;
  lastUpdate: number;
  errorRate: number;
  features: ExchangeFeatures;
}

export interface ExchangeFeatures {
  trading: boolean;
  marketData: boolean;
  positions: boolean;
  balances: boolean;
}

Response Wrappers

API Response

export interface ApiResponse<T> {
  success: boolean;
  data: T;
  timestamp: number;
  error?: ApiError;
}

export interface ApiError {
  code: number;
  type: string;
  message: string;
  details?: string;
}

Collection Responses

export type TickersResponse = AggregatedTicker;

export type AggregatedTickerApiResponse = ApiResponse<AggregatedTicker | Ticker>;

export type ExchangeTickerApiResponse = ApiResponse<Ticker>;

export interface TradesResponse {
  trades: Trade[];
}

export interface PositionsResponse {
  success: boolean;
  walletAddress: string;
  positions: Position[];
  totalPositions: number;
}

export interface SingleExchangePositionsResponse {
  success: boolean;
  exchange: 'lighter' | 'aster' | 'hyperliquid';
  walletAddress: string;
  positions: Position[];
  totalPositions: number;
}

export interface BalancesResponse {
  balances: Balance[];
  totalValueUSD: string;
}

export type ExchangeBalanceResponse = 
  | HyperliquidBalanceResponse 
  | LighterBalanceResponse 
  | AsterBalanceResponse;

Account Management Interfaces

Register API Key

export interface RegisterAPIRequest {
  // Common fields
  walletId?: string;
  address?: string;
  
  // Hyperliquid specific
  agentAddress?: string;
  agentName?: string;
  
  // Lighter specific
  seed?: string;
}

export interface RegisterAPIResponse {
  success: boolean;
  message: string;
  data: {
    // Aster
    keyId?: string;
    signerAddress?: string;
    
    // Hyperliquid
    approveAgentResult?: {
      status: string;
    };
    apiKey?: {
      publicKey: string;
    };
    
    // Lighter
    publicKey?: string;
    privateKey?: string;
    
    createdAt?: number;
  };
  timestamp: number;
}

Import Lighter Credentials

export interface LighterImportRequest {
  walletIdOrAddress: string;
  accountIndex: number;
  apiKeyIndex: number;
  apiPublicKey: string;
  apiPrivateKey: string;
}

export interface LighterImportResponse {
  success: boolean;
  message: string;
  timestamp: number;
}

Deposit

export interface AsterDepositRequest {
  fromAddress: string;
  tokenSymbol: string;
  amount: string;
  broker: number;
  allowanceSignedTx?: string;
  signedDepositTx: string;
}

export interface HyperliquidDepositRequest {
  fromAddress: string;
  amount: string;
  tokenSymbol: string;
  signedDepositTx: string;
}

export interface LighterDepositRequest {
  fromAddress: string;
  amount: string;
  tokenSymbol: string;
  allowanceSignedTx?: string;
  depositSignedTx: string;
}

export interface AsterDepositResponse {
  success: boolean;
  data: {
    allowanceSignedTxHash?: string;
    txAllowanceUrl?: string;
    txHash: string;
    txUrl: string;
  };
}

export interface HyperliquidDepositResponse {
  success: boolean;
  data: {
    fromAddress: string;
    txHash: string;
    amount: string;
    tokenInfo: string;
  };
}

export interface LighterDepositResponse {
  success: boolean;
  data: {
    allowanceSignedTxHash?: string;
    depositTxHash: string;
  };
}

export interface OrdersResponse {
  orders: Order[];
}

export interface OrderStatusResponse {
  success: boolean;
  data: Order;
  timestamp?: number;
}

Usage Examples

TypeScript Client Setup

import {
  Order,
  OpenPositionRequest,
  ClosePositionRequest,
  SmartOrderRequest,
  Position,
  Balance,
  OrderSide,
  OrderType,
  PositionSide,
  ExchangeName,
  ApiResponse,
  AsterDepositRequest,
  AsterDepositResponse,
  HyperliquidDepositRequest,
  HyperliquidDepositResponse,
  LighterDepositRequest,
  LighterDepositResponse
} from './dexagg-types';

class DexaggClient {
  private baseUrl = 'https://api.dexaggregatorbeta.xyz';

  async openPosition(request: OpenPositionRequest): Promise<ApiResponse<ExecutionResponse>> {
    // Implementation for opening positions
  }

  async closePosition(request: ClosePositionRequest): Promise<ApiResponse<ExecutionResponse>> {
    // Implementation for closing positions
  }

  async executeSmartOrder(request: SmartOrderRequest): Promise<ApiResponse<ExecutionResponse>> {
    // Implementation for smart order execution
  }

  async getRoutingRecommendation(symbol: string, side?: 'BUY' | 'SELL'): Promise<RoutingRecommendationResponse> {
    const sideParam = side ? `?side=${side}` : '';
    const response = await fetch(`${this.baseUrl}/api/trade/routing/${symbol}${sideParam}`, {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' }
    });
    return response.json();
  }

  async getAllPositions(walletAddress: string): Promise<PositionsResponse> {
    const response = await fetch(`${this.baseUrl}/api/trading/positions/all/${walletAddress}`, {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' }
    });
    return response.json();
  }

  async getExchangePositions(
    exchange: 'lighter' | 'aster' | 'hyperliquid',
    walletAddress: string
  ): Promise<SingleExchangePositionsResponse> {
    const response = await fetch(`${this.baseUrl}/api/trading/${exchange}/positions/${walletAddress}`, {
      method: 'GET',
      headers: { 'Content-Type': 'application/json' }
    });
    return response.json();
  }

  async getOrderStatus(
    exchange: 'lighter' | 'aster' | 'hyperliquid',
    orderId: string,
    symbol?: string
  ): Promise<OrderStatusResponse> {
    const symbolParam = symbol ? `?symbol=${symbol}` : '';
    const response = await fetch(
      `${this.baseUrl}/api/trading/${exchange}/orders/${orderId}/status${symbolParam}`,
      {
        method: 'GET',
        headers: { 'Content-Type': 'application/json' }
      }
    );
    return response.json();
  }

  async getBalances(asset?: string): Promise<ApiResponse<BalancesResponse>> {
    // Implementation for fetching balances across all exchanges
  }

  async getExchangeBalance(
    exchange: 'hyperliquid' | 'lighter' | 'aster',
    walletAddress: string
  ): Promise<ExchangeBalanceResponse> {
    const response = await fetch(
      `${this.baseUrl}/api/trading/${exchange}/balances?walletAddress=${walletAddress}`,
      {
        method: 'GET',
        headers: { 'Content-Type': 'application/json' }
      }
    );
    return response.json();
  }

  async registerAPIKey(
    exchange: 'hyperliquid' | 'lighter' | 'aster',
    request: RegisterAPIRequest
  ): Promise<RegisterAPIResponse> {
    const response = await fetch(
      `${this.baseUrl}/trading/${exchange}/registerAPI`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request)
      }
    );
    return response.json();
  }

  async depositToAster(request: AsterDepositRequest): Promise<AsterDepositResponse> {
    const response = await fetch(
      `${this.baseUrl}/api/trading/aster/deposit`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request)
      }
    );
    return response.json();
  }

  async depositToHyperliquid(request: HyperliquidDepositRequest): Promise<HyperliquidDepositResponse> {
    const response = await fetch(
      `${this.baseUrl}/api/trading/hyperliquid/deposit`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request)
      }
    );
    return response.json();
  }

  async depositToLighter(request: LighterDepositRequest): Promise<LighterDepositResponse> {
    const response = await fetch(
      `${this.baseUrl}/api/trading/lighter/deposit`,
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(request)
      }
    );
    return response.json();
  }

  async getSystemStatus(): Promise<ApiResponse<SystemStatusResponse>> {
    // Implementation for system status
  }

  // Market Data Methods
  async getOrderBook(symbol: string, depth?: number): Promise<ApiResponse<OrderBook>> {
    // Implementation for order book
  }

  async getTicker(symbol: string): Promise<AggregatedTickerApiResponse> {
    // Implementation for aggregated ticker data
  }

  async getExchangeTicker(
    exchange: 'lighter' | 'aster' | 'hyperliquid',
    symbol: string
  ): Promise<ExchangeTickerApiResponse> {
    // Implementation for single-exchange ticker data
  }

  async getTrades(symbol: string, limit?: number): Promise<ApiResponse<TradesResponse>> {
    // Implementation for recent trades
  }
}

Error Handling

try {
  const response = await client.openPosition({
    symbol: 'BTC',
    direction: 'LONG',
    size: '0.1',
    leverage: 10,
    orderType: 'MARKET',
    credentials: {
      lighter: {
        apiKeyPrivateKey: '0x...',
        accountIndex: 0
      }
    }
  });

  if (response.success) {
    console.log('Position opened:', response.data);
  } else {
    console.error('Error:', response.error);
  }
} catch (error) {
  console.error('Network error:', error);
}

Fetching Positions

// Get all positions across all exchanges
const allPositions = await client.getAllPositions('0xabc123...');
console.log(`Total positions: ${allPositions.totalPositions}`);
allPositions.positions.forEach(pos => {
  console.log(`${pos.exchange}: ${pos.symbol} ${pos.direction} ${pos.size}`);
});

// Get positions on a specific exchange
const lighterPositions = await client.getExchangePositions('lighter', '0xabc123...');
console.log(`Lighter positions: ${lighterPositions.totalPositions}`);

Checking Order Status

// Check order status with optional symbol hint
const orderStatus = await client.getOrderStatus('lighter', '12345', 'BTC');
if (orderStatus.success) {
  console.log(`Order ${orderStatus.data.orderId} status: ${orderStatus.data.status}`);
  console.log(`Filled: ${orderStatus.data.filledQuantity}/${orderStatus.data.quantity}`);
}

Getting Routing Recommendations

// Get routing recommendation for buying BTC
const routing = await client.getRoutingRecommendation('BTC', 'BUY');
if (routing.success) {
  console.log(`Best exchange: ${routing.data.routing.recommended}`);
  console.log(`Price: ${routing.data.routing.price}`);
  console.log(`Savings: ${routing.data.routing.savingsPercent}%`);
}

Fetching Balances

// Get balance from a specific exchange
const hyperliquidBalance = await client.getExchangeBalance(
  'hyperliquid',
  '0xE7bECcEC683a6e141EaD23237088CfbC348b2295'
);

if (hyperliquidBalance.success) {
  console.log(`Exchange: ${hyperliquidBalance.data.exchange}`);
  console.log(`Account Value: ${hyperliquidBalance.data.accountValue}`);
  hyperliquidBalance.data.balances.forEach(balance => {
    console.log(`${balance.asset}: ${balance.free} (free) / ${balance.total} (total)`);
  });
}

// Get balance from Lighter
const lighterBalance = await client.getExchangeBalance(
  'lighter',
  '0xE7bECcEC683a6e141EaD23237088CfbC348b2295'
);

if (lighterBalance.success && lighterBalance.data.exchange === 'lighter') {
  console.log(`Account Index: ${lighterBalance.data.accountIndex}`);
  console.log(`Collateral: ${lighterBalance.data.collateral}`);
  console.log(`Available: ${lighterBalance.data.availableBalance}`);
}

// Get balance from Aster
const asterBalance = await client.getExchangeBalance(
  'aster',
  '0x2443874d3FFF541B98d02198D81dDD61a2ee3ae1'
);

if (asterBalance.success && asterBalance.data.exchange === 'aster') {
  asterBalance.data.balances.forEach(balance => {
    console.log(`${balance.asset}:`);
    console.log(`  Free: ${balance.free}`);
    console.log(`  Locked: ${balance.locked}`);
    console.log(`  Cross Wallet: ${balance.crossWalletBalance}`);
    console.log(`  Unrealized PnL: ${balance.crossUnPnl}`);
  });
}

Registering API Keys

// Register API key for Aster
const asterKey = await client.registerAPIKey('aster', {
  address: '0xE7bECcEC683a6e141EaD23237088CfbC348b2295'
});

if (asterKey.success) {
  console.log(`Key ID: ${asterKey.data.keyId}`);
  console.log(`Signer: ${asterKey.data.signerAddress}`);
}

// Register API key for Hyperliquid with agent
const hyperliquidKey = await client.registerAPIKey('hyperliquid', {
  agentAddress: '0x1234567890abcdef...',
  agentName: 'Trading Bot',
  address: '0xE7bECcEC683a6e141EaD23237088CfbC348b2295'
});

if (hyperliquidKey.success) {
  console.log(`Agent approved: ${hyperliquidKey.data.approveAgentResult?.status}`);
  console.log(`Public key: ${hyperliquidKey.data.apiKey?.publicKey}`);
}

// Register API key for Lighter
const lighterKey = await client.registerAPIKey('lighter', {
  walletId: 'wallet_123',
  seed: 'optional_seed'
});

if (lighterKey.success) {
  console.log(`Public key: ${lighterKey.data.publicKey}`);
  // Store private key securely
  console.log(`Private key: ${lighterKey.data.privateKey}`);
}

Making Deposits

// Deposit to Aster (BNB Chain)
const asterDeposit = await client.depositToAster({
  fromAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  tokenSymbol: 'USDT',
  amount: '10000000000000000000', // 10 USDT (18 decimals)
  broker: 1000,
  allowanceSignedTx: '0x02f8b3...', // optional approve tx
  signedDepositTx: '0x02f8d5...'
});

if (asterDeposit.success) {
  console.log(`Deposit hash: ${asterDeposit.data.txHash}`);
  console.log(`Deposit URL: ${asterDeposit.data.txUrl}`);
  if (asterDeposit.data.allowanceSignedTxHash) {
    console.log(`Allowance hash: ${asterDeposit.data.allowanceSignedTxHash}`);
    console.log(`Allowance URL: ${asterDeposit.data.txAllowanceUrl}`);
  }
}

// Deposit to Hyperliquid (Arbitrum USDC transfer)
const hyperliquidDeposit = await client.depositToHyperliquid({
  fromAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  amount: '10000000', // 10 USDC (6 decimals)
  tokenSymbol: 'USDC',
  signedDepositTx: '0x02f8b3...'
});

if (hyperliquidDeposit.success) {
  console.log(`Transfer tx hash: ${hyperliquidDeposit.data.txHash}`);
  console.log(`From address: ${hyperliquidDeposit.data.fromAddress}`);
  console.log(`Amount: ${hyperliquidDeposit.data.amount}`);
  console.log(`Token: ${hyperliquidDeposit.data.tokenInfo}`);
}

// Deposit to Lighter (Ethereum mainnet, $5 minimum)
const lighterDeposit = await client.depositToLighter({
  fromAddress: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb',
  amount: '10000000', // 10 USDC (6 decimals)
  tokenSymbol: 'USDC',
  allowanceSignedTx: '0x02f8b3...', // optional approve tx
  depositSignedTx: '0x02f8d5...'
});

if (lighterDeposit.success) {
  console.log(`Deposit hash: ${lighterDeposit.data.depositTxHash}`);
  if (lighterDeposit.data.allowanceSignedTxHash) {
    console.log(`Allowance hash: ${lighterDeposit.data.allowanceSignedTxHash}`);
  }
}
For complete schema definitions including all interfaces, enums, and type guards, see our comprehensive TypeScript definitions package available on npm.