Builders
Build a trading app, a bot or a terminal on notional and charge a fee of your own on every trade you bring. Register a builder code with your fee, send your users' trades through the Router with it, and collect your fees in HYPE every week.
How it works
- Register a code in the Builder registry, with your fee and the address it is paid to.
- Send your users' trades through the Router with your code in each one. The Router takes your fee from each of them.
- Every Monday, the fees your code collected the week before are paid in HYPE.
If you know builder codes from Hyperliquid, these work much the same way: the trader pays your fee on top of the trade, at a rate you choose under a cap. They are not shared with Hyperliquid, so register your code here.
notional's own website is a builder too. It sends its trades with the code notional and adds no fee of its own. The builders table on Stats lists every builder with the volume it routes and the fees it has earned.
Your fee
You set your fee when you register your code: from 0 to 0.1% of each trade, in steps of 0.01%. The trader pays it on top of the trading fee. It is never taken from notional's fees, the stakers' rewards or the liquidity providers' earnings.
The Router takes your fee from the token the trader pays in, before it trades, and sends it to the Builder registry. Say your fee is 0.05% and a user buys a coin with 1,000 USDC through your app: the Router keeps 0.50 USDC for you and trades the other 999.50 USDC, which pays the curve's usual 1%.
- Weeks run Monday to Sunday in UTC. Each week, the registry converts the fees your code collected to HYPE and credits them to your code on the next Monday at 00:00 UTC, when staking rewards are paid too.
- Claim them to your payout address whenever you like. Credited fees do not expire.
Requirements
- A code. 3 to 16 characters: lower-case letters, digits and hyphens. Codes are first come, first served, and registering one costs only the network fee. The address that registers a code can change its fee and its payout address later. A new fee applies to trades from then on.
- The code on chain. It must be in the Router call itself. A code in a link, a URL or your own records credits nothing.
- The full cost, shown first. Before your user signs, show notional's fee and yours apart, then the quote and the minimum they will accept.
How attribution works
- Attribution is per transaction. The Router reads the code from the call, checks that it is registered, and takes its fee. Its
Routedevent records the code and the fee next to the trade. - A trade with no code, with a code nobody registered, or sent straight to a pool or to the Launchpad pays no builder fee and credits no builder. It still goes through as normal.
- There are no referral links and no sticky attribution: a user who trades through two apps pays each one only on the trades sent through it.
- A trade credits only the code in its own call, so nobody can claim the trades your app sends.
Integrating
Preview addresses: no contract is deployed at any address in these docs. Do not send transactions, funds or tokens to them.
These examples use viem in the browser. The first sets up the clients that the other two use. See Contracts for every address.
import "viem/window"; // Types window.ethereum.
import { createPublicClient, createWalletClient, custom, http, parseEther, stringToHex, zeroAddress } from "viem";
import { hyperEvm } from "viem/chains";
if (window.ethereum === undefined) throw new Error("No browser wallet found");
const publicClient = createPublicClient({ chain: hyperEvm, transport: http() });
const walletClient = createWalletClient({ chain: hyperEvm, transport: custom(window.ethereum) });
const [account] = await walletClient.requestAddresses();
if (account === undefined) throw new Error("The wallet shared no address");
// Your code, as the bytes32 the contracts take.
const BUILDER_CODE = stringToHex("myapp", { size: 32 });Register your code
const REGISTRY = "0x5b486c48aa83ae6022ff528161f7a14bdcb816d5";
const registryAbi = [
{
type: "function",
name: "payoutOf",
stateMutability: "view",
inputs: [{ name: "code", type: "bytes32" }],
outputs: [{ name: "payout", type: "address" }],
},
{
type: "function",
name: "register",
stateMutability: "nonpayable",
inputs: [
{ name: "code", type: "bytes32" },
{ name: "payout", type: "address" },
{ name: "feeBps", type: "uint16" },
],
outputs: [],
},
] as const;
// A code is free while it has no payout address.
const payout = await publicClient.readContract({
address: REGISTRY,
abi: registryAbi,
functionName: "payoutOf",
args: [BUILDER_CODE],
});
if (payout !== zeroAddress) throw new Error("That code is taken");
// Register it, paid to this wallet, with a fee of 0.05%: 5 basis points, of at most 10.
const { request } = await publicClient.simulateContract({
account,
address: REGISTRY,
abi: registryAbi,
functionName: "register",
args: [BUILDER_CODE, account, 5],
});
await walletClient.writeContract(request);Pass your code in a trade
Send every trade through the Router's swap, with your code as its last argument. For a coin paired with USDC or a stock, approve the Router to spend that token first, pass its address as tokenIn and send no value.
const ROUTER = "0x538a6e8231d4acf16a8546d2f93f7c44fb80831d";
const NOTIONAL = "0x7e57000000000000000000000000000000000000";
const routerAbi = [
{
type: "function",
name: "quote",
stateMutability: "view",
inputs: [
{ name: "tokenIn", type: "address" },
{ name: "tokenOut", type: "address" },
{ name: "amountIn", type: "uint256" },
{ name: "builderCode", type: "bytes32" },
],
outputs: [{ name: "amountOut", type: "uint256" }],
},
{
type: "function",
name: "swap",
stateMutability: "payable",
inputs: [
{ name: "tokenIn", type: "address" },
{ name: "tokenOut", type: "address" },
{ name: "amountIn", type: "uint256" },
{ name: "minAmountOut", type: "uint256" },
{ name: "recipient", type: "address" },
{ name: "deadline", type: "uint256" },
{ name: "builderCode", type: "bytes32" },
],
outputs: [{ name: "amountOut", type: "uint256" }],
},
] as const;
// Buy NOTIONAL with 1 HYPE. The zero address stands for HYPE, which is sent as the value.
const amountIn = parseEther("1");
// With your code, the quote takes your fee out first: it is what your user will receive.
const quoted = await publicClient.readContract({
address: ROUTER,
abi: routerAbi,
functionName: "quote",
args: [zeroAddress, NOTIONAL, amountIn, BUILDER_CODE],
});
// Accept up to 2% less than the quote, and only in the next 5 minutes.
const minAmountOut = (quoted * 98n) / 100n;
const deadline = BigInt(Math.floor(Date.now() / 1000) + 300);
// Simulate first: a trade that would fail is caught here, before the wallet asks to sign.
const { request } = await publicClient.simulateContract({
account,
address: ROUTER,
abi: routerAbi,
functionName: "swap",
args: [zeroAddress, NOTIONAL, amountIn, minAmountOut, account, deadline, BUILDER_CODE],
value: amountIn,
});
const hash = await walletClient.writeContract(request);