Enums
OrderSide
Copy
export enum OrderSide {
BUY = 'BUY',
SELL = 'SELL'
}
OrderType
Copy
export enum OrderType {
LIMIT = 'LIMIT',
MARKET = 'MARKET',
STOP_MARKET = 'STOP_MARKET',
STOP_LIMIT = 'STOP_LIMIT'
}
OrderStatus
Copy
export enum OrderStatus {
OPEN = 'OPEN',
FILLED = 'FILLED',
PARTIALLY_FILLED = 'PARTIALLY_FILLED',
CANCELED = 'CANCELED',
REJECTED = 'REJECTED',
UNKNOWN = 'UNKNOWN'
}
PositionSide
Copy
export enum PositionSide {
LONG = 'LONG',
SHORT = 'SHORT'
}
ExchangeName
Copy
export enum ExchangeName {
HYPERLIQUID = 'hyperliquid',
ASTER = 'aster',
LIGHTER = 'lighter',
AVANTIS = 'avantis'
}
SystemStatus
Copy
export enum SystemStatus {
OPERATIONAL = 'operational',
DEGRADED = 'degraded',
PARTIAL_OUTAGE = 'partial_outage',
MAJOR_OUTAGE = 'major_outage',
MAINTENANCE = 'maintenance'
}
ExchangeStatus
Copy
export enum ExchangeStatus {
OPERATIONAL = 'operational',
DEGRADED = 'degraded',
LIMITED = 'limited',
UNAVAILABLE = 'unavailable',
MAINTENANCE = 'maintenance'
}
TimeInForce
Copy
export enum TimeInForce {
GTC = 'GTC', // Good Till Canceled
IOC = 'IOC', // Immediate Or Cancel
FOK = 'FOK' // Fill Or Kill
}
MarginMode
Copy
export enum MarginMode {
CROSS = 'CROSS',
ISOLATED = 'ISOLATED'
}
Core Trading Interfaces
Order
Copy
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
Copy
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
Copy
export interface OpenPositionRequest {
symbol: string;
direction: 'LONG' | 'SHORT';
size: string;
leverage?: number;
orderType: 'MARKET' | 'LIMIT';
limitPrice?: string;
preferredExchange?: 'lighter' | 'aster' | 'hyperliquid';
credentials: ExchangeCredentials;
}
ClosePositionRequest
Copy
export interface ClosePositionRequest {
symbol: string;
direction: 'LONG' | 'SHORT';
size: string;
orderType?: 'MARKET' | 'LIMIT';
limitPrice?: string;
preferredExchange?: 'lighter' | 'aster' | 'hyperliquid';
credentials: ExchangeCredentials;
}
SmartOrderRequest
Copy
export interface SmartOrderRequest {
symbol: string;
side: 'BUY' | 'SELL';
type: 'MARKET' | 'LIMIT';
quantity: string;
price?: string;
reduceOnly?: boolean;
preferredExchange?: 'lighter' | 'aster' | 'hyperliquid';
}
Position
Copy
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
Copy
export interface Balance {
asset: string;
free: string;
locked?: string;
total: string;
crossWalletBalance?: string;
crossUnPnl?: string;
maxWithdrawAmount?: string;
}
Exchange Balance Responses
Copy
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
Copy
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
Copy
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
Copy
export interface AggregatedTicker {
symbol: string;
exchanges: {
hyperliquid?: Ticker;
lighter?: Ticker;
aster?: Ticker;
[exchange: string]: Ticker | undefined;
};
}
Trade
Copy
export interface Trade {
id: string;
symbol: string;
exchange: ExchangeName;
price: string;
size: string;
side: OrderSide;
timestamp: number;
}
OrderBook
Copy
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
Copy
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;
}
Copy
### 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
Copy
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
Copy
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
Copy
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
Copy
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
Copy
export interface LighterImportRequest {
walletIdOrAddress: string;
accountIndex: number;
apiKeyIndex: number;
apiPublicKey: string;
apiPrivateKey: string;
}
export interface LighterImportResponse {
success: boolean;
message: string;
timestamp: number;
}
Deposit
Copy
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
Copy
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
Copy
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
Copy
// 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
Copy
// 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
Copy
// 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
Copy
// 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
Copy
// 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
Copy
// 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.