Partners
Attribute trades to a Partner and claim settled Partner fees.
Attribute a trade
Use your registered partnerId on each trade. Partners earn a share of the base platform fee; current Registry rates apply to new trades.
const usability = await client.getPartnerUsability(partnerId);Handle usability and earnings separately:
partnerId
usable
earning
Effect
bytes32(0)
yes
no
Trades normally, no attribution
Registered, disabled
yes
no
Trades normally, still logged, earns nothing
Non-zero, unregistered
no
no
The whole trade reverts
An enabled, registered Partner is usable and earns fees. A disabled Partner remains usable for trading but earns no new fees. Check getPartnerUsability before displaying a referral incentive.
Pass partnerId to prepareBuy or prepareSell. For Uniswap V4 swaps, use encodeLaunchpadPartnerHookData; empty bytes means no Partner. Invalid encoding or an unregistered nonzero ID reverts.
Claim Partner fees
Only the current recipient in the Partner Registry can claim. Disabled Partners keep their balances but cannot claim until re-enabled. A recipient change transfers access to the entire unclaimed balance.
const partner = await client.getPartner(partnerId);
const balance = await client.getPartnerClaimableBalance({ partnerId, asset });
// Connect partner.recipient and confirm partner.enabled before claiming.
const claim = await client.preparePartnerClaim({ partnerId, asset });
const claimHash = await client.send(claim);
const result = await client.wait(claimHash, { confirmations: chain.confirmations });
if (result.status !== "confirmed") throw new Error("Partner claim reverted");
const updatedBalance = await client.getPartnerClaimableBalance({ partnerId, asset });Track pending earnings
V4 settlement may convert only part of a Partner’s fees. Unconverted balances carry into the next epoch and remain pending. Keep pending and claimable amounts separate in the earnings view.
Direct contract calls
Read PartnerRegistry.partner(bytes32 partnerId) → PartnerConfig for the controller, recipient, fee share, existence and enabled status; partnerPolicy() → PartnerPolicy exposes the default and maximum shares. SDK Partner reads and claims use these same contracts.
FeeEscrow.partnerBalance(bytes32 partnerId, address asset) → uint256andclaimPartner(bytes32 partnerId, address asset) → uint256 amount: read and claim Partner revenue. Claim caller must be the current registered recipient; disabling the Partner freezes claims.
For curve trades, use the five-argument buyExactIn / sellExactIn overload with partnerId. Zero bytes32 means no Partner; unknown nonzero IDs revert, while a known disabled Partner earns no trade share. For V4, use the hookData rules in the dedicated Hook guide.
Last updated
Was this helpful?