feat: implement Jupiter referral system with SSE compatibility

[rxdha1]

🎯 Jupiter Referral System Implementation

This PR implements a robust Jupiter referral system that allows developers to earn 2.51% fees from swaps while maintaining full compatibility with the existing SSE token infrastructure.

🐛 Problem Solved

Resolves the Jupiter v6 API conflict identified in commit 81f3f24 where using both platformFeeBps and referralAccount/referralFeeBps simultaneously caused fees to be ignored.

✨ Solution

• Uses Jupiter's recommended platformFeeBps approach in quote API
• Removes conflicting referral parameters from swap API
• Maintains separate ATA creation fee system for SSE tokens
• Preserves all existing functionality

🚀 Features

• ✅ 2.51% referral fee collection using environment variable configuration
• ✅ Multi-wallet support (external wallets + Privy embedded wallets)
• ✅ Enhanced error handling with detailed SOL balance messages
• ✅ Complete SSE compatibility - both fee systems work together
• ✅ Comprehensive documentation with setup guides and troubleshooting

📁 Files Changed

• Core Implementation: src/components/trade/hooks/jupiter/use-jupiter-swap.ts
• Backend Services: src/services/jupiter.ts, src/services/swap.ts
• Type Definitions: src/types/jupiter-service.ts
• API Routes: src/app/api/jupiter/swap/route.ts
• Documentation: README.md, JUPITER_REFERRAL_SETUP.md
• Configuration: .env.example

🧪 Testing

• ✅ Build successful (npm run build)
• ✅ TypeScript compilation clean
• ✅ No breaking changes to existing functionality
• ✅ SSE token infrastructure preserved
• ✅ All linting checks passed

💡 Technical Details

Dual Fee System Architecture:

1. Referral Fees: 2.51% collected via platformFeeBps in Jupiter quote API
2. ATA Creation Fees: Infrastructure costs paid by JUPITER_CONFIG.FEE_WALLET

Both systems operate independently without conflicts, ensuring reliable fee collection while maintaining full SSE token support.

📚 Documentation

Complete setup instructions and technical details available in JUPITER_REFERRAL_SETUP.md

🙏 Attribution

This implementation resolves the issue identified by @rxdha1 and the Bonk Computer team, refined for the official Solana Starter Kit.

---

Ready for review! 🚀

[vercel]

@rxdha1 is attempting to deploy a commit to the Primitives Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
solana-starter-kit	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 8, 2025 6:22pm