> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/api-v1/integrator-fees.md).

# Integrator Fees

Integrators can earn on the transfers they route through API v1 by adding their own fee to a quote. The fee is charged **on top of Swapper's fee**, shown as its own line in the quote, and accrues to you; Swapper pays out what you've earned periodically.

## Adding a fee

Set `fee` on [`POST /v1/quote`](https://docs.swapper.finance/api-v1/endpoints/quote.md) as a **decimal fraction** of the input amount — `0.003` is 0.3%:

```bash
curl -X POST "https://swapper.finance/api/v1/quote" \
  -H "x-swapper-api-key: $SWAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromChain": 8453,
    "toChain": 42161,
    "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "toToken": "0x0000000000000000000000000000000000000000",
    "fromAmount": "10000000",
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "fee": 0.003
  }'
```

* **An** [**API key**](https://docs.swapper.finance/api-v1/authentication.md) **is required.** The fee accrues to the integrator that owns the key, so a keyless request with a `fee` is rejected.
* **Maximum 3%** (`0.03`) unless you've agreed a different cap with Swapper. The dashboard's **Fees & earnings** page shows your current maximum.
* The fee must be in **whole basis points** — a multiple of `0.0001` (0.01%), e.g. `0.003` or `0.0025`. Anything finer is rejected with `INVALID_FEE`. Omitting `fee`, or `"fee": 0`, means no integrator fee.
* A quote with a fee is only built on routes where Swapper can match the executed transfer back to that exact quote — that's what guarantees the fee is credited to you. A few pairs can therefore return `NO_ROUTE_FOUND` with a fee but quote fine without one.
* You can set a different fee on every quote.

`fee` applies to `/v1/quote` only — it doesn't affect deposits made through the widget.

## How it's charged

The fee is calculated on `fromAmount`, in the **source token**, and deducted from the amount being swapped — just like Swapper's own fee. The quote you get back already accounts for both: `estimate.toAmount` and `estimate.toAmountMin` are what the user receives **after** fees.

Each fee is listed separately in `estimate.feeCosts`. For 10 USDC with `fee=0.003` (the Swapper fee figure is illustrative; yours depends on your agreement):

```jsonc
"feeCosts": [
  {
    "name": "Swapper fee",
    "description": "Swapper's fee for routing the transfer",
    "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6 /* … */ },
    "amount": "10000",
    "amountUSD": "0.01",
    "percentage": "0.001",
    "included": true
  },
  {
    "name": "Integrator fee",
    "description": "Fee charged by the integrator",
    "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6 /* … */ },
    "amount": "30000",
    "amountUSD": "0.03",
    "percentage": "0.003",
    "included": true
  }
  // network, bridge or relayer costs of the route, when there are any
]
```

`included: true` means the cost is deducted from the swapped amount (and is already reflected in `toAmount`); `included: false` would mean it's paid on top, in the transaction's `value`. `percentage` is a fraction of the input amount. See [Quote → FeeCost](https://docs.swapper.finance/api-v1/endpoints/quote.md#feecost).

## Getting paid

Your fee is **not** sent to you on-chain transaction by transaction. Instead:

1. **At execution**, your fee is collected together with Swapper's fee by Swapper. There is no fee-recipient address in the transaction you sign.
2. **When the transfer completes**, your share is recorded against it (fee percentage × `fromAmount`, in the source token, with its USD value at the time). Transfers that fail or are refunded earn nothing.
3. **Periodically**, Swapper pays out your accrued earnings to the **payout address** set in the [Integrator Dashboard](https://docs.swapper.finance/integrator-dashboard/overview.md): an EVM address (the same address on every EVM chain) and/or a Solana address.

{% hint style="info" %}
**Track every transfer with** [**`GET /v1/status`**](https://docs.swapper.finance/api-v1/endpoints/status.md)**.** Poll it with the source transaction hash after the user broadcasts — you need it anyway to know when the transfer is done, and tracking is what attributes the transfer (and your fee) to your quote. Start tracking within 7 days of the quote: after that the quote is no longer on record and the transfer can't be attributed to you. With your API key, the status of your own transfers also returns `integrator` and a `feeCosts` breakdown of the Swapper and integrator fees charged.
{% endhint %}

Set your payout address before your first payout; owners can change it any time on the dashboard's **Fees & earnings** page.

## Seeing your earnings

The dashboard's **Fees & earnings** page shows:

* your Swapper fee and your maximum integrator fee;
* total earned, already paid, and pending;
* earnings per calendar month (UTC; the current month is still accruing);
* every payout, with its date, amount and transaction hash.

The **Overview** page also shows integrator fees earned over the selected period.

## Errors

Fee problems return `400` with the code `INVALID_FEE`:

| Situation                                 | `message` (abridged)                                                    |
| ----------------------------------------- | ----------------------------------------------------------------------- |
| Not a decimal fraction (e.g. `fee=30bps`) | `fee must be a decimal fraction, e.g. 0.003 for 0.3%`                   |
| Sent without an API key                   | `Charging an integrator fee requires an API key …`                      |
| Above your maximum                        | `fee 0.05 exceeds the maximum of 0.03 (3%) allowed for this integrator` |

See [Errors](https://docs.swapper.finance/api-v1/errors.md) for the envelope.
