userFees

Get fee rates, volume information, and referral discounts for a user on Hyperliquid.

Why Hyperliquid? Build on the dominant perpetuals DEX with 70% market share, $2.7T+ lifetime volume, and $2B TVL with 200K orders/second throughput, zero gas fees, sub-second finality, and fully onchain Central Limit Order Book (CLOB).

When to Use This Endpoint

The userFees endpoint is essential for traders, trading platforms, and analytics tools who need to:

• Calculate Trading Costs — Estimate fees before placing orders
• Volume Tracking — Monitor daily trading volume
• Fee Optimization — Compare user's fees against standard schedule
• Referral Programs — Track referral discounts and benefits

Request

Endpoint

POST https://api-hyperliquid-mainnet-info.n.dwellir.com/info

Headers

Header	Value	Required
Content-Type	application/json	Yes
X-Api-Key	Your API key	Yes

Parameters

Parameter	Type	Required	Description
type	string	Yes	Must be "userFees"
user	string	Yes	User's Ethereum wallet address

Example Request

{
  "type": "userFees",
  "user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f"
}

Response

Success Response

{
  "dailyUserVlm": [
    {
      "date": "2026-02-07",
      "userCross": "0.0",
      "userAdd": "0.0",
      "exchange": "6761946801.4399995804"
    },
    {
      "date": "2026-02-08",
      "userCross": "0.0",
      "userAdd": "0.0",
      "exchange": "3963888811.4499998093"
    },
    {
      "date": "2026-02-09",
      "userCross": "0.0",
      "userAdd": "0.0",
      "exchange": "2538522069.9000000954"
    }
  ],
  "feeSchedule": {
    "cross": "0.00045",
    "add": "0.00015",
    "spotCross": "0.0007",
    "spotAdd": "0.0004",
    "tiers": {
      "vip": [
        {
          "ntlCutoff": "5000000.0",
          "cross": "0.0004",
          "add": "0.00012",
          "spotCross": "0.0006",
          "spotAdd": "0.0003"
        }
      ],
      "mm": [
        {
          "makerFractionCutoff": "0.005",
          "add": "-0.00001"
        }
      ]
    },
    "referralDiscount": "0.04",
    "stakingDiscountTiers": [
      {
        "bpsOfMaxSupply": "0.0",
        "discount": "0.0"
      },
      {
        "bpsOfMaxSupply": "0.0001",
        "discount": "0.05"
      }
    ]
  },
  "userCrossRate": "0.00045",
  "userAddRate": "0.00015",
  "userSpotCrossRate": "0.0007",
  "userSpotAddRate": "0.0004",
  "activeReferralDiscount": "0.04",
  "trial": null,
  "feeTrialEscrow": "0.0",
  "nextTrialAvailableTimestamp": null,
  "stakingLink": null,
  "activeStakingDiscount": {
    "bpsOfMaxSupply": "0.0",
    "discount": "0.0"
  }
}

Response Fields

Field	Type	Description
dailyUserVlm	array	Array of daily trading volume objects (last 15 days)
feeSchedule	object	Complete fee schedule with tiers and discounts
userCrossRate	string	User's current cross margin fee rate
userAddRate	string	User's current add liquidity fee rate
userSpotCrossRate	string	User's current spot cross margin fee rate
userSpotAddRate	string	User's current spot add liquidity fee rate
activeReferralDiscount	string	Active referral discount (decimal, e.g., "0.04" = 4%)
trial	null | object	Fee trial information if active
feeTrialEscrow	string	Amount in escrow for fee trial
nextTrialAvailableTimestamp	null | integer	Timestamp when next trial becomes available
stakingLink	null | string	Staking link if applicable
activeStakingDiscount	object	Current staking discount tier

Daily Volume Object

Field	Type	Description
date	string	Date in YYYY-MM-DD format
userCross	string	User's cross margin trading volume for the day
userAdd	string	User's add liquidity volume for the day
exchange	string	Total exchange volume for the day

Fee Schedule Object

Field	Type	Description
cross	string	Base cross margin fee rate
add	string	Base add liquidity fee rate
spotCross	string	Base spot cross margin fee rate
spotAdd	string	Base spot add liquidity fee rate
tiers	object	VIP and market maker tier structures
referralDiscount	string	Standard referral discount percentage
stakingDiscountTiers	array	Array of staking discount tier objects

VIP Tier Object

Field	Type	Description
ntlCutoff	string	Notional volume cutoff for this tier
cross	string	Cross margin fee rate at this tier
add	string	Add liquidity fee rate at this tier
spotCross	string	Spot cross margin fee rate at this tier
spotAdd	string	Spot add liquidity fee rate at this tier

Market Maker Tier Object

Field	Type	Description
makerFractionCutoff	string	Maker fraction cutoff for this tier
add	string	Add liquidity rebate (negative = rebate)

Staking Discount Tier Object

Field	Type	Description
bpsOfMaxSupply	string	Basis points of max supply staked
discount	string	Fee discount percentage at this tier

Note: Fee rates are expressed as decimals (e.g., "0.00045" = 0.045% or 4.5 basis points)

Code Examples

cURL

curl -X POST 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "userFees",
    "user": "0x63E8c7C149556D5f34F833419A287bb9Ef81487f"
  }'

JavaScript

const ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info';
const API_KEY = 'your-api-key-here';

async function getUserFees(userAddress) {
  const response = await fetch(ENDPOINT, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': API_KEY
    },
    body: JSON.stringify({
      type: 'userFees',
      user: userAddress
    })
  });

  if (!response.ok) {
    throw new Error(`HTTP ${response.status}: ${response.statusText}`);
  }

  return await response.json();
}

// Usage
const fees = await getUserFees('0x63E8c7C149556D5f34F833419A287bb9Ef81487f');

// Convert to basis points for readability
const crossRateBps = parseFloat(fees.userCrossRate) * 10000;
const addRateBps = parseFloat(fees.userAddRate) * 10000;

console.log(`Cross Margin Rate: ${crossRateBps} bps`);
console.log(`Add Liquidity Rate: ${addRateBps} bps`);
console.log(`Spot Cross Rate: ${parseFloat(fees.userSpotCrossRate) * 10000} bps`);
console.log(`Spot Add Rate: ${parseFloat(fees.userSpotAddRate) * 10000} bps`);

if (parseFloat(fees.activeReferralDiscount) > 0) {
  console.log(`Active Referral Discount: ${parseFloat(fees.activeReferralDiscount) * 100}%`);
  console.log(`Referral Discount: ${(parseFloat(fees.referralDiscount) * 100).toFixed(1)}%`);
}

Python

import requests
from typing import Dict
from decimal import Decimal

ENDPOINT = 'https://api-hyperliquid-mainnet-info.n.dwellir.com/info'
API_KEY = 'your-api-key-here'

def get_user_fees(user_address: str) -> Dict:
    """Get user's fee rates and volume information"""
    response = requests.post(
        ENDPOINT,
        json={
            'type': 'userFees',
            'user': user_address
        },
        headers={
            'Content-Type': 'application/json',
            'X-Api-Key': API_KEY
        },
        timeout=10
    )
    response.raise_for_status()
    return response.json()

# Usage
fees = get_user_fees('0x63E8c7C149556D5f34F833419A287bb9Ef81487f')

# Convert to basis points
cross_rate = Decimal(fees['userCrossRate'])
add_rate = Decimal(fees['userAddRate'])
spot_cross_rate = Decimal(fees['userSpotCrossRate'])
spot_add_rate = Decimal(fees['userSpotAddRate'])

print(f"Cross Margin Rate: {cross_rate * 10000} bps")
print(f"Add Liquidity Rate: {add_rate * 10000} bps")
print(f"Spot Cross Rate: {spot_cross_rate * 10000} bps")
print(f"Spot Add Rate: {spot_add_rate * 10000} bps")

# Check discounts
if Decimal(fees['activeReferralDiscount']) > 0:
    print(f"Active Referral Discount: {Decimal(fees['activeReferralDiscount']) * 100}%")

if Decimal(fees['activeStakingDiscount']['discount']) > 0:
    print(f"Active Staking Discount: {Decimal(fees['activeStakingDiscount']['discount']) * 100}%")

# Volume history
print(f"\nDaily Volume Records: {len(fees['dailyUserVlm'])}")

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "strconv"
)

const (
    Endpoint = "https://api-hyperliquid-mainnet-info.n.dwellir.com/info"
    APIKey   = "your-api-key-here"
)

type UserFeesRequest struct {
    Type string `json:"type"`
    User string `json:"user"`
}

type UserRates struct {
    UserCrossRate string `json:"userCrossRate"`
    UserAddRate   string `json:"userAddRate"`
}

type UserFees struct {
    UserRates        UserRates              `json:"userRates"`
    DailyUserVlm     []interface{}          `json:"dailyUserVlm"`
    FeeSchedule      map[string]interface{} `json:"feeSchedule"`
    ReferralDiscount string                 `json:"referralDiscount"`
}

func getUserFees(userAddress string) (*UserFees, error) {
    reqBody, _ := json.Marshal(UserFeesRequest{
        Type: "userFees",
        User: userAddress,
    })

    req, _ := http.NewRequest("POST", Endpoint, bytes.NewBuffer(reqBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-Api-Key", APIKey)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)

    var result UserFees
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

func rateToBps(rate string) float64 {
    r, _ := strconv.ParseFloat(rate, 64)
    return r * 10000
}

func main() {
    fees, err := getUserFees("0x63E8c7C149556D5f34F833419A287bb9Ef81487f")
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    crossBps := rateToBps(fees.UserRates.UserCrossRate)
    addBps := rateToBps(fees.UserRates.UserAddRate)

    fmt.Printf("Cross Margin Rate: %.1f bps (%s)\n", crossBps, fees.UserRates.UserCrossRate)
    fmt.Printf("Add Liquidity Rate: %.1f bps (%s)\n", addBps, fees.UserRates.UserAddRate)

    discount, _ := strconv.ParseFloat(fees.ReferralDiscount, 64)
    if discount > 0 {
        fmt.Printf("Referral Discount: %.1f%%\n", discount*100)
    }

    fmt.Printf("\nDaily Volume Records: %d\n", len(fees.DailyUserVlm))
}

Common Use Cases

1. Calculate Trading Costs

Estimate fees for a trade:

async function calculateTradingFee(userAddress, orderValue, isMaker = false) {
  const fees = await getUserFees(userAddress);

  // Use cross rate for taker, add rate for maker
  const feeRate = isMaker
    ? parseFloat(fees.userRates.userAddRate)
    : parseFloat(fees.userRates.userCrossRate);

  // Apply referral discount if available
  const discount = parseFloat(fees.referralDiscount);
  const effectiveRate = feeRate * (1 - discount);

  const feeAmount = orderValue * effectiveRate;

  return {
    orderValue: orderValue,
    feeRate: feeRate,
    discount: discount,
    effectiveRate: effectiveRate,
    feeAmount: feeAmount,
    feeBps: effectiveRate * 10000
  };
}

// Usage
const tradeFee = await calculateTradingFee(
  '0x63E8c7C149556D5f34F833419A287bb9Ef81487f',
  10000, // $10,000 order
  true   // maker order
);

console.log(`Order Value: $${tradeFee.orderValue}`);
console.log(`Fee Rate: ${tradeFee.feeBps.toFixed(2)} bps`);
console.log(`Estimated Fee: $${tradeFee.feeAmount.toFixed(2)}`);

2. Compare Against Standard Fees

Compare user's fees to standard rates:

async function compareFeeRates(userAddress, standardRate = 0.0005) {
  const fees = await getUserFees(userAddress);
  const userRate = parseFloat(fees.userRates.userCrossRate);

  const savingsBps = (standardRate - userRate) * 10000;
  const savingsPercent = ((standardRate - userRate) / standardRate) * 100;

  return {
    userRate: userRate,
    standardRate: standardRate,
    savingsBps: savingsBps,
    savingsPercent: savingsPercent,
    hasBetterRate: userRate < standardRate
  };
}

// Usage
const comparison = await compareFeeRates(
  '0x63E8c7C149556D5f34F833419A287bb9Ef81487f',
  0.0005 // 5 bps standard
);

if (comparison.hasBetterRate) {
  console.log(`You save ${comparison.savingsBps.toFixed(2)} bps (${comparison.savingsPercent.toFixed(1)}%)`);
}

3. Estimate Monthly Fee Savings

Calculate potential savings with referral discount:

async function estimateMonthlySavings(userAddress, monthlyVolume) {
  const fees = await getUserFees(userAddress);

  const baseRate = parseFloat(fees.userRates.userCrossRate);
  const discount = parseFloat(fees.referralDiscount);

  const baseFees = monthlyVolume * baseRate;
  const discountedFees = baseFees * (1 - discount);
  const savings = baseFees - discountedFees;

  return {
    monthlyVolume: monthlyVolume,
    baseRate: baseRate,
    discount: discount,
    baseFees: baseFees,
    discountedFees: discountedFees,
    savings: savings,
    savingsPercent: discount * 100
  };
}

// Usage
const savings = await estimateMonthlySavings(
  '0x63E8c7C149556D5f34F833419A287bb9Ef81487f',
  1000000 // $1M monthly volume
);

console.log(`Monthly Volume: $${savings.monthlyVolume.toLocaleString()}`);
console.log(`Base Fees: $${savings.baseFees.toFixed(2)}`);
console.log(`With Discount: $${savings.discountedFees.toFixed(2)}`);
console.log(`Monthly Savings: $${savings.savings.toFixed(2)}`);

4. Fee Tier Analyzer

Analyze user's fee tier and potential improvements:

async function analyzeFeePosition(userAddress) {
  const fees = await getUserFees(userAddress);

  const crossRate = parseFloat(fees.userRates.userCrossRate);
  const addRate = parseFloat(fees.userRates.userAddRate);
  const discount = parseFloat(fees.referralDiscount);

  // Example tier thresholds (adjust based on actual schedule)
  const tiers = [
    { name: 'Standard', rate: 0.0005, minVolume: 0 },
    { name: 'Tier 1', rate: 0.0004, minVolume: 100000 },
    { name: 'Tier 2', rate: 0.0003, minVolume: 500000 },
    { name: 'Tier 3', rate: 0.0002, minVolume: 2000000 },
  ];

  const currentTier = tiers.findLast(t => t.rate >= crossRate) || tiers[0];
  const nextTier = tiers[tiers.indexOf(currentTier) + 1];

  console.log('=== Fee Analysis ===\n');
  console.log(`Current Cross Rate: ${(crossRate * 10000).toFixed(2)} bps`);
  console.log(`Current Add Rate: ${(addRate * 10000).toFixed(2)} bps`);
  console.log(`Estimated Tier: ${currentTier.name}`);

  if (discount > 0) {
    console.log(`Referral Discount: ${(discount * 100).toFixed(1)}%`);
  }

  if (nextTier) {
    const improvement = ((crossRate - nextTier.rate) / crossRate) * 100;
    console.log(`\nNext tier saves ${improvement.toFixed(1)}% on fees`);
    console.log(`Requires ~$${nextTier.minVolume.toLocaleString()} monthly volume`);
  }
}

5. Fee Comparison Tool

Compare fees across different order types:

async function compareFeeTypes(userAddress, orderValue) {
  const fees = await getUserFees(userAddress);

  const makerRate = parseFloat(fees.userRates.userAddRate);
  const takerRate = parseFloat(fees.userRates.userCrossRate);
  const discount = parseFloat(fees.referralDiscount);

  const makerFee = orderValue * makerRate * (1 - discount);
  const takerFee = orderValue * takerRate * (1 - discount);

  console.log(`Order Value: $${orderValue.toLocaleString()}\n`);

  console.log('Maker Order (limit):');
  console.log(`  Rate: ${(makerRate * 10000).toFixed(2)} bps`);
  console.log(`  Fee: $${makerFee.toFixed(2)}`);

  console.log('\nTaker Order (market):');
  console.log(`  Rate: ${(takerRate * 10000).toFixed(2)} bps`);
  console.log(`  Fee: $${takerFee.toFixed(2)}`);

  console.log(`\nSavings with maker: $${(takerFee - makerFee).toFixed(2)}`);
}

Error Handling

Common Errors

Error	Cause	Solution
401 Unauthorized	Invalid API key	Verify your API key is correct
400 Bad Request	Missing or invalid user address	Ensure valid Ethereum address format
429 Too Many Requests	Rate limit exceeded	Implement request throttling
500 Internal Server Error	Server issue	Retry with exponential backoff

Error Response Example

{
  "error": "Missing required parameter: user",
  "code": "MISSING_PARAMETER"
}

Robust Error Handling

async function safeGetUserFees(userAddress, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await getUserFees(userAddress);
    } catch (error) {
      if (error.response?.status === 429) {
        // Rate limit - exponential backoff
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else if (error.response?.status === 400) {
        throw new Error('Invalid user address');
      } else if (i === maxRetries - 1) {
        throw error;
      }
    }
  }
}

Best Practices

1. Cache fee data — Fee rates change infrequently, cache for several minutes
2. Always use effective rate — Apply referral discount when calculating costs
3. Display fees clearly — Show both basis points and dollar amounts
4. Validate addresses — Ensure user addresses are valid Ethereum addresses
5. Consider order type — Use correct rate for maker vs taker orders

Related Endpoints

• clearinghouseState — Get account state and trading volume
• openOrders — See orders that will incur fees
• meta — Get trading pair metadata
• spotClearinghouseState — Get spot trading balances

---

Access real-time Hyperliquid fee information with Dwellir's HyperCore Info Endpoint. Get your API key →