Setting Affiliate Fees

​

Overview

Many teams use Skip Go as a source of a revenue for their project by charging fees on swaps. (Charging fees on transfers will be possible in the future!). We refer to these fees throughout the product and documentation as “affiliate fees”

Skip Go’s affiliate fee functionality is simple but flexible — supporting a large variety of bespoke fee collection scenarios:

• Set your desired fee level on each swap (so you can offer lower fees to your most loyal users)
• Set the account that receives the fee on each swap (so you can account for funds easily & separate revenue into different tranches)
• Divide the fee up in customizable proportions among different accounts (so you can create referral/affiliate revenue sharing programs with partners and KOLs)

​

Affiliate Fees Work

1. At this time, affiliate fees can only be collected on swaps. We do not support collecting affiliate fees on routes that only consist of transfers (e.g. CCTP transfers, IBC transfers, etc…) even when there are multi-hop transfers. Please contact us if charging fees on transfers is important to you
2. Affiliate fees are collected on the chain where the last swap takes place: Skip Go aggregates over swap venues (DEXes, orderbooks, liquid staking protocols, etc…) on many different chains. Some routes even contain multiple swaps. For each individual cross-chain or single chain swap where you collect a fee, the fee is applied on the last swap and sent to an address you specify on the chain where the last swap takes place
3. Affiliate fees are collected/denominated in the output token of each swap: For example, if a user swaps OSMO to ATOM, your fee collection address will earn a fee in ATOM
4. Affiliate fees are calculated using the minimum output amount, which is set based on our estimated execution price after accounting for the user’s slippage tolerance : For example, consider an ATOM to OSMO swap where min amount out is 10 uosmo and the cumulative fees are 1000 bps or 10%. If the swap successfully executes, the affiliate fee will be 1 uosmo. It will be 1 uosmo regardless of whether the user actually gets 10, 11, or 12 uosmo out of the swap

​

How to Use Affiliate Fees

There are two simple steps involved in using affiliate fees:

1. Incorporate the fee into the quote : You need to request the route & quote with the total fee amount (in basis points) you will collect, so Skip Go can deduct this automatically from the estimated amount_out it returns to the user. This ensures the quote you show the user already accounts for the fee, and they won’t receive any unexpectedly low amount.
2. Set the address(es) to receive the fee: You also need to tell Skip Go the exact address(es) to send the fee revenue to. You need to pass a list of addresses and specify a fee amount (in basis points) for each to collect.

​

Incorporating Fees with /route and /msgs

When executing swaps using the /route and /msgs endpoints, you can incorporate affiliate fees by specifying the total fee during the /route request and detailing the fee recipients during the /msgs request. Below is a comprehensive guide on how to correctly implement this.

1. Set Total Fee in /route Request

In your /route request, include the cumulative_affiliate_fee_bps parameter to specify the total fee you wish to collect, expressed in basis points (bps).

• Definition: 1% fee = 100 basis points.
• Example: To collect a 0.75% fee, set cumulative_affiliate_fee_bps to "75".

{
  "cumulative_affiliate_fee_bps": "75",
  // ...other parameters
}

2. Identify Swap Chain

After the /route request, use the swap_venue.chain_id field in the response to determine which chain the swap will occur on. You’ll need this information to provide valid recipient addresses in the next step.

3. Specify Fee Recipients in /msgs Request

In your /msgs request, define the chainIdsToAffiliates object to allocate fees to specific addresses on the relevant chains.

Structure:

{
  "chainIdsToAffiliates": {
    "<chain_id>": {
      "affiliates": [
        {
          "basisPointsFee": "<fee_in_bps>",
          "address": "<recipient_address>"
        },
        // ...additional affiliates
      ]
    },
    // ...additional chains
  }
}

Example:

{
  "chainIdsToAffiliates": {
    "noble-1": {
      "affiliates": [
        {
          "basisPointsFee": "100", // 1% fee
          "address": "noble1..."
        },
        {
          "basisPointsFee": "100", // 1% fee
          "address": "noble2..."
        }
      ]
    },
    "osmosis-1": {
      "affiliates": [
        {
          "basisPointsFee": "200", // 2% fee
          "address": "osmo1..."
        }
      ]
    }
  }
}

Notes:

• The sum of basisPointsFee values across all affiliates on the swap chain must equal the cumulative_affiliate_fee_bps set in the /route request.
• All addresses must be valid on the chain where the swap will take place. Invalid addresses will result in a 400 error.
• If using @skip-go/client, remember to use camelCase (e.g., basisPointsFee) in the config.

​

Incorporating Fees with /msgs_direct

When using the /msgs_direct endpoint, you need to specify affiliate fees for every possible chain the swap might occur on since the swap chain is determined during the request.

​

Steps:

1. Define chainIdsToAffiliates for All Potential Swap Chains

   • Use the chainIdsToAffiliates object to map each potential chain_id to its corresponding affiliates.
   • For each chain_id, provide a list of affiliates, each with:
     • basisPointsFee: The fee amount in basis points (bps).
     • address: The recipient’s address on that chain.

2. Include Entries for Every Possible Chain

   • Retrieve all potential swap chains by querying the /v2/fungible/swap_venues endpoint.
   • Include an entry in chainIdsToAffiliates for each chain_id from the list.

3. Ensure Fee Consistency Across Chains

   • The sum of basisPointsFee values for affiliates on each chain must be equal across all chains.
   • This consistency is necessary because the fee amount used in the swap must be the same, regardless of which chain the swap occurs on.
   • If the fee sums differ between chains, the request will return an error.

​

Example Request:

{
  "chainIdsToAffiliates": {
    "noble-1": {
      "affiliates": [
        {
          "basisPointsFee": "100", // 1% fee
          "address": "noble1..."
        },
        {
          "basisPointsFee": "100", // 1% fee
          "address": "noble2..."
        }
      ]
    },
    "osmosis-1": {
      "affiliates": [
        {
          "basisPointsFee": "200", // 2% fee
          "address": "osmo1..."
        }
      ]
    },
    // Include entries for all other potential chains
  },
  // ...other parameters
}

Notes:

• In the example above, the total fee for each chain is 200 bps (2%).
• Ensure that all addresses are valid on their respective chains.