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

Method	Description
`allMids()`	Get current mid prices for all perpetual assets
`candleSnapshot(coin, interval, startTime, endTime)`	Get OHLCV candles for a coin
`candleSnapshotPaginated(coin, interval, startTime, endTime)`	Auto-paginated candle queries for large time ranges
`l2Book(coin)`	Get orderbook snapshot
`metaAndAssetCtxs(dex?)`	Get perpetual futures metadata and contexts (supports HIP-3 DEXs)
`meta(dex?)`	Get perpetual futures metadata only (supports HIP-3 DEXs)
`universeNames()`	Get asset universe names (convenience method)
`recentTrades(coin)`	Get recent trades for a coin

Spot Market Data

Method	Description
`spotMeta()`	Get all spot tokens metadata (tokens, universes)
`spotMetaAndAssetCtxs()`	Get spot metadata + market data (prices, volumes)
`tokenDetails(tokenId)`	Get detailed token information by token ID
`spotClearinghouseState(address)`	Get user's spot token balances

Account & Order Data

Method	Description
`clearinghouseState(address)`	Get perpetual account state (balance, positions)
`openOrders(address)`	Get user's open orders
`frontendOpenOrders(address)`	Get user's open orders including trigger orders
`historicalOrders(address)`	Get up to 2000 most recent orders
`userFills(address)`	Get user's trade fills history
`userFillsByTime(user, startTime, endTime?)`	Get user's fills filtered by time range
`userFunding(user, startTime, endTime?)`	Get user's funding payments
`fundingHistory(coin, startTime, endTime?)`	Get historical funding rates for a coin
`orderStatus(user, oid)`	Get order status by order ID
`portfolio(user)`	Get portfolio with historical account value and PnL

Sub-Accounts & HIP-3 DEXs

Method	Description
`subAccounts(user)`	Get user's sub-accounts with balances and positions
`perpDexs()`	Get all HIP-3 builder-deployed perpetual DEXs
`maxBuilderFee(user, builder)`	Get max approved builder fee

Vault Operations 🆕

Method	Description
`vaultDetails(vaultAddress, user?)`	Get detailed vault information including performance, followers, and portfolio history
`vaultSummaries()`	Get summaries for all vaults (may return empty - known API issue)
`leadingVaults(user)`	Get all vaults managed by a specific vault leader
`userVaultEquities(user)`	Get user's vault deposits and equity across all vaults

Full API docs →

ExchangeClient (Trading) - 21 Methods Available #

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

Order Management

Method	Description
`placeOrder(orders, grouping, builder, vaultAddress?)`	Place limit/market/trigger orders
`cancelOrders(cancels, vaultAddress?)`	Cancel orders by order ID
`cancelOrdersByCloid(asset, cloids, vaultAddress?)`	Cancel orders by client order ID
`modify(oid, order, vaultAddress?)`	Modify an existing order (price, size)
`batchModify(modifies, vaultAddress?)`	Modify multiple orders in a single atomic request
`scheduleCancel(time)`	Schedule all orders to cancel at a specific time

TWAP Orders

Method	Description
`twapOrder(twap, vaultAddress?)`	Place TWAP (time-weighted average price) order
`twapCancel(cancel, vaultAddress?)`	Cancel an active TWAP order

Account Management

Method	Description
`updateLeverage(asset, leverage, isCross, vaultAddress?)`	Set leverage for a perpetual asset
`updateIsolatedMargin(asset, isBuy, ntli, vaultAddress?)`	Add/remove isolated margin
`usdTransfer(destination, amount)`	Transfer USDC between accounts/sub-accounts
`usdClassTransfer(amount, toPerp)`	Transfer USDC between spot and perp accounts
`withdraw(destination, amount)`	Withdraw USDC to another address
`approveBuilderFee(builder, maxFeeRate)`	Approve a builder fee for HIP-3 DEXs

Spot Token Operations

Method	Description
`spotUser(action)`	Toggle spot dusting settings
`spotSend(destination, token, amount)`	Send spot tokens to another address
`sendAsset(destination, token, amount, dex?, subAccount?)`	Transfer assets between DEXs/addresses/sub-accounts
`subAccountTransfer(amount, subAccount, isDeposit)`	Transfer USDC to/from sub-accounts (perp DEX)
`subAccountSpotTransfer(token, amount, subAccount, isDeposit)`	Transfer spot tokens to/from sub-accounts

Vault Operations 🆕

Method	Description
`vaultTransfer(vaultAddress, isDeposit, usd)`	Deposit/withdraw USDC to/from vaults ($5 minimum, 24h lockup)

WebSocketClient (Real-Time) - 15 Subscriptions Available #

Market Data Streams

Method	Description
`subscribeAllMids(callback)`	Live mid prices for all perpetual assets
`subscribeL2Book(coin, callback)`	Live orderbook updates for a coin
`subscribeCandle(coin, interval, callback)`	Live OHLCV candle updates
`subscribeTrades(coin, callback)`	Live trades stream for a coin
`subscribeBbo(coin, callback)`	Best bid/offer updates

Account Streams

Method	Description
`subscribeUserFills(address, callback)`	Live trade fills for user
`subscribeOrderUpdates(address, callback)`	Order status updates for user
`subscribeUserFundings(address, callback)`	Live funding payments for user
`subscribeUserEvents(address, callback)`	User event stream (clearinghouse state changes, etc.)
`subscribeNotification(address, callback)`	Account notifications
`subscribeWebData3(address, callback)`	Aggregated account data stream

TWAP Streams

Method	Description
`subscribeTwapStates(address, callback)`	Active TWAP orders status
`subscribeUserTwapHistory(address, callback)`	TWAP order history events
`subscribeUserTwapSliceFills(address, callback)`	Individual TWAP slice fill notifications

Other

Method	Description
`subscribeRaw(key, message, callback)`	Generic raw subscription for any type

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 (31 methods) + ExchangeClient (21 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
✅ Spot token trading (buy/sell, send, dust settings, sub-account transfers)
✅ HIP-3 DEX support (query DEXs, metadata, trade on builder-deployed perps)
✅ Sub-account queries and USDC transfers
✅ Vault operations (query vaults, deposit/withdraw, check positions)
✅ Order modification (single and batch)
✅ Builder fee approval
✅ Paginated candle queries for large time ranges
✅ Portfolio and funding history endpoints
✅ Published to pub.dev 🎉
✅ Comprehensive dartdoc documentation (67 methods with examples and API docs)

Future

❌ Referral system integration
❌ Comprehensive API documentation expansion
❌ Additional WebSocket streams (spot markets, vault updates)

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 #

Built with ❤️ for the Hyperliquid community

hyperliquid_dart 0.16.2
hyperliquid_dart: ^0.16.2 copied to clipboard

Metadata

hyperliquid_dart #

Features #

Installation #

Quick Start #

Read-Only API (No Wallet Needed) #

Trading (Requires Wallet) #

Real-Time WebSocket Streams #

Wallet Integration #

Using Raw Private Key (Built-in) #

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

API Reference #

InfoClient (Read-Only) - 31 Methods Available #

ExchangeClient (Trading) - 21 Methods Available #

WebSocketClient (Real-Time) - 15 Subscriptions Available #

Examples #

Testing #

Architecture #

Roadmap #

Contributing #

License #

Disclaimer #

Links #

← Metadata

Publisher

Weekly Downloads

Metadata

Topics

Documentation

License

Dependencies

More

hyperliquid_dart 0.16.2 hyperliquid_dart: ^0.16.2 copied to clipboard

Metadata

hyperliquid_dart #

Features #

Installation #

Quick Start #

Read-Only API (No Wallet Needed) #

Trading (Requires Wallet) #

Real-Time WebSocket Streams #

Wallet Integration #

Using Raw Private Key (Built-in) #

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

API Reference #

InfoClient (Read-Only) - 31 Methods Available #

ExchangeClient (Trading) - 21 Methods Available #

WebSocketClient (Real-Time) - 15 Subscriptions Available #

Examples #

Testing #

Architecture #

Roadmap #

Contributing #

License #

Disclaimer #

Links #

← Metadata

Publisher

Weekly Downloads

Metadata

Topics

Documentation

License

Dependencies

More

hyperliquid_dart 0.16.2
hyperliquid_dart: ^0.16.2 copied to clipboard