> ## Documentation Index
> Fetch the complete documentation index at: https://www.velora.xyz/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Monetize Widget swaps

> Collect partner fees or surplus revenue from every swap routed through the widget.

The widget supports two monetization surfaces:

* `partnerConfig` — fee or surplus share on every swap that completes through your integration.
* `referrerConfig` — a referrer wallet that receives a share of protocol revenue.

Both are optional and independent.

## Partner fees

Pass `partnerConfig` inside `config` to identify your integration and (optionally) take a cut of each swap.

```tsx theme={null}
<Widget
  config={{
    partnerConfig: {
      partner: "my-app-name",
      partnerAddress: "0xYourFeeCollector",
      partnerFeeBps: 25,
    },
  }}
/>
```

### `PartnerConfig` fields

| Field | Type | Description |
| - | - | - |
| `partner` | `string` | Your `partner` identifier (e.g. `"my-app-name"`). Used for attribution and analytics. |
| `partnerAddress` | `Address` | Optional. Ethereum address that receives the fee. Overrides the address derived from `partner`. |
| `partnerFeeBps` | `number` | Optional. Fee in basis points. `25` = 0.25%. Max `200` (2%). |
| `partnerTakesSurplus` | `boolean` | Optional. When `true`, you receive 50% of swap surplus instead of a fixed fee. Defaults to `false`. |

<Note>
  If both `partnerFeeBps` and `partnerTakesSurplus` are set, `partnerFeeBps` wins. To take surplus instead of a fixed fee, set `partnerTakesSurplus: true` and leave `partnerFeeBps` unset.
</Note>

Either `partner` or `partnerAddress` must be present for partner features to activate.

### Choosing between fee and surplus

| | Fixed fee (`partnerFeeBps`) | Surplus share (`partnerTakesSurplus`) |
| - | - | - |
| Revenue | Predictable per-trade cut | Variable; depends on routing edge |
| User cost | Worse quotes (fee comes off the top) | Same quote as no-fee: surplus is the *better-than-quoted* portion |
| Max | 2% (`partnerFeeBps: 200`) | 50% of surplus |
| Best for | Mass-market integrations where a known cut matters | High-volume integrations that prioritize the user-facing rate |

### Example: fixed-fee integration

```tsx theme={null}
import { Widget } from "@velora-dex/widget";

export function Swap() {
  return (
    <Widget
      config={{
        theme: "light",
        partnerConfig: {
          partner: "my-app-name",
          partnerAddress: "0xYourFeeCollector",
          partnerFeeBps: 25, // 0.25%
        },
      }}
    />
  );
}
```

### Example: surplus-share integration

```tsx theme={null}
<Widget
  config={{
    partnerConfig: {
      partner: "my-app-name",
      partnerAddress: "0xYourFeeCollector",
      partnerTakesSurplus: true,
    },
  }}
/>
```

## Referrer revenue

Pass a `referrerConfig` to attribute swaps to a referrer wallet that receives a share of protocol revenue. This is independent of `partnerConfig`: you can set one, both, or neither.

```tsx theme={null}
<Widget
  config={{
    referrerConfig: {
      referrerAddress: "0xReferrerWallet",
    },
  }}
/>
```

### `ReferrerConfig` fields

| Field | Type | Description |
| - | - | - |
| `referrerAddress` | `Address` | Ethereum address that receives the referrer share. Required to activate referrer attribution. |

## Production tips

Load `partner` from an environment variable so staging, production, and white-label builds can use different identifiers without code changes. Memoize `partnerConfig` like every other non-primitive config field; a new object on every render forces the widget to re-render. And audit `partnerAddress` before shipping: once a swap is routed, fees pay to it on-chain, so treat it like any other treasury address.

## Related pages

* [Configure](/docs/widget/configure) — all other config fields.
* [Widget API reference](/docs/widget/widget-api-reference) — full `PartnerConfig` / `ReferrerConfig` types.


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