@mangrovedao/trading-hooks

A comprehensive React hooks library for building decentralized trading applications on the Mangrove Protocol. This package provides a complete set of hooks, providers, and utilities for order management, balance tracking, market data, and trading workflows.

🚀 Features

📈 Order Management

• Limit Orders: Create, cancel, and manage limit orders on the order book
• Market Orders: Execute immediate market trades with Mangrove routing
• Order History: Track active and historical orders with pagination
• Real-time Updates: Automatic order status synchronization and live data

💰 Balance & Approvals

• Token Balances: Monitor user token holdings across multiple tokens
• Approval Management: Handle token spending approvals and allowances
• Infinite Approvals: Set unlimited spending allowances for seamless trading
• Gas Estimation: Calculate and optimize transaction costs

📊 Market Data & Analytics

• Live Pricing: Real-time token price feeds and OHLCV data
• Market Statistics: 24-hour volume, price changes, and market metrics
• Order Book: Retrieve live market depth and liquidity data
• Orderbook Trades: Track recent trades and market activity
• Pool Information: Access liquidity pool statistics and performance

🔧 Trading Utilities

• Dollar Conversion: Convert between tokens and USD with live rates
• Trade Information: Calculate trade details, fees, and slippage
• Network Management: Handle multi-chain operations seamlessly
• Local Storage: Persist user preferences and settings

⚛️ React Providers

• Market Provider: Global market state management and context
• Mangrove Provider: Core protocol connection and configuration

📦 Installation

npm install @mangrovedao/trading-hooks

Or with pnpm:

pnpm add @mangrovedao/trading-hooks

🏁 Quick Start

Setup Providers

import { MarketProvider, MangroveProvider } from "@mangrovedao/trading-hooks";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { WagmiProvider } from "wagmi";

const queryClient = new QueryClient();

function App() {
  return (
    <WagmiProvider config={wagmiConfig}>
      <QueryClientProvider client={queryClient}>
        <MangroveProvider>
          <MarketProvider>
            <TradingApp />
          </MarketProvider>
        </MangroveProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Basic Trading Component

import {
  useMarket,
  useOrders,
  usePostLimitOrder,
  useMarketStats,
} from "@mangrovedao/trading-hooks";

function TradingComponent() {
  const { currentMarket, setMarket } = useMarket();
  const { data: orders } = useOrders({ type: "active" });
  const { postLimitOrder, isPending } = usePostLimitOrder();
  const { data: stats } = useMarketStats({
    markets: currentMarket ? [currentMarket] : [],
  });

  const handlePlaceOrder = async () => {
    if (!currentMarket) return;

    await postLimitOrder({
      side: "buy",
      amount: "100",
      price: "1.5",
      market: currentMarket,
    });
  };

  return (
    <div>
      <h2>
        {currentMarket?.base.symbol}/{currentMarket?.quote.symbol}
      </h2>
      <div>Price: ${stats?.price?.toFixed(4)}</div>
      <div>24h Change: {stats?.dailyPercentChange?.toFixed(2)}%</div>
      <button onClick={handlePlaceOrder} disabled={isPending}>
        Place Limit Order
      </button>
      <div>Active Orders: {orders?.pages[0]?.data.length || 0}</div>
    </div>
  );
}

📚 API Reference

Providers

MarketProvider

Provides global market context and state management.

import { MarketProvider, useMarket } from "@mangrovedao/trading-hooks";

function App() {
  return (
    <MarketProvider>
      <TradingInterface />
    </MarketProvider>
  );
}

function TradingInterface() {
  const { currentMarket, setMarket, markets } = useMarket();
  // Access current market and switch between markets
}

MangroveProvider

Core Mangrove Protocol provider for blockchain connection.

import { MangroveProvider } from "@mangrovedao/trading-hooks";

function App() {
  return (
    <MangroveProvider>
      <YourApp />
    </MangroveProvider>
  );
}

Core Hooks

Order Management

useOrders(options)

Fetch and manage user orders with infinite pagination.

const { data, fetchNextPage, hasNextPage, isLoading } = useOrders({
  type: "active", // 'active' | 'history'
  pageSize: 25,
  allMarkets: false,
});

usePostLimitOrder()

Create limit orders on the order book.

const { postLimitOrder, isPending, error } = usePostLimitOrder();

await postLimitOrder({
  side: "buy",
  amount: "100",
  price: "1.25",
  market: currentMarket,
  expiryDate: new Date(Date.now() + 86400000), // 24 hours
});

usePostMarketOrder()

Execute immediate market orders.

const { postMarketOrder, isPending } = usePostMarketOrder();

await postMarketOrder({
  side: "sell",
  amount: "50",
  market: currentMarket,
});

useCancelOrder()

Cancel existing limit orders.

const { cancelOrder, isPending } = useCancelOrder();

await cancelOrder({
  offerId: "123",
  market: currentMarket,
});

Market Data & Analytics

useMarket()

Access current market information and switch between trading pairs.

const { currentMarket, setMarket, markets } = useMarket();

// Switch to a different market
setMarket(newMarket);

useOpenMarkets()

Get all available trading markets and tokens.

const { openMarkets, tokens, isLoading } = useOpenMarkets();

useMarketStats(options)

Get comprehensive market statistics and OHLCV data.

const { data: stats, isLoading } = useMarketStats({
  markets: [currentMarket],
});

// Access: price, dailyPercentChange, volume, open, high, low, close

useMangroveBook(options)

Retrieve live order book data for a market.

const { book, isLoading, refetch } = useMangroveBook({
  market: currentMarket,
  depth: 10,
});

useOrderbookTrades(options)

Track recent trades and market activity.

const { data: trades, isLoading } = useOrderbookTrades({
  market: currentMarket,
  limit: 50,
});

useTokenPrices(options)

Get real-time token prices.

const { data: prices, isLoading } = useTokenPrices({
  tokens: [wethToken, usdcToken],
});

usePoolStats(options)

Access liquidity pool statistics.

const { data: poolStats, isLoading } = usePoolStats({
  pools: [currentPool],
});

Balances & Approvals

useBalances(options)

Monitor user token balances.

const { balances, isLoading, refetch } = useBalances({
  tokens: [wethToken, usdcToken],
});

useApprovals(options)

Check token spending approvals.

const { approvals, needsApproval, isLoading } = useApprovals({
  tokens: [wethToken],
  spender: mangroveAddress,
});

useInfiniteApproveToken()

Set unlimited token spending allowance.

const { approveToken, isPending } = useInfiniteApproveToken();

await approveToken({
  token: wethToken,
  spender: mangroveAddress,
});

Trading Utilities

useDollarConversion()

Convert token amounts to USD values.

const { convertToUsd, convertFromUsd } = useDollarConversion();

const usdValue = convertToUsd("100", wethToken);
const tokenAmount = convertFromUsd("1000", usdcToken);

useTradeInfos(options)

Calculate trade details including fees and slippage.

const { tradeInfo, isLoading } = useTradeInfos({
  side: "buy",
  amount: "100",
  market: currentMarket,
});

useTxState()

Manage transaction states and confirmations.

const { txState, updateTxState, clearTxState } = useTxState();

Configuration & Network

useDefaultChain()

Get the current default blockchain network.

const { defaultChain } = useDefaultChain();

useAddresses()

Access important contract addresses.

const { mangroveAddress, routerAddress } = useAddresses();

useNetworkClient()

Get network client for blockchain operations.

const { client } = useNetworkClient();

🛠 Advanced Examples

Complete Trading Dashboard

import {
  useMarket,
  useOrders,
  useBalances,
  useMarketStats,
  useOrderbookTrades,
  usePostLimitOrder,
  useCancelOrder,
} from "@mangrovedao/trading-hooks";

function TradingDashboard() {
  const { currentMarket, markets, setMarket } = useMarket();
  const { data: orders } = useOrders({ type: "active" });
  const { balances } = useBalances();
  const { data: stats } = useMarketStats({
    markets: currentMarket ? [currentMarket] : [],
  });
  const { data: trades } = useOrderbookTrades({
    market: currentMarket,
  });
  const { postLimitOrder } = usePostLimitOrder();
  const { cancelOrder } = useCancelOrder();

  return (
    <div className="trading-dashboard">
      <MarketSelector
        markets={markets}
        current={currentMarket}
        onSelect={setMarket}
      />
      <MarketStats stats={stats} />
      <OrderBook market={currentMarket} />
      <RecentTrades trades={trades} />
      <TradingForm market={currentMarket} onSubmit={postLimitOrder} />
      <OrdersTable orders={orders} onCancel={cancelOrder} />
      <BalanceOverview balances={balances} />
    </div>
  );
}

Multi-Market Analytics

function MarketAnalytics() {
  const { markets } = useMarket();
  const { data: allStats } = useMarketStats({
    markets: markets || [],
  });

  return (
    <div>
      {Array.isArray(allStats) ? (
        allStats.map((stats, index) => <MarketCard key={index} stats={stats} />)
      ) : (
        <MarketCard stats={allStats} />
      )}
    </div>
  );
}

Real-time Order Management

function OrderManager() {
  const { data: activeOrders } = useOrders({
    type: "active",
    allMarkets: true,
    pageSize: 50,
  });

  const { data: orderHistory } = useOrders({
    type: "history",
    pageSize: 50,
  });

  return (
    <div>
      <h2>Active Orders ({activeOrders?.pages[0]?.data.length || 0})</h2>
      {activeOrders?.pages.map((page) =>
        page.data.map((order) => (
          <OrderCard key={order.offerId} order={order} />
        ))
      )}

      <h2>Order History</h2>
      {orderHistory?.pages.map((page) =>
        page.data.map((order) => (
          <HistoryCard key={order.offerId} order={order} />
        ))
      )}
    </div>
  );
}

📋 Requirements

Peer Dependencies

{
  "react": "^18.0.0",
  "react-dom": "^18.0.0",
  "next": "^14.0.4",
  "@tanstack/react-form": "^1.11.1",
  "@tanstack/react-query": "^5.76.1",
  "@mangrovedao/mgv": "^0.9.23",
  "@rainbow-me/rainbowkit": "^2.2.5",
  "viem": "2.23.9",
  "wagmi": "2.14.15"
}

Dependencies

The package includes these core dependencies:

• lucide-react - Icon library
• sonner - Toast notifications
• usehooks-ts - Additional React hooks
• zod - Runtime type validation
• zustand - State management

🏗 Architecture

Package Structure

src/
├── hooks/           # All React hooks
│   ├── queries/     # Data fetching hooks
│   ├── order/       # Order management hooks
│   └── ghostbook/   # Ghostbook-specific hooks
├── providers/       # React context providers
├── config/          # Configuration utilities
├── constants/       # Trading constants
├── enums/          # Type enumerations
├── types/          # TypeScript type definitions
├── utils/          # Helper functions
├── stores/         # Zustand state stores
├── abi/            # Smart contract ABIs
└── schema/         # Zod validation schemas

Hook Categories

• Order Hooks: Manage limit/market orders, cancellations
• Market Hooks: Access market data, statistics, order books
• Balance Hooks: Handle token balances and approvals
• Query Hooks: Fetch external data (prices, pool stats)
• Utility Hooks: Local storage, transaction states, conversions
• Network Hooks: Blockchain client and network management

🔧 Development

Building the Package

pnpm build

Development Mode

pnpm dev

Generate Barrel Exports

pnpm run generate:barrels

🔗 Exports Overview

Main Exports

// All hooks
export * from "@mangrovedao/trading-hooks/hooks";

// Providers
export * from "@mangrovedao/trading-hooks/providers";

// Configuration
export * from "@mangrovedao/trading-hooks/config";

// Constants and enums
export * from "@mangrovedao/trading-hooks/constants";
export * from "@mangrovedao/trading-hooks/enums";

Subpath Exports

// Specific hook categories
import { useOrders } from "@mangrovedao/trading-hooks/hooks/useOrders";
import { MarketProvider } from "@mangrovedao/trading-hooks/providers/market";
import { TRADING_CONFIG } from "@mangrovedao/trading-hooks/config";

🌐 Links

• NPM Package
• Mangrove Protocol
• Documentation
• GitHub Repository

Built with ❤️ for the Mangrove Protocol ecosystem