Fee Configuration

Overview

Kuest allows you to configure platform trading fees, affiliate commission sharing, and fee recipient addresses. Fees are charged on-chain during trade execution and can be customized per deployment.

Trading Fees

Trading fees are charged as a percentage of each trade and split between the platform and affiliates.

Fee Structure

Overview
Smart Contract

Total Trading Fee = Base Fee + Platform Fee

Exchange Base Fee: On-chain minimum (e.g., 0.20%)
Platform Fee: Your custom addition (configurable)
Total Fee: What users pay per trade

Distribution:

Platform Share: Percentage kept by platform
Affiliate Share: Percentage paid to referrers

Example with 2% total fee:

User trades $100
Trading fee: $2.00 (2%)
Affiliate gets: $1.00 (50% of fee)
Platform keeps: $1.00 (50% of fee)

The on-chain exchange contract enforces a minimum base fee:

// Exchange contract
function exchangeBaseFeeRate() public view returns (uint256)

This base fee is read from the contract and enforced as the minimum:

CTF Exchange: CTF_EXCHANGE_ADDRESS
Neg Risk Exchange: NEG_RISK_CTF_EXCHANGE_ADDRESS

Both contracts are queried and the maximum base fee is used.

Configuring Trading Fees

Admin Panel
Fee Calculation

Navigate to Admin → Fees
Find Trading Fees section
Set Trading fee (%) (minimum enforced)
Set Affiliate share (%) (0-100%)
Click Save settings

The system will display the minimum fee based on the on-chain base fee rate. You cannot set a fee below this minimum.

Implementation in src/lib/affiliate-data.ts:

// Calculate trading fee
export function calculateTradingFee(
  amount: number,
  feeDecimal: number
): number {
  return amount * feeDecimal
}

// Calculate affiliate commission
export function calculateAffiliateCommission(
  feeAmount: number,
  affiliateShareDecimal: number
): number {
  return feeAmount * affiliateShareDecimal
}

// Calculate platform share
export function calculatePlatformShare(
  feeAmount: number,
  platformShareDecimal: number
): number {
  return feeAmount * platformShareDecimal
}

Fee Validation

The system validates fees to ensure they meet on-chain requirements:

src/app/[locale]/admin/affiliate/_actions/update-affiliate-settings.ts

const tradeFeeBps = Math.round(parsed.data.trade_fee_percent * 100)
const exchangeBaseFeeBps = await fetchMaxExchangeBaseFeeRate()

if (exchangeBaseFeeBps !== null && tradeFeeBps < exchangeBaseFeeBps) {
  return { 
    error: `Trading fee must be at least ${(exchangeBaseFeeBps / 100).toFixed(2)}%.` 
  }
}

Attempting to set a trading fee below the on-chain base fee will result in an error. The minimum is typically 0.20% but can vary by network.

Fee Recipient Wallet

Configure the Polygon wallet address that receives platform trading fees.

Configuration
Validation

Navigate to Admin → General
Scroll to Market and fee settings
Enter your Polygon wallet address in Fee recipient wallet
Format: 0xabc123... (42-character hex address)
Click Save settings

If left empty, the zero address (0x0000...0000) is used and fees are effectively burned.

The system validates wallet addresses:

const WALLET_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/

function normalizeFeeRecipientWalletAddress(
  value: string | null | undefined,
  sourceLabel: string
) {
  const normalized = value?.trim() ?? ''
  
  if (!normalized) {
    return { value: ZERO_ADDRESS, error: null }
  }
  
  if (!WALLET_ADDRESS_PATTERN.test(normalized)) {
    return { 
      value: null, 
      error: `${sourceLabel} must be a valid wallet address.` 
    }
  }
  
  return { value: normalized as `0x${string}`, error: null }
}

Important: Ensure you control this wallet address. Once fees are sent to this address, they cannot be redirected without updating the settings.

Affiliate Configuration

Control how much of the trading fee is shared with affiliates:

Value: 0-100% of the trading fee
Location: Admin → Fees → Affiliate share (%)
Default: Configurable

Example:

Trading fee: 2%
Affiliate share: 50%
On a $100 trade:
- Total fee: $2.00
- Affiliate receives: $1.00 (50% of$ 2.00)
- Platform receives: $1.00 (remaining 50%)

Referral System

The affiliate system tracks referrals on-chain via the exchange contract:

src/lib/exchange.ts

export async function fetchReferralLocked(
  exchange: `0x${string}`,
  maker: `0x${string}`,
): Promise<boolean | null> {
  const result = await getExchangeClient().readContract({
    address: exchange,
    abi: exchangeReferralAbi,
    functionName: 'referrals',
    args: [maker],
  })
  
  // Returns: [referrer, affiliate, affiliatePercentage, locked]
  return result[3] // locked status
}

Fee Data API

Fee totals are tracked and can be queried:

src/lib/data-api/fees.ts

export async function fetchFeeReceiverTotals({
  endpoint,
  address,
  exchange,
  tokenId,
  limit = 100,
  offset = 0,
}: FeeReceiverTotalsParams): Promise<FeeReceiverTotal[]>

export function sumFeeTotals(totals: FeeReceiverTotal[]): bigint

export function sumFeeVolumes(totals: FeeReceiverTotal[]): bigint

Market Creators

Control which wallet addresses can create markets that appear on your fork.

Configuration
Behavior

Navigate to Admin → General
Find Market and fee settings
Enter wallet addresses in Allowed market creator wallets
Format: One address per line
Example:
```
0xabc123...
0xdef456...
0x789abc...
```
Click Save settings

Market creator filtering is useful for:

Private prediction markets
Whitelabel deployments
Testing and development
Niche market categories

Settings Storage

Fee-related settings are stored in the database:

Group	Key	Description	Example
`affiliate`	`trade_fee_bps`	Trading fee in basis points	`200` (2%)
`affiliate`	`affiliate_share_bps`	Affiliate share in basis points	`5000` (50%)
`general`	`fee_recipient_wallet`	Platform fee wallet address	`0xabc...`
`general`	`market_creators`	Allowed creator addresses (newline-separated)	`0xabc...\n0xdef...`

Basis points (bps) are 1/100th of a percent. 100 bps = 1%. This is used internally for precision.

Accessing Fee Settings

import { fetchAffiliateSettingsFromAPI } from '@/lib/affiliate-data'

const result = await fetchAffiliateSettingsFromAPI()

if (result.success) {
  const settings = result.data
  console.log(settings.tradeFeePercent)        // "2.00"
  console.log(settings.affiliateSharePercent)  // "50.00"
  console.log(settings.platformSharePercent)   // "50.00"
  console.log(settings.tradeFeeDecimal)        // 0.02
}

Fee Calculation Example

Let’s walk through a complete fee calculation:

User places trade

Trade amount: $500
Trading fee: 2% (0.02)
Affiliate share: 40%

Calculate total fee

const tradingFee = 500 * 0.02 = $10.00

Split fee

const affiliateCommission = 10.00 * 0.40 = $4.00
const platformShare = 10.00 * 0.60 = $6.00

Distribute on-chain

$4.00 → Affiliate address
$6.00 → Platform fee recipient wallet
User receives: $500 worth of shares (minus fees)

Best Practices

Setting Competitive Fees

Research competitor fee structures
Balance revenue with user acquisition
Consider volume-based fee tiers (requires custom implementation)
Monitor fee impact on trading volume
Test different fee levels with A/B testing

Affiliate Program

Set competitive affiliate shares (30-50% is common)
Higher shares attract more affiliates
Monitor affiliate fraud and abuse
Track affiliate performance via admin panel
Provide marketing materials for affiliates

Fee Recipient Security

Use a multi-sig wallet for large deployments
Regularly withdraw fees to cold storage
Monitor fee recipient balance
Set up alerts for large fee accumulations
Keep backup of fee recipient private key (securely)

Market Creator Management

Start with a small list of trusted creators
Expand gradually as you verify quality
Remove creators who violate terms
Consider automated creator verification
Document creator guidelines clearly

Troubleshooting

Fee below minimum error

Problem: Cannot save trading fee below on-chain minimumSolution:

Check the current on-chain base fee rate
Set your fee at or above this minimum
Contact blockchain team if minimum seems incorrect
Verify you’re on the correct network (Polygon, testnet, etc.)

Fees not received

Problem: Trading fees not appearing in recipient walletSolution:

Verify fee recipient wallet address is correct
Check if address is the zero address (fees are burned)
Confirm trades are being executed successfully
Check Polygonscan for fee transactions
Ensure sufficient gas for fee transfers

Invalid wallet address

Problem: Error when saving wallet addressSolution:

Ensure address starts with 0x
Verify address is exactly 42 characters
Check for typos or invalid characters
Copy address directly from wallet app
Test address on Polygonscan

Market creators not working

Problem: Markets from specified creators not showing upSolution:

Verify addresses are formatted correctly (one per line)
Check that creators have actually created markets
Ensure addresses match exactly (case-insensitive but exact)
Look for whitespace or hidden characters
Clear cache and restart server

Admin Panel

Access fee configuration interface

Affiliate System

Learn about affiliate tracking

Smart Contracts

Understand on-chain fee mechanisms

Branding

Configure other platform settings

Get Started

Deployment

Configuration

Features

Customization

Operations

Overview

Trading Fees

Fee Structure

Configuring Trading Fees

Fee Validation

Fee Recipient Wallet

Affiliate Configuration

Referral System

Fee Data API

Market Creators

Settings Storage

Accessing Fee Settings

Fee Calculation Example

Best Practices

Troubleshooting

Admin Panel

Affiliate System

Smart Contracts

Branding

Build docs developers (and LLMs) love

Get Started

Deployment

Configuration

Features

Customization

Operations

​Overview

​Trading Fees

​Fee Structure

​Configuring Trading Fees

​Fee Validation

​Fee Recipient Wallet

​Affiliate Configuration

​Affiliate Share

​Referral System

​Fee Data API

​Market Creators

​Settings Storage

​Accessing Fee Settings

​Fee Calculation Example

​Best Practices

​Troubleshooting

​Related Configuration

Admin Panel

Affiliate System

Smart Contracts

Branding

Build docs developers (and LLMs) love

Overview

Trading Fees

Fee Structure

Configuring Trading Fees

Fee Validation

Fee Recipient Wallet

Affiliate Configuration

Affiliate Share

Referral System

Fee Data API

Market Creators

Settings Storage

Accessing Fee Settings

Fee Calculation Example

Best Practices

Troubleshooting

Related Configuration