For the complete documentation index, see llms.txt. This page is also available as Markdown.

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) → uint256 and claimPartner(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?