Add referral fee support (Legacy Swap) + live E2E scripts, docs, and config by MonteCrypto999 · Pull Request #1 · Sendo-labs/plugin-jupiter

MonteCrypto999 · 2025-10-24T17:11:36Z

PR: Optional Referral Fees on Jupiter Legacy Swap

This PR adds optional referral fees on Jupiter Legacy Swap via platformFeeBps and feeAccount,
with clean env-based config, tests, and runnable E2E examples (simulation/signing).

🧩 Features

Referral Fees

Adds platformFeeBps to /quote when REFERRAL_FEE_BPS > 0.
Derives feeAccount as the ATA for the chosen mint from REFERRAL_FEE_RECEIVER.
Modes:
- sol_only: collect fees only if SOL/WSOL is in the pair.
- smart: prefer SOL if available, else input mint.
Respects ExactIn / ExactOut rules and skips fees if constraints aren’t met.

🧠 Code Changes

src/service.ts
- Integrates platformFeeBps in quote and feeAccount in swap.
- Handles mint selection and fee receiver ATA derivation.
src/__tests__/integration.test.ts
- Live-mode tests against Jupiter API (referral on/off, custom mint sample).
src/scripts/e2e-mainnet.ts
- E2E script using .env (can simulate and sign/send).
local-e2e/ (gitignored)
- Local simulator for build/quote/swap, simulate, and sign via Helius RPC.
Docs & Config
- README.md and env.example: updated with clear config and E2E instructions.
- .gitignore: ignores local-e2e and env files.

⚙️ How to Use

1. Setup Environment

Copy .env.example → .env and set:

REFERRAL_FEE_BPS=20
REFERRAL_MODE=sol_only
REFERRAL_FEE_RECEIVER=<fee receiver public key>
TEST_INPUT_MINT=So11111111111111111111111111111111111111112
TEST_OUTPUT_MINT=Dz9mQ9NzkBcCsuGPFJ3r1bS4wgqKMHBPiVuniW8Mbonk
TEST_INPUT_AMOUNT_ATOMIC=5000000      # 0.005 SOL
TEST_SLIPPAGE_BPS=150
# Optional (for simulation/signing)
HELIUS_RPC_URL=<url>
SIGNER_SECRET_KEY=[…]
SEND_TX=0

2. Run E2E Example

npm run build && node dist/scripts/e2e-mainnet.js

3. Local Simulator (ignored, for ops/dev)

Populate local-e2e/.env.local as above, then run:

npm run local:sim

🧩 Notes & Edge Cases

Error “Invalid token account / 0x1789 (6025)”
Usually a route/account issue.
Ensure the fee receiver’s ATA exists for the selected mint (e.g., WSOL in sol_only mode).
If absent, create the ATA or let Jupiter create it idempotently.
Some routes may still fail in simulation—try higher slippage or another route.
No Referral Program needed for Legacy Swap.
(Still required for Trigger API.)

🔗 References

✅ Checklist

Referral fee applied only when REFERRAL_FEE_BPS > 0 and valid feeAccount
feeAccount derived from REFERRAL_FEE_RECEIVER ATA for selected mint
Live integration tests against Jupiter API
E2E script with simulation/signing (HELIUS RPC)
README and .env.example updated
Local-only utilities ignored by git

…e env files

…ample; refine fee receiver ATA checks; ignore local-e2e

Copilot

Pull Request Overview

This PR adds optional referral fee support for Jupiter Legacy Swap, enabling platform fees (0-10%) to be collected on swaps. It introduces environment-based configuration for fee collection modes (sol_only or smart), automatic ATA derivation for fee accounts, and comprehensive testing/documentation.

Key Changes:

Referral fee infrastructure with platformFeeBps (quote) and feeAccount (swap) parameters
Two fee collection modes with automatic mint selection and ATA derivation
Live integration tests, E2E mainnet scripts, and comprehensive documentation

Reviewed Changes

Copilot reviewed 10 out of 13 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`tsup.config.ts`	Added E2E script to build entry points
`src/types.ts`	Added referral config types (`FeeMode`, `ReferralConfig`, `FeeMintSelection`)
`src/service.ts`	Core referral logic: config loading, mint selection, ATA derivation, and integration into quote/swap flows
`src/scripts/e2e-mainnet.ts`	E2E mainnet script with simulation and optional signing/sending
`src/index.ts`	Exported `JupiterService` for direct usage
`src/__tests__/referral.test.ts`	Basic referral config validation tests
`src/__tests__/integration.test.ts`	Live integration tests against Jupiter API
`package.json`	Added dependencies (`dotenv`, `tsx`) and E2E scripts
`env.example`	Environment variable documentation for referral config
`README.md`	Comprehensive documentation on features, setup, and usage

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-10-24T17:15:38Z

src/service.ts

+  let resolveHandle: any = false
+  let rejectHandle: any = false


Initialize resolveHandle and rejectHandle as null instead of false. Using false is misleading since these will be assigned function references, not boolean values.

Suggested change

let resolveHandle: any = false

let rejectHandle: any = false

let resolveHandle: any = null

let rejectHandle: any = null

Copilot · 2025-10-24T17:15:39Z

src/service.ts

+  let resolveHandle: any = false
+  let rejectHandle: any = false


Initialize resolveHandle and rejectHandle as null instead of false. Using false is misleading since these will be assigned function references, not boolean values.

Copilot · 2025-10-24T17:15:39Z

README.md

+## Features
+
+- **Token Swaps**: Execute swaps via Jupiter aggregator
+- **Referral Fees**: Collect platform fees on swaps (0-10%)


The documentation states fees can be 0-10%, but there is no validation in the code to enforce this upper limit. Consider adding validation in loadReferralConfig to ensure feeBps does not exceed 1000 (10%), or update the documentation to reflect that any value is accepted.

Suggested change

- **Referral Fees**: Collect platform fees on swaps (0-10%)

- **Referral Fees**: Collect platform fees on swaps (configurable percentage)

Copilot · 2025-10-24T17:15:39Z

README.md

+- The swap will proceed **without fees**
+- A warning will be logged


The warning states that swaps will proceed without fees if the fee account doesn't exist, but the actual behavior in the code (lines 364-369 in service.ts) logs warnings and proceeds. However, Jupiter may reject the transaction if the fee account is invalid. Consider clarifying that the transaction may fail during execution rather than just proceeding silently without fees.

Suggested change

- The swap will proceed **without fees**

- A warning will be logged

- A warning will be logged

- The swap may fail (Jupiter may reject the transaction if the fee account is invalid or missing)

standujar · 2025-10-26T22:51:23Z

@MonteCrypto999 can you check commit suggestion please ? I'll merge after :)

MonteCrypto999 added 13 commits October 24, 2025 16:10

feat: add referral types (ReferralConfig, FeeMode, FeeMintSelection)

985725a

feat: add referral config loader and mint selection with tests

a2c84b6

refactor: move referral logic into service.ts

3ef6aea

feat: integrate platformFeeBps in getQuote and feeAccount in executeSwap

a477a5e

fix: add type annotations to resolve TypeScript warnings

70deba6

fix: add type annotations to cache functions

840315a

test: add integration tests for referral fees

b27c2f7

docs: add comprehensive README with referral setup instructions

2ddea1d

feat: use REFERRAL_FEE_RECEIVER for feeAccount; update docs and ignor…

becf1dc

…e env files

docs: add backend endpoint recommendation to ensure fee ATA exists

733663e

chore: add env.example with commented referral config

9867eee

chore: add mainnet E2E script and build config

dca92fd

chore: add live E2E with simulation/signing; update README and env.ex…

2a64939

…ample; refine fee receiver ATA checks; ignore local-e2e

standujar requested a review from Copilot October 24, 2025 17:14

Copilot AI reviewed Oct 24, 2025

View reviewed changes

Merge branch '1.x' into referral

0d500dc

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add referral fee support (Legacy Swap) + live E2E scripts, docs, and config#1

Add referral fee support (Legacy Swap) + live E2E scripts, docs, and config#1
MonteCrypto999 wants to merge 14 commits intoSendo-labs:1.xfrom
MonteCrypto999:referral

MonteCrypto999 commented Oct 24, 2025 •

edited by standujar

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Oct 24, 2025

Uh oh!

Copilot AI Oct 24, 2025

Uh oh!

Copilot AI Oct 24, 2025

Uh oh!

Copilot AI Oct 24, 2025

Uh oh!

standujar commented Oct 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	- Referral Fees: Collect platform fees on swaps (0-10%)
	- Referral Fees: Collect platform fees on swaps (configurable percentage)

		- The swap will proceed without fees
		- A warning will be logged

Conversation

MonteCrypto999 commented Oct 24, 2025 • edited by standujar Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR: Optional Referral Fees on Jupiter Legacy Swap

🧩 Features

Referral Fees

🧠 Code Changes

⚙️ How to Use

1. Setup Environment

2. Run E2E Example

3. Local Simulator (ignored, for ops/dev)

🧩 Notes & Edge Cases

🔗 References

✅ Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

standujar commented Oct 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MonteCrypto999 commented Oct 24, 2025 •

edited by standujar

Loading