You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: "This page covers how integrators can earn affiliate fees on swaps."
4
+
---
5
+
6
+
### Overview
7
+
8
+
Many teams use Skip API 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"
9
+
10
+
Skip API's affiliate fee functionality is simple but flexible -- supporting a large variety of bespoke fee collection scenarios:
11
+
12
+
* Set your desired fee level on each swap (so you can offer lower fees to your most loyal users)
13
+
* Set the account that receives the fee on each swap (so you can account for funds easily & separate revenue into different tranches)
14
+
* Divide the fee up in customizable proportions among different accounts (so you can create referral/affiliate revenue sharing programs with partners and KOLs)
15
+
16
+
### Affiliate Fees Work
17
+
18
+
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
19
+
2.**Affiliate fees are collected on the chain where the last swap takes place**: Skip API 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.
20
+
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.
21
+
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.
22
+
23
+
### How to Use Affiliate Fees
24
+
25
+
There are two simple steps involved in using affiliate fees:
26
+
27
+
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 API 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 your fee, and they won't receive any unexpectedly low amount.
28
+
2.**Set the address(es) to receive the fee**: You also need to tell Skip API 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.
29
+
30
+
#### Fees with /route and /msgs
31
+
32
+
When using `/route` and `/msgs`, you incorporate the fee into the quote when you call `/route` then separately set the addresses to receive the fee when calling `/msgs`:
33
+
34
+
1. In the `/route` request, set `cumulative_affiliate_fee_bps` to the integer corresponding to the number of basis points you will collect in your fee
35
+
1. For example, set `cumulative_affiliate_fee_bps` to 100 if you would like to collect a 1% fee on the swap
36
+
2. Use the `swap_venue.chain_id` field in the response of `/route` to determine which chain the swap takes place on. You'll need to use addresses on this chain later when setting the addresses to receive the fee
37
+
3. In the `/msgs` request, set `affiliates` to a list of `Affiliate` objects, where each corresponds to a fee-receiving address on the chain where the swap will take place (`address` gives the address, and `basis_point_fee` gives the fee amount).
38
+
1. The sum of `basis_point_fee` values across all affiliates should equal `cumulative_affiliate_fee_bps`
39
+
2. If you pass any addresses that are not valid on the chain where the swap will take place, the request will return a `400` error
40
+
41
+
#### Fees with /msgs\_direct
42
+
43
+
44
+
<Info>
45
+
**/route and /msgs recommended over /msgs\_direct**
46
+
47
+
We generally recommend integrators use `/route` and `/msgs` rather than `/msgs_direct`. The complexity you must manage below is part of the reason for this recommendation.
48
+
</Info>
49
+
50
+
1. Set `affiliates`to a list of\``Affiliate` objects, where each corresponds to an address that will receive a portion of the fees if the swap takes place on the chain where that address is located. ( Within an `Affiliate` object, `address` gives the address, and `basis_point_fee` gives the fee amount).
51
+
1. You should pass a set of affiliate addresses for every chain where the swap _might_ take place. (You can get this list by querying the `/v2/fungible/swap_venues` endpoint for the list of all `swap_venues` and grabbing the `chain_id` for each). This is required because `/msgs_direct` is determining the route, so we don't know which chain the swap will take place on when calling it.
52
+
2. You should ensure that the sums of `basis_point_fee` for the sets of addresses you pass for each chain are equivalent. (For example, if you pass osmo1... addresses and neutron1... addresses, the sum of the `basis_point_fee` values for the osmo1... addresses must be the same as the sum for the neutron1... addresses.) You will receive an error if your fee sums are non-equivalent. (The error is necessary because we don't know which fee amount to simulate with.)
53
+
54
+
<Tip>
55
+
**Want to help us get better? Have questions or feedback?**
56
+
57
+
You can reach us easily by joining [our Discord](https://skip.money/discord) and grabbing the "Skip API Developer" role.
This parameter indicates whether you want to allow the API to return and execute a route even when our routing engine forecasts low or unknown execution quality:
10
10
11
-
*`allow_unsafe=false` (default): The API will throw an error instead of returning a route when the routing engine forecasts bad execution quality (i.e. \> 10% `price_impact` or difference between USD value in and out) or when execution quality can't be determined.
12
-
*`allow_unsafe=true`: The API will return a route for a trade even when the routing engine forecasts bad execution quality (i.e. \> 10% `price_impact` or difference between USD value in and out) or when execution quality can't be determined. In these cases, the API appends a `warning` to the response in a `warning` field
11
+
*`allow_unsafe=false` (default): The API will throw an error instead of returning a route when the routing engine forecasts bad execution quality (i.e. > 10% `price_impact` or difference between USD value in and out) or when execution quality can't be determined.
12
+
*`allow_unsafe=true`: The API will return a route for a trade even when the routing engine forecasts bad execution quality (i.e. > 10% `price_impact` or difference between USD value in and out) or when execution quality can't be determined. In these cases, the API appends a `warning` to the response in a `warning` field
13
13
14
-
<Note>
15
14
16
-
**Make sure you understand execution/quote quality measurements first**
15
+
<Info>
16
+
**Make sure you understand execution/quote quality measurements first**
17
+
18
+
Before reading this doc, you should read our documentation on quote quality: [ Understanding Quote Quality Metrics](/understanding-quote-quality-metrics). This provides basic background information about the different ways the Skip API measures whether a route will likely give a user a bad execution price, namely the difference between the USD value of the input and the output & on-chain price impact.
19
+
</Info>
17
20
18
-
Before reading this doc, you should read our documentation on quote quality: [ Understanding Quote Quality Metrics](/docs/understanding-quote-quality-metrics). This provides basic background information about the different ways the API measures whether a route will likely give a user a bad execution price, namely the difference between the USD value of the input and the output & on-chain price impact.
19
-
</Note>
20
21
## `allow_unsafe=false` Behavior
21
22
22
-
When `allow_unsafe=false`, the endpoint throws an error when execution quality is low (as measured by price impact or estimated USD value lost) or when execution quality can't be determined (i.e. neither of these measurements are available).
23
+
When `allow_unsafe=false`, the endpoint throws an error when execution quality is poor (as measured by price impact or estimated USD value lost) or when execution quality can't be determined (i.e. neither of these measurements are available).
23
24
24
-
Below, we provide examples of each case where the API returns an error when`allow_unsafe=false`:
25
+
In particular, if `allow_unsafe=false`, `/route` and `/msgs_direct` return errors when:
25
26
26
27
*`price_impact > .10`(the swap will move the on-chain price by more than 10%)
27
28
*`(usd_amount_in-usd_amount_out)/usd_amount_in)>.10` (greater than 10% of the value of the input is lost)
28
29
* Neither of the above metrics can be computed
29
30
31
+
Below, we provide examples of the responses in each these cases.
32
+
30
33
The price impact is greater than 10% (`BAD_PRICE_ERROR`):
31
34
32
-
```JSON
33
-
{
35
+
*```{
34
36
"code": 3,
35
37
"message": "swap execution price in route deviates too far from market price. expected price impact: 98.6915%",
36
38
"details": [
@@ -46,8 +48,7 @@ The price impact is greater than 10% (`BAD_PRICE_ERROR`):
46
48
47
49
The user loses more than 10% of their USD value (`BAD_PRICE_ERROR`):
48
50
49
-
```json
50
-
{
51
+
*```{
51
52
"code": 3,
52
53
"message": "difference in usd value of route input and output is too large. input usd value: 1000 output usd value: 600",
53
54
"details": [
@@ -63,8 +64,8 @@ The user loses more than 10% of their USD value (`BAD_PRICE_ERROR`):
63
64
64
65
The `price_impact` and the estimated USD value difference cannot be calculated (`LOW_INFO_ERROR`)
65
66
66
-
```json
67
-
{
67
+
* JSON
68
+
```{
68
69
"code": 3,
69
70
"message": "unable to determine route safety",
70
71
"details": [
@@ -80,19 +81,20 @@ The `price_impact` and the estimated USD value difference cannot be calculated (
80
81
81
82
## `allow_unsafe=true` Behavior
82
83
83
-
When `allow_unsafe=true`, the endpoints will still return routes even when the routing engine forecasts will have bad execution price (measured by price\_impact or estimated USD lost), but they will have a `warning` field appended to them.
84
+
When `allow_unsafe=true`, the endpoints will still return routes even when the routing engine forecasts will have unknown or poor execution quality (measured by price\_impact or estimated USD lost), but they will have a `warning` field appended to them.
84
85
85
86
The `warning` field is populated exactly when the endpoints would return an error if `allow_unsafe` were `false`, namely:
86
87
87
88
*`price_impact > .10`(the swap will move the on-chain price by more than 10%)
88
89
*`(usd_amount_in-usd_amount_out)/usd_amount_in)>.10` (greater than 10% of the value of the input is lost)
89
90
* Neither of the above metrics can be computed
90
91
91
-
Below, we provide examples of each case where the API returns a warning
92
+
Below, we provide examples of the responses in each these cases.
92
93
93
94
The price impact is greater than 10% (`BAD_PRICE_WARNING`):
94
95
95
-
```JSON
96
+
*
97
+
```JSON JSON
96
98
"warning": {
97
99
"type": "BAD_PRICE_WARNING",
98
100
"message": "swap execution price in route deviates too far from market price. expected price impact: 98.6826%"
@@ -101,17 +103,15 @@ The price impact is greater than 10% (`BAD_PRICE_WARNING`):
101
103
102
104
More than 10% of the USD value of the input is lost in the swap (`BAD_PRICE_WARNING`):
103
105
104
-
```
105
-
"warning": {
106
+
*```"warning": {
106
107
"type": "BAD_PRICE_WARNING",
107
108
"message": "difference in usd value of route input and output is too large. input usd value: 1000 output usd value: 600"
108
109
}
109
110
```
110
111
111
112
The `price_impact` and the estimated USD value difference cannot be calculated (`LOW_INFO_ERROR`)
112
113
113
-
```
114
-
"warning": {
114
+
*```"warning": {
115
115
"type": "LOW_INFO_WARNING",
116
116
"message": "unable to determine route safety"
117
117
}
@@ -121,11 +121,10 @@ The `price_impact` and the estimated USD value difference cannot be calculated (
121
121
122
122
**Above all else, we recommend setting `allow_unsafe=false`**
123
123
124
-
In addition, we recommend reading our documentation around [safe API integrations](/docs/safe-swapping-how-to-protect-users-from-harming-themselves) to learn about UX/UI practices that can further help prevent users from performing trades they'll immediately regret.
125
-
126
-
<Check>
127
-
128
-
Want to help us get better? Have questions or feedback?
124
+
In addition, we recommend reading our documentation around [safe API integrations](/safe-swapping-how-to-protect-users-from-harming-themselves) to learn about UX/UI practices that can further help prevent users from performing trades they'll immediately regret.
129
125
130
-
You can reach us easily at [email protected] or in [our developer support channel on TG](https://t.me/+3y5biSyZRPIwZWIx)
131
-
</Check>
126
+
<Check>
127
+
**Want to help us get better? Have questions or feedback?**
128
+
129
+
You can reach us easily by joining [our Discord](https://skip.money/discord) and grabbing the "Skip API Developer" role.
0 commit comments