> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cosmos.network/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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"`.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "cumulative_affiliate_fee_bps": "75",
  // ...other parameters
}
```

<Info>
  If you're using `@skip-go/client`, use camelCase: `cumulativeAffiliateFeeBps`.
</Info>

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:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "chainIdsToAffiliates": {
    "<chain_id>": {
      "affiliates": [
        {
          "basisPointsFee": "<fee_in_bps>",
          "address": "<recipient_address>"
        },
        // ...additional affiliates
      ]
    },
    // ...additional chains
  }
}
```

##### Example:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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`

<Warning>
  We recommend using `/route` and `/msgs` over `/msgs_direct` due to the added complexity when handling fees with `/msgs_direct`.
</Warning>

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:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "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.

<Info>
  **Have questions or feedback? Help us get better!**

  Join [our Discord](https://discord.com/invite/interchain) and select the "Skip Go Developer" role to share your questions and feedback.
</Info>