HGP-88: Builder Code Support for DEX Connectors

1. Summary

This proposal formalizes a builder-code interface for Hummingbot DEX connectors and a matching application integration spec in Hummingbot API. Builder codes are a native per-order revenue-share primitive offered by modern DEXes (dYdX v4, Hyperliquid spot and perp, GRVT, Pacifica, Lighter spot and perp, Decibel). They allow a third-party "builder" — typically a frontend or routing application — to attach a small fee to every fill it originates, settled by the venue. Venue caps range from 10 bps (Hyperliquid perps) to 100 bps (dYdX, Hyperliquid spot), with user-signed caps on GRVT, Pacifica, Lighter, and Decibel. Where a venue exposes builder codes across both spot and perp markets (Hyperliquid, Lighter), this proposal applies to both connectors.

The design separates the connector mechanism from the monetization policy:

1. Hummingbot connectors always inject a builder identity into every perp order on the four venues where 0-bps attribution requires no user approval: Hyperliquid, dYdX v4, GRVT, and Pacifica. The Hummingbot Foundation builder is the default on these venues, configured at 0 bps — attribution only, no user approval required, no fees charged. On Lighter and Decibel, where any builder attribution requires user pre-approval, the open-source default is no builder configured — partner fields are omitted unless an application explicitly configures one.
2. Applications built on Hummingbot API (Condor today, others later) override the connector's builder configuration with their own builder identity and a non-zero fee. The Foundation defaults to 0 bps for attribution; applications choose their own builder address and fee rate based on their monetization strategy (Condor at 1 bps, others potentially higher). Hummingbot does not orchestrate builder-approval actions — connectors accept either main wallet or agent wallet credentials for trading as they do today, but Hummingbot core and Hummingbot API do not call ApproveBuilderFee, ApproveIntegrator, or approveMaxBuilderFee on the user's behalf. Applications collect approvals at their own UI layer via web-based wallet integration and hand the resulting credentials (with approval already in place) to Hummingbot API.
3. Hummingbot API exposes /connectors/{name}/builder-info so applications can render approval status (including expiry where the venue enforces one), request user approval when missing, and gate trading until approval lands.

This separation keeps Hummingbot's Apache 2.0-licensed core free of any user-paid fee logic and out of the builder-approval orchestration business, while giving apps a clean, portable surface to monetize their distribution.

If approved, this proposal authorizes implementation on all existing Hummingbot DEX connectors that support builder codes — currently Hyperliquid (spot and perp), dYdX v4, GRVT, Pacifica, Lighter, and Decibel — plus the supporting Hummingbot API surface and a reference Condor integration. The same connector-level pattern applies to any future DEX connector whose venue ships a builder-code primitive, spot or perp; new connectors are authorized to adopt the interface at creation time without requiring a separate HBP.

---

2. Motivation

2.1 Why builder codes are different from CEX broker integrations

Hummingbot has long had a monetization layer on the CEX side via API broker integrations: certain CEX connectors are wired so that trades carry a broker code, the exchange identifies that volume, and the exchange rebates a portion of its own fee back to the broker. From the trader's perspective this is invisible — they pay the standard exchange fee and nothing more. The broker fee comes out of the exchange's margin, not the trader's pocket.

DEXes don't have margin to rebate. Hyperliquid, dYdX, GRVT, Pacifica, Lighter, and Decibel all run thin protocol fees (around 4 bps perp taker on most venues; spot fees vary) and don't operate a CEX-style broker rebate program. Instead they ship builder codes: an explicit, trader-paid surcharge layered on top of the protocol fee, routed by the venue to the application that originated the order. The model is different in two important ways:

• User-paid, not venue-rebated. The fee is charged on top of the venue's own fee. Disclosure to the user is therefore essential — both at the application's UI layer and via the venue's order/fill APIs (which all four expose).
• Application-scoped, not core-scoped. The Hummingbot Foundation does not charge a builder fee. Monetization happens at the application layer, where the app onboards the user, signs a builder approval with the user's main wallet, and configures its own builder identity in its Hummingbot API deployment.

Other properties:

• Venue-native. The fee is collected and settled by the exchange, not bolted on by Hummingbot. No custodial flow inside Hummingbot, no internal accounting, no protocol risk.
• Small and bounded. Typical configurations are in the 1–10 bps range, well under venue caps.
• Already standard on Web3 DEXes. Most Hyperliquid frontends already use builder codes, and the primitive has spread to spot venues. This proposal aligns Hummingbot with current Web3 DEX practice rather than inventing anything.

2.2 How this proposal positions

This proposal ships connector-level builder code support with the Foundation builder configured at 0 bps for attribution only — no user-paid fee, no approval flow in the open-source core. Applications built on Hummingbot API override this default with their own builder identity and non-zero fee, and orchestrate the user-facing approval flow at their UI layer.

2.3 Why a spec, not a one-off

Condor is the immediate driver, but the goal is a portable interface. Any application built on Hummingbot API — a market-making dashboard, a copy-trading frontend, a Telegram bot — should be able to register its own builder code and earn on its volume without forking the Hummingbot connectors.

A formalized interface in Hummingbot:

• Removes per-application connector forks.
• Ships a reference implementation in the open-source core that any application can configure with its own builder identity.
• Gives application developers a documented surface (/connectors/{name}/builder-info, configurable builder identity, application-layer approval flow) they can rely on.

2.4 Why now

Three of the four target venues have builder code APIs in production today. Hyperliquid in particular has become the dominant Web3 perp venue, and every serious Hyperliquid frontend already uses builder codes. Shipping without builder-code support means Hummingbot-based applications competing on Hyperliquid distribution are leaving the only available revenue primitive on the table.

3. Background: How builder codes work

(Due to size constraints, the remainder of the proposal and background information are in the Notion docs below)

Proposal: https://www.notion.so/hummingbot-foundation/Builder-Codes-Proposal-365c9b8ea4f7809eb256c0db6d25e732?source=copy_link

Implementation: https://www.notion.so/hummingbot-foundation/Builder-Codes-Implementation-365c9b8ea4f7800f9b11f7ef4b078a15?source=copy_link

Background Research: https://www.notion.so/hummingbot-foundation/Builder-Codes-Research-35ec9b8ea4f780159811de87295e2545?source=copy_link