AsterDex Futures SDK (Rust)

Async Rust SDK for the AsterDex Futures API v3. Covers REST and WebSocket APIs with EIP-712 signing.

Features

• Full REST API coverage (trading, market data, account, listen key, MMP, asset)
• WebSocket market data streams (13 event types with typed deserialization)
• WebSocket user data stream (order updates, account updates, config updates)
• EIP-712 Ethereum signing via alloy-rs
• Typed errors with rate-limit header exposure
• Raw JSON passthrough for untyped access

Installation

Add to Cargo.toml:

[dependencies]

asterdex-sdk = "0.1.3"

Quick Start

REST — Authenticate and place an order

use asterdex_sdk::{FuturesClient, PlaceOrderParams};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load credentials from environment variables:
    // ASTERDEX_USER, ASTERDEX_SIGNER_ADDRESS, ASTERDEX_SIGNER_PRIVATE_KEY, ASTERDEX_BASE_URL
    let client = FuturesClient::from_env()?;

    let order = client.place_order(PlaceOrderParams {
        symbol: "BTCUSDT".to_string(),
        side: "BUY".to_string(),
        order_type: "LIMIT".to_string(),
        quantity: "0.001".to_string(),
        price: Some("30000.0".to_string()),
        time_in_force: Some("GTC".to_string()),
        ..Default::default()
    }).await?;

    println!("Order placed: id={}", order.data.order_id);
    Ok(())
}

WebSocket — Subscribe to market streams

use asterdex_sdk::{WebSocketClient, WebSocketMessage};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ws = WebSocketClient::new("wss://fstream.asterdex-testnet.com")?;
    let mut stream = ws.subscribe(vec!["btcusdt@aggTrade", "btcusdt@markPrice"]).await?;

    while let Some(event) = stream.recv().await {
        match event? {
            WebSocketMessage::AggTrade(e) => println!("Trade: {} @ {}", e.symbol, e.price),
            WebSocketMessage::MarkPrice(e) => println!("Mark: {} = {}", e.symbol, e.mark_price),
            _ => {}
        }
    }
    Ok(())
}

WebSocket — User data stream

use asterdex_sdk::{FuturesClient, WebSocketClient, UserDataEvent};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let rest = FuturesClient::from_env()?;
    let listen_key = rest.create_listen_key().await?.data.listen_key;

    let ws = WebSocketClient::new("wss://fstream.asterdex-testnet.com")?;
    let mut stream = ws.subscribe_user_data(&listen_key).await?;

    while let Some(event) = stream.next_event().await {
        match event? {
            UserDataEvent::OrderUpdate(e) => {
                println!("Order update: {} {}", e.order.symbol, e.order.order_status)
            }
            _ => {}
        }
    }
    Ok(())
}

Environment Variables

Copy .env.example to .env and fill in your values. Never commit .env.

Architecture

Single-crate Rust library. Key modules:

FuturesClient is a type alias for RestClient. All futures endpoint methods live under src/futures/endpoints/ and are automatically available on FuturesClient.

See ARCHITECTURE.md for full design decisions and ADRs.

Error Handling

All methods return Result<ApiResponse<T>, AsterDexError>. Key error variants:

pub enum AsterDexError {
    ApiError { code: i64, msg: String },           // API-level error
    RateLimited { retry_after: Option<Duration> },  // HTTP 429
    IpBanned { retry_after: Option<Duration> },     // HTTP 418
    WebSocketError { message: String },
    ConfigError { message: String },
    SerdeError { message: String },
}

Integration Guide

For the complete API reference — all endpoints with request/response structs, usage examples, WebSocket stream types, and error handling patterns — see docs/integration_guide.md.

Topics covered:

• Market data (order book, klines, mark price, funding rate, tickers)
• Trading (place, modify, cancel, query orders; positions; batch orders)
• Account (balance, leverage, margin type, position mode, ADL quantile)
• Listen key lifecycle and user data WebSocket stream
• MMP (Market Maker Protection) endpoints
• Asset / sub-account wallet transfer
• Raw JSON passthrough (raw_get, raw_signed_post, etc.)
• Full WebSocketMessage and UserDataEvent type reference

Key Flows by Milestone

Testing

# Unit tests (no network required)

cargo test --lib


# Integration tests (requires testnet credentials in environment)

cargo test --test integration -- --ignored