Builder fees

A builder fee lets an integration built on the Bloom API earn a share of each swap it sends. You name a wallet and a rate on the swap request, and that wallet is paid its share in the same transaction as the trade, on top of Bloom’s own fee. It is opt-in per request: a swap that leaves both fields out behaves exactly as before.

{
  "address": "<TOKEN_ADDRESS>",
  "side": "Buy",
  "wallets": [{ "address": "<TRADING_WALLET>", "amount": "2" }],
  "builder_address": "<BUILDER_WALLET>",
  "builder_fee_bps": 50,
  "slippage": 10,
  "priority_fee": 0.001,
  "processor_tip": 0.0001,
  "anti_mev": false,
  "auto_tip": false
}

Here the trading wallet buys with 2 SOL and <BUILDER_WALLET> receives 0.5% of that — 0.01 SOL.

Fields

Field	Type	Description
`builder_address`	string	The wallet that receives the fee: an address on the chain being traded — base58 on the Solana host, `0x…` on the EVM host.
`builder_fee_bps`	integer	The builder’s share in basis points, `1`–`100`. `100` = 1%, `50` = 0.5%, `1` = 0.01%.

Both fields or neither. A request carrying only one of them is rejected rather than executed without the fee — a builder never trades believing they are paid when they are not.

How the fee is charged

Side	The share is taken on
Buy	The amount spent — `amount`, in the quote asset.
Sell	The proceeds of the sale, measured on chain, so the share is exact whatever the execution price.

Paid in the asset the trade settles in — the chain’s native token, or the stablecoin when the swap uses a stable quote_asset.
A separate transfer in the same transaction as the swap. It is atomic with the trade: if the swap does not land, the builder is not paid, and the swap cannot land without paying them.
On top of Bloom’s fee. Bloom’s fee is unchanged, and the builder’s share is not taken out of it.
Per wallet. When a swap runs on several wallets, each wallet’s trade pays its own share.
Rounded down to the asset’s smallest unit.

The fee applies to the swap in the request only. Auto-orders attached to it sell later as trades of their own, and do not pay the builder.

On Solana

A Buy pays the share in addition to amount. The wallet must hold amount plus the builder’s share, Bloom’s fee and the network fees; otherwise the swap fails with INSUFFICIENT_BALANCE.
A Sell’s share is a share of the gross proceeds — what the sale returned before Bloom’s fee.
Stable trades pay the builder’s token account. With quote_asset set to USDC or USD1, the share goes to the builder’s token account for that stable. It is opened in the same transaction if it does not exist yet, so the builder has nothing to set up; the trading wallet pays that one-time account rent.
builder_address cannot be a wallet the swap trades from.

Keep some SOL in the builder wallet. Solana refuses a transfer that would leave an account below the rent-exempt minimum, so a small SOL share sent to an empty wallet fails — and takes the swap with it.

On EVM

builder_address is a 0x address, and the share arrives there directly — as the chain’s native token, or as the stable itself when the swap uses a stable quote_asset. There is no token account to open.

Rejected requests

A builder fee that cannot be applied is refused with INVALID_REQUEST before anything is sent on chain. It is never silently dropped.

Only one of builder_address and builder_fee_bps is set.
builder_fee_bps is 0 or above 100.
builder_address is not a valid address for the chain.
builder_address is one of the wallets the swap trades from.

The message says which:

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "invalid request: builder_fee_bps must be between 1 and 100"
  }
}

Getting Started

Core Concepts

Fields

How the fee is charged

On Solana

On EVM

Rejected requests

​Fields

​How the fee is charged

​On Solana

​On EVM

​Rejected requests

Fields

How the fee is charged

On Solana

On EVM

Rejected requests