hyperliquid_dart #

A Dart SDK for the Hyperliquid decentralized exchange (DEX). Trade perpetual futures with REST API, WebSocket streams, and EIP-712 signing.

Features #

• REST API — 52 methods across InfoClient (31) and ExchangeClient (21) for market data, account info, trading, and vault operations
• Spot & Perpetual Trading — Full support for both spot markets and perpetual futures
• Vault Operations — Query vaults, check positions, deposit/withdraw funds
• WebSocket — 15 real-time subscriptions for orderbook, trades, fills, funding, TWAP, and ledger updates
• EIP-712 Signing — Full signing support with wallet-agnostic interface
• Wallet Adapters — Built-in support for raw private keys; bring your own wallet (Privy, Web3Auth, etc.)
• Type-Safe — Comprehensive Dart models for all API responses
• HIP-3 DEX Support — Query and trade on builder-deployed perpetual DEXs
• Minimal Dependencies — Only 4 runtime dependencies, no bloat
• Production-Ready — 21 integration tests passing (95%), verified against live mainnet
• TypeScript SDK Parity — 56% InfoClient, 42% ExchangeClient, 79% WebSocketClient coverage (actively expanding)

Installation #

Add to your pubspec.yaml:

dependencies:
  hyperliquid_dart:
    git:
      url: https://github.com/Riten-Zone/Hyperliquid-Dart-SDK.git
      ref: main

Or use a local path during development:

dependencies:
  hyperliquid_dart:
    path: ../Hyperliquid-Dart-SDK

Then run:

dart pub get  # or flutter pub get

Quick Start #

Read-Only API (No Wallet Needed) #

import 'package:hyperliquid_dart/hyperliquid_dart.dart';

void main() async {
  // Create an InfoClient for read-only queries
  final info = InfoClient();

  // Fetch current prices
  final mids = await info.allMids();
  print('BTC: \$${mids['BTC']}');

  // Fetch candlestick data
  final candles = await info.candleSnapshot(
    coin: 'BTC',
    interval: '1h',
    startTime: DateTime.now().subtract(Duration(days: 1)).millisecondsSinceEpoch,
    endTime: DateTime.now().millisecondsSinceEpoch,
  );
  print('Fetched ${candles.length} candles');

  // Fetch orderbook
  final book = await info.l2Book('BTC');
  print('Best bid: ${book.bids.first.price}');
  print('Best ask: ${book.asks.first.price}');

  info.close();
}

Trading (Requires Wallet) #

import 'package:hyperliquid_dart/hyperliquid_dart.dart';

void main() async {
  // Create a wallet adapter (this example uses raw private key)
  final wallet = PrivateKeyWalletAdapter('0xYOUR_PRIVATE_KEY');

  // Create an ExchangeClient for trading
  final exchange = ExchangeClient(wallet: wallet);

  // Set leverage
  await exchange.updateLeverage(
    asset: 0,  // BTC
    leverage: 10,
    isCross: true,
  );

  // Place a limit order
  final result = await exchange.placeOrder(
    orders: [
      OrderWire.limit(
        asset: 0,  // BTC
        isBuy: true,
        limitPx: '50000',  // $50,000
        sz: '0.001',       // 0.001 BTC
        tif: TimeInForce.gtc,
      ),
    ],
  );
  print('Order placed: ${result.status}');

  exchange.close();
}

Real-Time WebSocket Streams #

import 'package:hyperliquid_dart/hyperliquid_dart.dart';

void main() async {
  final ws = WebSocketClient();
  await ws.connect();

  // Subscribe to live prices
  final midsHandle = ws.subscribeAllMids((mids) {
    print('BTC: \$${mids['BTC']}');
  });

  // Subscribe to orderbook updates
  final bookHandle = ws.subscribeL2Book('BTC', (book) {
    print('Bid: ${book.bids.first.price}, Ask: ${book.asks.first.price}');
  });

  // Keep running for 10 seconds
  await Future.delayed(Duration(seconds: 10));

  // Cleanup
  await midsHandle.cancel();
  await bookHandle.cancel();
  await ws.dispose();
}

Wallet Integration #

The SDK uses a WalletAdapter interface, allowing you to integrate any wallet provider.

Using Raw Private Key (Built-in) #

final wallet = PrivateKeyWalletAdapter('0xYOUR_PRIVATE_KEY');

⚠️ Security: Never hardcode private keys in production. Use environment variables or secure storage.

Custom Wallet Integration (e.g., Privy) #

class PrivyWalletAdapter implements WalletAdapter {
  final PrivyClient _privy;

  PrivyWalletAdapter(this._privy);

  @override
  Future<String> getAddress() async {
    return await _privy.getAddress();
  }

  @override
  Future<String> signTypedData(Map<String, dynamic> typedData) async {
    return await _privy.eth_signTypedData_v4(typedData);
  }
}

// Use it
final wallet = PrivyWalletAdapter(myPrivyClient);
final exchange = ExchangeClient(wallet: wallet);

API Reference #

InfoClient (Read-Only) - 31 Methods Available #

Coverage: 56% (31/55) compared to TypeScript SDK

Perpetual Futures Market Data

Spot Market Data

Account & Order Data

Sub-Accounts & HIP-3 DEXs

Vault Operations 🆕

Full API docs →

ExchangeClient (Trading) - 21 Methods Available #

Coverage: 42% (21/50) compared to TypeScript SDK

Order Management

TWAP Orders

Account Management

Spot Token Operations

Vault Operations 🆕

WebSocketClient (Real-Time) - 15 Subscriptions Available #

Market Data Streams

Account Streams

TWAP Streams

Other

Planned Future Subscriptions

• Spot market real-time data streams
• Vault performance updates

Examples #

See the example/ directory for more examples:

• hyperliquid_dart_example.dart — Comprehensive demo

Testing #

# Unit tests (no wallet needed)
dart test --exclude-tags integration

# Integration tests (requires HYPERLIQUID_PRIVATE_KEY env var)
HYPERLIQUID_PRIVATE_KEY=0x... dart test --tags integration

Architecture #

• Minimal Dependencies: http, web_socket_channel, pointycastle, msgpack_dart
• Wallet-Agnostic: Abstract WalletAdapter interface
• Type-Safe: Comprehensive models for all API responses
• Memory-Efficient: Designed for long-running applications

Roadmap #

Completed

• ✅ REST API — InfoClient (25 methods) + ExchangeClient (13 methods)
• ✅ WebSocket subscriptions (15 real-time streams)
• ✅ EIP-712 signing with wallet-agnostic interface
• ✅ PrivateKeyWalletAdapter for raw private keys
• ✅ Perpetual futures trading (orders, leverage, positions)
• ✅ TWAP orders (place, cancel, monitor via WebSocket)
• ✅ Spot market metadata and price queries
• ✅ HIP-3 DEX support (query DEXs, metadata, trade on builder-deployed perps)
• ✅ Sub-account queries and USDC transfers
• ✅ Order modification (single and batch)
• ✅ Builder fee approval
• ✅ Paginated candle queries for large time ranges
• ✅ Portfolio and funding history endpoints

Future

• ❌ Spot token trading (buy/sell operations)
• ❌ Vault deposits and withdrawals
• ❌ Publish to pub.dev
• ❌ Referral system integration
• ❌ Comprehensive API documentation expansion

Contributing #

Contributions welcome! Please open an issue or PR on GitHub.

License #

MIT License - see LICENSE for details.

Disclaimer #

This SDK is provided as-is. Trading crypto involves risk. The authors are not responsible for any losses incurred.

Links #

• Hyperliquid Documentation
• Hyperliquid DEX
• GitHub Repository

Built with ❤️ for the Hyperliquid community