# Partner

The Partner system allows integrators to earn referral fees from swaps executed through their platforms. When users swap through a registered partner, a portion of the protocol fees is allocated to that partner.

## 1. How Partner Fee Collection Works <a href="#how-partner-fee-collection-works" id="how-partner-fee-collection-works"></a>

#### Fee Accumulation Mechanism <a href="#fee-accumulation-mechanism" id="fee-accumulation-mechanism"></a>

```
User Swap with Partner
        ↓
Protocol calculates referral_fee = protocol_fee × ref_fee_rate / 10^9
        ↓
Referral fee is stored in Partner.balances (on-chain Bag)
        ↓
Fees accumulate across multiple swaps
        ↓
Partner must manually claim fees using PartnerCap
```

**Important:** Manual Claim Required, referral fees are NOT automatically transferred to the partner's wallet.

* Fees accumulate in the `Partner` object's `balances` field (a `Bag` storing multiple coin types)
* Partners must explicitly call `claim_ref_fee` to withdraw accumulated fees
* Each coin type must be claimed separately
* Only the holder of `PartnerCap` can claim the fees

## 2. Swap with Partner (Earn Referral Fees) <a href="#id-1-swap-with-partner-earn-referral-fees" id="id-1-swap-with-partner-earn-referral-fees"></a>

Integrators can earn referral fees by passing their `partner_id` when executing swaps.

#### Example <a href="#using-typescript-sdk" id="using-typescript-sdk"></a>

```typescript
import { CetusDlmmSDK } from '@cetus/dlmm-sdk'

// 1. Get swap quote
const quote = await sdk.Swap.preSwap({
  pool_id: '0x...',
  a2b: true,
  by_amount_in: true,
  amount: '1000000000',
  coin_type_a: '0x2::sui::SUI',
  coin_type_b: '0x...::usdc::USDC',
})

// 2. Build swap transaction with partner
const tx = sdk.Swap.swapPayload({
  quote_obj: quote,
  coin_type_a: '0x2::sui::SUI',
  coin_type_b: '0x...::usdc::USDC',
  by_amount_in: true,
  slippage: 0.01,
  partner: '0x<PARTNER_ID>',  // Your partner object ID
})

// 3. Execute
await client.signAndExecuteTransaction({ transaction: tx, signer: keypair })
```

## 3. Claim Referral Fees (For Partners) <a href="#id-2-claim-referral-fees-for-partners" id="id-2-claim-referral-fees-for-partners"></a>

#### Example <a href="#using-typescript-sdk" id="using-typescript-sdk"></a>

Partners can claim accumulated fees using their `PartnerCap`.

```typescript
// 1. Check accumulated balances
const partner = await sdk.Partner.getPartner(partner_id)
const balances = await sdk.Partner.getPartnerBalance(partner.balances.id)
console.log(balances) // [{ coin_type: '0x2::sui::SUI', balance: '1000000' }, ...]

// 2. Claim fees for specific coin types
const tx = await sdk.Partner.claimRefFeePayload({
  partner_id: '0x<PARTNER_ID>',
  partner_cap_id: '0x<PARTNER_CAP_ID>',  // Optional, auto-fetched if omitted
  fee_coin_types: [
    '0x2::sui::SUI',
    '0x...::usdc::USDC',
  ],
})

// 3. Execute
await client.signAndExecuteTransaction({ transaction: tx, signer: keypair })
```

## Apply for Partner Swap

Interested in Partner Swap? Submit a request from here:<https://4bx69zjogri.typeform.com/to/UUETIX2f>