Monetize Widget swaps

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.

<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`.

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

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

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%
        },
      }}
    />
  );
}

<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.

<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.

Configure — all other config fields.
Widget API reference — full PartnerConfig / ReferrerConfig types.

​Partner fees

​PartnerConfig fields

​Choosing between fee and surplus

​Example: fixed-fee integration

​Example: surplus-share integration

​Referrer revenue

​ReferrerConfig fields

​Production tips

​Related pages

Partner fees

`PartnerConfig` fields

Choosing between fee and surplus

Example: fixed-fee integration

Example: surplus-share integration

Referrer revenue

`ReferrerConfig` fields

Production tips

Related pages