Setting Affiliate Fees
This page covers how integrators can earn affiliate fees on swaps.
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
- 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
- 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
- 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
- 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:
- 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. - 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.
- 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"
.
If you’re using @skip-go/client
, use camelCase: cumulativeAffiliateFeeBps
.
- 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.
- 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:
Example:
Notes:
- The sum of
basisPointsFee
values across all affiliates on the swap chain must equal thecumulative_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
We recommend using /route
and /msgs
over /msgs_direct
due to the added complexity when handling 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:
-
Define
chainIdsToAffiliates
for All Potential Swap Chains- Use the
chainIdsToAffiliates
object to map each potentialchain_id
to its corresponding affiliates. - For each
chain_id
, provide a list ofaffiliates
, each with:basisPointsFee
: The fee amount in basis points (bps).address
: The recipient’s address on that chain.
- Use the
-
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 eachchain_id
from the list.
- Retrieve all potential swap chains by querying the
-
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.
- The sum of
Example Request:
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.
Have questions or feedback? Help us get better!
Join our Discord and select the “Skip Go Developer” role to share your questions and feedback.