Builder Codes

Most venues let a front-end register a builder identity and stamp it on the order flow it sends, so the venue can attribute that flow back to you. AGG stores one builder value per app, per venue, and applies it when your users trade.

​

Configuring

Open the admin dashboard → select your app → Settings → Builder Codes. Each supported venue has its own card showing the current value, when it was last updated, and live usage counters. Only the owner of an app can set, update, or remove a builder code. Other members see the section but get a 403 on write.

​

Where to get each value

• Polymarket — create a builder profile at polymarket.com/settings?tab=builder. Both the maker and taker fee rate on that profile must be 0.
• Hyperliquid — any EVM address you control. It’s the address HL credits for the order flow.
• Predict.fun — your 5-character referral code from your Predict.fun account.

​

Polymarket is validated on save

Polymarket is the one venue where AGG verifies your input before storing it. On save, the API calls Polymarket’s CLOB at GET /fees/builder-fees/<builderCode> and refuses the write unless:

1. The endpoint returns 200 — a 404 means the code isn’t registered with Polymarket at all.
2. Both builder_taker_fee_rate_bps and builder_maker_fee_rate_bps are 0.

There is no bypass. If the CLOB is unreachable or returns a non-2xx, the save fails and you’re told to retry — AGG would rather block than persist a code it could not verify. On success the response’s fee tier is snapshotted onto the row and shown as the registration timestamp in the dashboard. Hyperliquid and Predict.fun are format-validated only; there is no venue-side registration check on save.

​

Fees are always zero

AGG rejects any attempt to attach a builder fee to a builder code:

• The upsert body rejects builderFeeTenthsBps and feeRateBps outright.
• Polymarket profiles with a non-zero maker or taker rate are rejected on save.
• On Hyperliquid, configuring an app builder address forces the order’s builder fee to 0. Because the fee is zero, AGG also skips the approveBuilderFee handshake your users would otherwise have to sign — swapping in your own builder address costs your users nothing and adds no extra signature prompt.

App-level revenue is configured separately from builder codes.

​

How each venue applies it

Attribution works differently per venue, and the difference is worth knowing because it changes when your code takes effect.

​

Polymarket and Hyperliquid — per order

The code rides every order. When a user of your app submits, the executor looks up the (appId, venue) row via the user’s owning app and stamps it on that order. If there’s no row — or it’s disabled — the order falls back to AGG’s platform-wide builder value for that venue, or to no attribution at all. A lookup failure never blocks a trade. Every resolution path swallows its errors and returns “no override”.

​

Predict.fun — once per trader

Predict.fun has no order-level attribution field. Instead, the referral code is attached to the trader’s Predict.fun account, once, on their first order through your app. AGG records that it has done so and never asks the venue again for that user. Two consequences worth planning around:

• It’s one-shot per trader. Predict.fun only accepts a referral “if not already set”. A trader who already has a referral on their Predict.fun account keeps it — your code will not replace it.
• Rotating your code only affects new traders. Changing the value in admin lets the next order retry the write for traders who never had one land; it cannot re-attribute traders already referred.

The write runs alongside the order rather than gating it, so a slow or failing Predict.fun referral endpoint never delays or fails a trade. A transient failure (venue 5xx, network) is retried on that trader’s next order; a definitive refusal is not retried, since asking again cannot change it.

​

Usage stats and auto-disable

Every submit that uses your code updates the row, which is what the dashboard card renders: On Polymarket, a failure only counts against your code when the error looks like it came from the code itself — the message mentions “builder”, or it’s a rate-limit (429), 401, or 403. That order is then retried immediately with the platform fallback code, so a bad builder code degrades attribution, not fills. Balance, allowance, and liquidity errors are never blamed on the code. After 5 consecutive attributable failures the row is auto-disabled with the reason auto: 5 consecutive failures. While disabled it is skipped entirely and every order uses the fallback. The dashboard shows the disabled state and reason. Auto-disable applies to Polymarket and Hyperliquid only. Predict.fun rejections are counted and shown, but never disable your code: the most common rejection is simply that the trader already had a referral on their account, which says nothing about whether your code is valid. Each trader is asked at most once either way. Re-saving the code clears the disabled marker, resets consecutiveFailures to 0, and clears the last error — for Polymarket that means it also re-runs the CLOB validation, so a re-save doubles as a health check. There’s no separate “re-enable” button.

​

Removing

Remove on the venue card deletes the row. Subsequent orders fall back to the platform builder value for that venue. For Predict.fun, removal stops new traders from being referred, but does not un-refer traders whose accounts already carry your code — the venue has no API to reverse it.