Skip to main content

maxBuilderFee

Get maximum builder fee information on Hyperliquid, including fee limits and builder incentive structures.

When to Use This Endpoint#

The maxBuilderFee endpoint is essential for:

  • Builder Operations — Understand maximum allowable builder fees
  • Fee Calculations — Calculate builder incentives and costs
  • MEV Strategies — Plan maximum extractable value strategies
  • Cost Estimation — Estimate total transaction costs including builder fees

Request#

Endpoint#

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

Headers#

HeaderValueRequired
Content-Typeapplication/jsonYes
X-Api-KeyYour API keyYes

Parameters#

ParameterTypeRequiredDescription
typestringYesMust be "maxBuilderFee"

Example Request#

{
  "type": "maxBuilderFee"
}

Response#

Success Response#

Returns maximum builder fee information.

{
  "maxFee": "0.001"
}

Response Fields#

FieldTypeDescription
maxFeestringMaximum builder fee as a decimal value

Code Examples#

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":"maxBuilderFee"}'

Common Use Cases#

1. Check Maximum Builder Fee#

Display current maximum builder fee:

async function checkMaxBuilderFee() {
  const feeData = await getMaxBuilderFee();

  console.log('=== Maximum Builder Fee ===\n');
  console.log(`Max fee: ${feeData.maxFee}`);

  const feePercent = parseFloat(feeData.maxFee) * 100;
  console.log(`As percentage: ${feePercent}%`);
}

// Usage
await checkMaxBuilderFee();

2. Calculate Builder Fee for Transaction#

Estimate builder fee for a transaction:

async function calculateBuilderFee(transactionValue) {
  const feeData = await getMaxBuilderFee();
  const maxFeeRate = parseFloat(feeData.maxFee);

  const estimatedFee = transactionValue * maxFeeRate;

  return {
    transactionValue: transactionValue,
    maxFeeRate: maxFeeRate,
    estimatedFee: estimatedFee,
    feePercent: maxFeeRate * 100
  };
}

// Usage
const fee = await calculateBuilderFee(10000); // $10,000 transaction
console.log(`Estimated builder fee: $${fee.estimatedFee.toFixed(2)}`);
console.log(`Fee rate: ${fee.feePercent}%`);

3. Compare to Transaction Costs#

Compare builder fee to total costs:

async function analyzeTotalCosts(transactionValue, tradingFee = 0.0002) {
  const feeData = await getMaxBuilderFee();
  const builderFeeRate = parseFloat(feeData.maxFee);

  const builderFee = transactionValue * builderFeeRate;
  const tradingFeeCost = transactionValue * tradingFee;
  const totalCost = builderFee + tradingFeeCost;

  return {
    transactionValue: transactionValue,
    builderFee: builderFee,
    tradingFee: tradingFeeCost,
    totalCost: totalCost,
    builderFeePercent: (builderFee / totalCost) * 100
  };
}

// Usage
const costs = await analyzeTotalCosts(10000);
console.log(`Builder fee: $${costs.builderFee.toFixed(2)}`);
console.log(`Trading fee: $${costs.tradingFee.toFixed(2)}`);
console.log(`Total cost: $${costs.totalCost.toFixed(2)}`);

4. Builder Fee Monitor#

Monitor changes in maximum builder fee:

class BuilderFeeMonitor {
  constructor(checkIntervalMs = 300000) {
    this.checkIntervalMs = checkIntervalMs; // 5 minutes
    this.lastFee = null;
  }

  async start() {
    const check = async () => {
      const feeData = await getMaxBuilderFee();
      const currentFee = parseFloat(feeData.maxFee);

      if (this.lastFee !== null && currentFee !== this.lastFee) {
        const change = ((currentFee - this.lastFee) / this.lastFee) * 100;
        console.log(`Builder fee changed: ${change > 0 ? '+' : ''}${change.toFixed(2)}%`);
      }

      this.lastFee = currentFee;
      console.log(`Current max builder fee: ${currentFee}`);
    };

    await check();
    setInterval(check, this.checkIntervalMs);
  }
}

// Usage
const monitor = new BuilderFeeMonitor();
monitor.start();

5. Fee Comparison Tool#

Compare builder fees across scenarios:

async function compareBuilderFees(transactionValues) {
  const feeData = await getMaxBuilderFee();
  const feeRate = parseFloat(feeData.maxFee);

  const comparisons = transactionValues.map(value => ({
    value: value,
    builderFee: value * feeRate,
    feePercent: feeRate * 100
  }));

  console.log('=== Builder Fee Comparison ===\n');
  comparisons.forEach(comp => {
    console.log(`Transaction: $${comp.value.toLocaleString()}`);
    console.log(`Builder fee: $${comp.builderFee.toFixed(2)}`);
    console.log('---');
  });

  return comparisons;
}

// Usage
await compareBuilderFees([1000, 5000, 10000, 50000]);

Error Handling#

Common Errors#

ErrorCauseSolution
401 UnauthorizedInvalid API keyVerify your API key is correct
429 Too Many RequestsRate limit exceededImplement request throttling
500 Internal Server ErrorServer issueRetry with exponential backoff

Error Response Example#

{
  "error": "Invalid request",
  "code": "INVALID_REQUEST"
}

Robust Error Handling#

async function safeGetMaxBuilderFee(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await getMaxBuilderFee();
    } catch (error) {
      if (error.response?.status === 429) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else if (i === maxRetries - 1) {
        throw error;
      }
    }
  }
}

Best Practices#

  1. Cache appropriately — Builder fee changes infrequently, cache for 5-10 minutes
  2. Include in cost calculations — Always factor builder fees into total costs
  3. Monitor changes — Track fee changes for cost projections
  4. Display clearly — Show builder fees separately in UI for transparency
  5. Use precise decimals — Maintain precision for accurate fee calculations

Performance Tips#

Cached Fee Retrieval#

class CachedBuilderFeeService {
  constructor(cacheDurationMs = 300000) {
    this.cache = null;
    this.cacheTime = 0;
    this.cacheDurationMs = cacheDurationMs; // 5 minutes
  }

  async getMaxFee() {
    const now = Date.now();

    if (this.cache && (now - this.cacheTime) < this.cacheDurationMs) {
      return this.cache;
    }

    const feeData = await getMaxBuilderFee();
    this.cache = feeData;
    this.cacheTime = now;

    return feeData;
  }

  invalidate() {
    this.cache = null;
    this.cacheTime = 0;
  }
}

// Usage
const feeService = new CachedBuilderFeeService();
const feeData = await feeService.getMaxFee();

Access builder fee information with Dwellir's HyperCore Info Endpoint. Get your API key →