Builder Code

A builder code lets you charge your own fee on the fills you submit for someone else. If you run a frontend, a bot, a wallet integration, or any app that routes order flow to TxFlow, this is how you earn from that flow. It applies to perpetual and outcome markets.

It works entirely through signed actions and on-chain fee logic — there is no revenue-share agreement to sign, no off-chain accounting, and no separate payout rail:

1. The user approves a cap for your builder address, signed with their own key.
2. Your orders carry your builder address and a fee within that cap.
3. You claim what has accrued, whenever you want.

The fee is charged per order, so the same builder can price different flows differently — up to whatever the user approved.

1. The user approves your cap

The user signs approveBuilderFee with their main key. An agent key cannot grant this — the approval is the user's own decision about their money.

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

• maxFeeRate is a percentage string ("0.02%"), greater than zero and at most 1%.
• A user may hold 20 approvals at once. Submitting the action again for the same builder updates the rate without consuming another slot.
• The builder cannot be the zero address, the user themselves, or a vault.
• The approval is live once the action lands in a block.

The user can withdraw it at any time with revokeBuilderFee, which sets the rate to 0 and marks the approval REVOKED.

2. Your orders carry the builder object

Add one action-level builder object to the order action. It sits beside orders, not inside an individual order body, 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": 10
  }
}

f is the fee in tenths of a basis point — rate = f / 100,000. This unit is the easiest thing to get wrong:

Builder codes apply to perpetual and outcome markets. f must satisfy both the user's approval and the per-market cap:

If the builder object is absent, the builder is not approved by that user, or f exceeds either cap, the builder fee is ignored and the order still goes through — you get no rejection to debug.

3. You claim what you have earned

Fees accrue to your builder address as they are collected. Claim them with claimBuilderRewards, which is agent-signed — an authorized agent may submit the claim for its owner.

{ "type": "claimBuilderRewards" }

• The claim takes the full unclaimed balance; there is no partial amount to specify.
• It moves claimableRewards into claimedRewards. accruedRewards does not change — it is the lifetime figure.
• With nothing to claim, the action fails with No unclaimed builder rewards.

Check your builder state

builderState is the read side of all of the above: what you have earned, what you can claim, and whether you currently qualify to accrue at all. 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
}

Because an over-cap or unapproved builder object is dropped silently, this is the query to watch: if accruedRewards is not moving on flow you are tagging, check eligible first.

Requirements

Next steps

• approveBuilderFee — the approval action and its EIP-712 type.
• revokeBuilderFee — how a user removes an approval.
• claimBuilderRewards — the claim action and its signing preimage.
• builderState — the read side: accrual, payouts, and eligibility.
• Attach a builder to an order — the builder field in the order envelope.
• Signing — the two signing flows the actions above use.
• Try Testnet — run the whole flow against testnet from your browser.