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.
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%
},
}}
/>
);
}
Example: surplus-share integration
<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.
Related pages
