> ## Documentation Index
> Fetch the complete documentation index at: https://dev.bloombot.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Builder fees

> Earn a share of the swaps your integration sends, paid to your wallet in the same transaction.

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](/api-reference/swap.md), 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.

```json theme={null}
{
  "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`](/concepts/chains).
* **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](/concepts/auto-orders.md)
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.**

> [!WARNING]
>
> 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`](/concepts/errors) 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:

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.