Skip to main content

Add Fees To Swap

The Referral Program is an open source program by Jupiter to provide referral fees for integrators who are integrating Jupiter Swap and Jupiter Limit Order. You can check out the code here to gain a better understanding of how it works.

Use Case​

By default, there are zero protocol fees on Jupiter Swap. Integrators have the option to introduce a platform fee denoted in basis points, e.g. 20 bps for 0.2% of the token input or output. If a platform fee is set by an integrator, Jupiter will take 2.5% of the platform fee charged by the integrators.

note

If you use our APIs heavily and consider taking fees, please reach out to us.

Important Notes​

  • This is useful if you are an end user application such as wallets, payments, merchants, etc.
  • The Jupiter Swap project account for the Referral Program is 45ruCyfdRkWpRNGEqWzjCiXRHkZs8WXCLQ67Pnpye7Hp.
  • The referralTokenAccount can either be:
    • Input mint or the output mint on the swap for ExactIn.
    • Input mint ONLY on the swap for ExactOut.
  • You can use the Dashboard, SDK or API to set up the referralAccount and referralTokenAccount in this guide.
  • It does not support Token2022 tokens.

Let’s Get Started​

1. Set up​

You will need to complete the prerequisites and understanding of Get Started and Get Quote and Swap guide as this is reliant on the Swap API.

Obtain referralAccount and referralTokenAccount

There are 3 ways you can set up a referral account.

  1. Use our referral dashboard to create them. After creating, remember to find your Referral Key on the page and the associated token accounts.
  2. Use our SDK to create them. You can use the example scripts to create.
  3. Use our API to create them. You can use this API reference to create.

Obtain mintAccount

As for the mint account, assuming you have an interface where a user swaps, you will know up front what are the input or output mints. For the sake of example, we will use a hardcoded mint public key.

const referralAccount = new Publickey('ReplaceWithPubkey');
const mintAccount = new Publickey('So11111111111111111111111111111111111111112');

3. Set your referral fee in Quote​

Setting your referral fee is simple, just add platformFeeBps parameter to the /quote endpoint.

In this example, we set platformFeeBps to 20 which equates to 0.2%.

const quoteResponse = await (
    await fetch(
        'https://api.jup.ag/quote/v1?inputMint=So11111111111111111111111111111111111111112&outputMint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&amount=100000&slippageBps=50&restrictIntermediateTokens=true&platformFeeBps=20'
    )
  ).json();
  
console.log(JSON.stringify(quoteResponse, null, 2));

3. Set your referral token account in Swap​

In order to refer and receive fees from all types of tokens, you will need to have already initialize referralTokenAccounts (owned by your referralAccount) for the mint in the swap. By calling the Swap API with the parameter feeAccount, which is the referralTokenAccount, you will receive the serialized swap transaction that will set a fee to be taken from the referred and sent to that token account.

In this code block, we will be using the SDK to try to find the referralTokenAccount based on our previously defined referralAccount and mintAccount.

  • If the token account is found, it will proceed to the Swap API.
  • If the token account is not found, it will send a transaction to the network to attempt to initialize one for the mint. Do note that transactions may fail due to various reasons like Priority Fees.
import { ReferralProvider } from "@jup-ag/referral-sdk";

const { tx, referralTokenAccountPubKey } = await provider.initializeReferralTokenAccount({
    payerPubKey: wallet.publicKey,
    referralAccountPubKey: referralAccount,
    mint: mintAccount,
});

const referralTokenAccount = await connection.getAccountInfo(referralTokenAccountPubKey);

// Attempt to initialize a token account
if (!referralTokenAccount) {
    const signature = await sendAndConfirmTransaction(connection, tx, [wallet]);
    console.log({ signature, referralTokenAccountPubKey: referralTokenAccountPubKey.toBase58() });

// Since initialized, it will carry on
} else {
    console.log(`referralTokenAccount ${referralTokenAccountPubKey.toBase58()} for mint ${mintAccount.toBase58()} already exists`);
};

const feeAccount = referralTokenAccountPubKey;
console.log(feeAccount);

However, if you are confident that the referralTokenAccount for specific mints have been created, you can use this method to get it. Do note that, even if the token account is not intialized, it will return a pubkey as it is a Program Derived Address. Read more here.

const [feeAccount] = PublicKey.findProgramAddressSync(
    [
        Buffer.from("referral_ata"), // A string that signifies the account type, here "referral_ata."
        referralAccount.toBuffer(), //  The public key of the referral account converted into a buffer.
        mintAccount.toBuffer(), // The mint public key, converted into a buffer.
    ],
    new PublicKey("REFER4ZgmyYx9c6He5XfaTMiGfdLwRnkV4RPp9t9iF3") // The public key of the Referral Program
);

Using the above, we will now know the feeAccount to be passed in as the parameter in Swap API. You can refer to the Build Swap Transaction guide to add any parameters where necessary to help transaction sending, etc.

const swapResponse = await (
    await fetch('https://api.jup.ag/swap/v1', {
        method: 'POST',
        headers: {
        'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            quoteResponse,
            userPublicKey: wallet.publicKey.toBase58(), // Pass in actual referred user in production
            feeAccount: feeAccount,
        })
    })
).json();

console.log(swapResponse);

4. Sign and send transaction​

Finally, the referred can sign the transaction and it can be submitted to the network to be executed. You can refer to the Send Swap Transaction guide to complete this step.

Additional Resources​

Now you have set up and added fees to the swaps you provide to the end users. The fees are collected and stored in the referralTokenAccount. In order to claim them, you can use the SDK or API to claim them all at once.