Builder codes en Hyperliquid: la comisión oculta de bots, wallets y frontends de terceros

En resumen: un builder code permite que una app que envía órdenes por ti (una wallet, un bot de Telegram, un frontend alternativo) añada su propia comisión encima de la de Hyperliquid. Apruebas un máximo una vez con tu wallet principal y, a partir de ahí, la app puede cobrar hasta ese porcentaje en cada ejecución, con un tope del protocolo del 0,1% en perps y del 1% en spot. Todo es onchain: puedes auditar cuánto has pagado y revocar aprobaciones cuando quieras.

¿Qué es un builder code en Hyperliquid?

En la documentación de Hyperliquid, un «builder» es una app DeFi construida sobre el exchange, no un constructor de bloques. Los builder codes son la forma en que esas apps cobran: cada orden que la app envía en tu nombre puede llevar un parámetro builder con la dirección de la app y una comisión. Cuando la orden se ejecuta, esa comisión se te cobra dentro de la lógica normal de fees y se abona al builder, que la reclama como las recompensas de referidos.

Por eso el mismo trade de BTC puede salir bastante más caro desde un bot de Telegram o la pestaña de perps de una wallet que desde app.hyperliquid.xyz. El libro de órdenes, el precio y la liquidez son los mismos; el sobrecoste es la builder fee.

Cómo funcionan, paso a paso

1. Aprobación. La primera vez que usas una app, te pide firmar una acción ApproveBuilderFee que fija la comisión máxima que ese builder puede cobrarte. Debe firmarla tu wallet principal; una API wallet o agent wallet no puede.
2. Órdenes. Cada orden posterior puede incluir {"b": direcciónBuilder, "f": comisión}, donde f va en décimas de punto básico. f = 10 es 1 pb (0,01%) y f = 100 son 10 pb (0,1%).
3. Cobro. En cada ejecución, la builder fee se suma a la comisión normal de Hyperliquid. Nunca puede superar el máximo aprobado ni el tope del protocolo.
4. Revocación. Puedes cambiar o revocar la aprobación cuando quieras con tu wallet principal.

Límites que conviene conocer

Regla	Valor
Builder fee máxima en perps	0,1% del nocional (10 pb)
Builder fee máxima en spot	1% (solo en el lado pagado en el activo de cotización, no en compras spot)
Cuándo se cobra en perps	En apertura y en cierre
Aprobaciones activas por usuario	Hasta 10 builders a la vez
Quién puede aprobar	Solo la wallet principal, no agent/API wallets
Requisito del builder	Al menos 100 USDC de valor en su cuenta de perps

Ejemplo: lo que cuesta de verdad una builder fee

Supón que mueves 50.000 USDC de nocional al día en perps, casi siempre como taker. La comisión taker base en el primer tramo de volumen de Hyperliquid es 0,045% (tramos y descuentos en nuestra guía de comisiones).

Vía	Comisión por ejecución	Coste diario	Coste en 30 días
Hyperliquid directo	0,045%	22,5 USDC	675 USDC
App con builder fee del 0,02%	0,065%	32,5 USDC	975 USDC
App con builder fee del 0,05%	0,095%	47,5 USDC	1.425 USDC
App en el tope del 0,1%	0,145%	72,5 USDC	2.175 USDC

En el tope, la builder fee por sí sola es más del doble de la comisión del exchange. Para un trader activo, esa diferencia suele ser mayor que su PnL mensual. Las cifras son ilustrativas: tu coste real depende de tu tramo, tu mezcla maker/taker y la tarifa real del builder.

¿Merece la pena pagar una builder fee?

A veces sí. Un buen bot, un flujo móvil que de verdad usas, copy trading u órdenes avanzadas pueden justificar unos puntos básicos. Lo que quieres evitar es pagar un 0,1% en cada ejecución sin saberlo, sobre todo si operas a menudo, haces scalping o mueves mucho nocional con apalancamiento alto. Las comisiones se calculan sobre el nocional, no sobre el margen: a 20x, una builder fee del 0,1% en entrada y salida es un 4% de tu margen por operación completa. Lo explicamos en la guía de apalancamiento y la guía de PnL real.

Cómo ver qué builders tienes aprobados

Es información pública onchain, así que puedes consultarla sin conectar la wallet ni compartir claves. Dos endpoints de info bastan:

• {"type": "approvedBuilders", "user": "0x..."} devuelve las direcciones de builders que tienes aprobadas.
• {"type": "maxBuilderFee", "user": "0x...", "builder": "0x..."} devuelve el máximo aprobado para un builder, en décimas de punto básico (100 = 0,1%).

Cómo saber cuánto has pagado en builder fees

Cada fill que devuelve userFills o userFillsByTime tiene un campo fee (la comisión total, builder incluida) y un campo opcional builderFee, que solo aparece si se cobró builder fee. Sumándolo obtienes tu coste exacto. Este script en Python muestra el total reciente, las monedas con más builder fee y cada builder aprobado con su máximo:

import requests
from collections import defaultdict

USER = "0xYourAddress"
URL = "https://api.hyperliquid.xyz/info"

fills = requests.post(URL, json={"type": "userFills", "user": USER}).json()
total_fee = sum(float(f["fee"]) for f in fills)
builder_fee = sum(float(f.get("builderFee", 0)) for f in fills)
by_coin = defaultdict(float)
for f in fills:
    by_coin[f["coin"]] += float(f.get("builderFee", 0))

print(f"Fills checked: {len(fills)}")
print(f"Total fees: {total_fee:.2f}  of which builder fees: {builder_fee:.2f}")
for coin, fee in sorted(by_coin.items(), key=lambda x: -x[1])[:10]:
    if fee:
        print(coin, round(fee, 2))

approved = requests.post(URL, json={"type": "approvedBuilders", "user": USER}).json()
for b in approved:
    mx = requests.post(URL, json={"type": "maxBuilderFee", "user": USER, "builder": b}).json()
    print(b, "max approved:", mx / 1000, "%")

userFills devuelve tus fills más recientes (hasta 2.000); para más historial, pagina con userFillsByTime indicando inicio y fin. Si empiezas con la API, mira nuestra guía de la API de Hyperliquid con Python. Para un CSV completo con comisiones por fill, consulta cómo exportar tu historial de trades.

Cómo revocar o bajar una aprobación

Se revoca firmando un nuevo ApproveBuilderFee para ese builder con un máximo menor, o cero, desde tu wallet principal. Hazlo desde una interfaz de confianza o con el SDK oficial de Python. Como solo puedes tener 10 aprobaciones activas, limpiar las apps que ya no usas es buena higiene, igual que revocar agent wallets antiguas (ver la guía de API wallets y la guía de seguridad de wallets).

Builder fees vs códigos de referido

Son mecanismos distintos. La builder fee es un cargo extra que añade la app que enruta tus órdenes. Un código de referido hace lo contrario: te da descuento sobre las comisiones de Hyperliquid. El código HYPERFOLIO da un 4% de descuento en tus primeros 25 M$ de volumen; más en la guía del código de referido.

Checklist antes de operar desde una app de terceros

• Lee la solicitud de aprobación: ¿qué comisión máxima estás firmando?
• Compara el coste total de la app con operar directamente en Hyperliquid para tu volumen mensual.
• Prioriza apps que publiquen su tarifa de builder.
• Revisa el campo builderFee tras los primeros trades para confirmar la tarifa real.
• Revoca los builders que ya no uses.

Controla comisiones y PnL real con Hyperfolio

Hyperfolio es un tracker de portfolio gratuito y de solo lectura para Hyperliquid. Nunca te pide firmar nada, así que no tiene aprobación de builder ni cobra builder fee. Pega cualquier dirección y verás posiciones, PnL, comisiones y funding en un solo sitio, compara wallets, sigue al Smart Money y usa la calculadora de perps antes de dimensionar un trade. Instálalo como PWA en el móvil y vigila lo que de verdad te cuesta operar.

Preguntas frecuentes

¿Los builder codes cambian el precio que obtengo?

No. Las órdenes van al mismo libro de Hyperliquid. El builder code solo añade una comisión a las ejecuciones.

¿Puede una app cobrarme más de lo aprobado?

No. El protocolo aplica el máximo aprobado y los topes globales del 0,1% en perps y 1% en spot.

¿Se cobra builder fee en órdenes maker?

Se cobra por ejecución en las órdenes enviadas con el parámetro builder, añadan o retiren liquidez. La app fija la tarifa por orden, hasta tu máximo aprobado.

¿Una agent wallet puede aprobar una builder fee?

No. La aprobación debe firmarla la wallet principal, lo que te protege si se compromete la clave de un bot.

¿Cómo sé si estoy pagando builder fees?

Busca el campo builderFee en tus fills o ejecuta el script de arriba. Si no aparece, en ese fill no se cobró builder fee.