Technical Documentation

How builder codes work at the protocol level, plus the API and actions you integrate with. Builder codes apply to perpetual, spot and prediction (outcome) markets — on spot, to sell fills only — and everything below runs on testnet today — no application needed.

Builder address

• An EVM externally owned account (EOA). Contract and multi-sig addresses are not supported.
• It cannot be the same address you or your users trade from, and cannot be the zero address or a vault.
• Use separate addresses for testnet and mainnet.

Eligibility

Your builder address earns fees only while its Perps account holds at least 100 USDC. Below that, orders still fill, but the builder fee on those orders is 0. This is a check on your own perpetual sub-account, not on the market being traded. Check the eligible flag in builderState.

User approval

• The user signs approveBuilderFee from their main wallet (EIP-712), naming your builder address and a maxFeeRate.
• Agent wallets and API keys cannot grant this approval — it is the user's own decision about their money.
• A user can approve up to 20 builders at once. Submitting the action again for the same builder updates the rate without using another slot.
• The approval is live once the action lands in a block. The user can remove it at any time with revokeBuilderFee, which sets the rate to 0 and marks the approval REVOKED.

{
  "type": "approveBuilderFee",
  "txflowNetwork": "TxFlow-Testnet",
  "chainId": 2511,
  "apiVersion": 1,
  "builder": "0x2e4D75dF2eE2653Ea7A113Cc1Fa36d45e923061F",
  "maxFeeRate": "0.05%",
  "nonce": 1757992743994
}

maxFeeRate is a percentage string ("0.05%"), greater than zero and at most 1%.

In a new account's setup, the approval comes after the deposit and before the user authorizes your agent key — see Set up an account. Before routing, confirm the approval and its cap with maxBuilderFee, or list every builder the user has approved with approvedBuilders.

Attaching your code to orders

Add a builder object at the action level of each order. It sits beside orders, not inside an individual order, and the order signature covers it.

{
  "type": "order",
  "grouping": "na",
  "orders": [
    { "a": 1, "b": true, "p": "50000.0", "s": "0.01", "r": false, "t": { "limit": { "tif": "Gtc" } } }
  ],
  "builder": { "b": "0x2e4D75dF2eE2653Ea7A113Cc1Fa36d45e923061F", "f": 50 }
}

• b is your builder address.
• f is your fee in tenths of a basis point: f: 50 is 0.05%.

This unit is the easiest thing to get wrong:

f must satisfy both the user's approval and the market cap:

Builder fee = notional value × f / 100,000

Spot: sell fills only

On spot, the protocol charges the builder fee on the sell leg only:

• Sell fill — the fee is deducted in USDC from the quote the user has just received, and accrues to you like any other builder fee.
• Buy fill — no builder fee. The order is still valid with a builder object attached, and still fills; the rate is ignored.

This is by design: a spot order reserves only its principal when it rests, so a buy has no USDC set aside to pay a builder fee from, while a sell receives USDC on the fill. Because the builder object is harmless on buys, you can attach it to every spot order and let the protocol charge only where it applies. Show no builder fee on buy tickets.

Builder fees are additional to TxFlow trading fees: the user pays their own fee tier plus your builder fee.

Claiming

• Fees accrue to claimableRewards in real time.
• claimBuilderRewards sweeps the full balance to your builder Perps account. Partial claims are not supported. It is signed by an agent key authorized by your builder address, not by the builder address itself.
• The claim moves claimableRewards into claimedRewards; accruedRewards is the lifetime figure and does not change. With nothing to claim, the action fails with No unclaimed builder rewards.

{ "type": "claimBuilderRewards" }

Check your builder state

builderState shows your lifetime accrued, claimable and claimed amounts, your eligibility, and your active user count. Pass your builder address as user.

{
  "type": "builderState",
  "user": "0x4916d34209A2E010912dE8b412A90ECcEc77D8aC"
}

{
  "accruedRewards": "0.000000",
  "claimableRewards": "0.000000",
  "claimedRewards": "0.000000",
  "eligible": true,
  "perpsAccountValue": "200.012971",
  "isStandardAccount": true,
  "activeUserCount": 0
}

If accruedRewards is not moving on flow you are tagging, check eligible first.

Builder actions

Mainnet and testnet APIs are the same. A working testnet integration needs no code changes beyond the network endpoint and your mainnet builder address.

Development guide

1. Set up addresses. Create separate builder EOAs for testnet and mainnet. Endpoints, signing and every action are documented in the Builder API Reference.
2. Fund your builder account. Deposit at least 100 USDC and verify eligibility with builderState.
3. Implement user onboarding. Guide users through wallet connection, deposit, approveBuilderFee, and trading authorization (approveAgent).
4. Verify authorization. Check the user's approved fee rate with maxBuilderFee before routing orders, and make sure f does not exceed it.
5. Attach the builder object. Include the builder object in every order.
6. Display fees. Show builder fees separately in trade tickets and confirmations.
7. Monitor and claim. Track earnings with builderState and call claimBuilderRewards to claim available fees.
8. Test and deploy. Complete end-to-end testing on testnet with Try Testnet, then switch to the mainnet endpoint and builder address.