FeeForwarder

LI.FI has upgraded its fee handling mechanism on supported EVM chains, migrating from the FeeCollector contract to a new FeeForwarder contract. This page explains what changed, what it means for your integration, and what—if anything—you need to do.

Why this change?

The previous FeeCollector model required fees to accumulate in a contract and be manually withdrawn later. This added operational overhead and delayed payouts to fee recipients. With FeeForwarder, fees are forwarded immediately to the configured recipient wallet(s) at transaction execution time. No manual withdrawal step is required. The contract also supports forwarding partner-specified fees to several recipients in one transaction—for example an integrator fee plus an additional reseller or intermediary fee.

What changes for partners?

Immediate fee forwarding

On chains where FeeForwarder is deployed, transactions call the new contract and fees are distributed automatically at execution time. No action is required from partners.

Multi-party fee distribution

By default, the integrator fee you configure is forwarded to your configured fee wallet. You can add other recipient-specific fees with the distributionFees request parameter described below. This is useful when more than one partner needs to be paid in the same transaction. Each distributionFees entry is an additional percentage of fromAmount. It is not a share of the integrator’s fee. On EVM and Tron, FeeForwarder settles those amounts atomically in the same on-chain transaction. On Solana, each receiver is paid with its own transfer instruction; there is no FeeForwarder contract. One Solana exception: on swap-and-bridge routes every fee is collected from the swap output. Each distribution is then percentage of the swap output in the intermediate token, not of fromAmount. Same-chain Solana smart-deposit routes have no fee-collection step and reject distributionFees. distributionFees is not the same as intermediary. intermediary is a named partner ID whose share is configured by LI.FI and requires both integrator and fee. distributionFees lists explicit receiver addresses and percentages on the request.

Request parameters

Pass distributionFees on GET /v1/quote, GET /v1/quote/toAmount, and in options on POST /v1/advanced/routes. The returned step echoes distributionFees; on the two-call flow, pass that step to POST /v1/advanced/stepTransaction unchanged so the split is re-resolved at transaction build. On GET endpoints, encode each entry with indexed query keys (distributionFees[0][receiver], distributionFees[0][percentage]). A JSON string in a single distributionFees query parameter is rejected with a validation error. On POST /v1/advanced/routes, send a JSON array in options.distributionFees.

Field	Type	Description
`receiver`	`string`	Recipient address in the source-chain form: 20-byte `0x`-prefixed hex on EVM/Tron (all-lowercase, or a valid EIP-55 checksum; a mixed-case address with a wrong checksum is rejected), base58 public key on Solana. The form must match the source chain. Zero and default addresses are rejected.
`percentage`	`number`	An additional fraction of `fromAmount` (of the swap output in the intermediate token on Solana swap-and-bridge routes); must be greater than `0` and less than `0.5` per entry

Limits and checks:

1 to 10 entries on EVM/Tron. At most 2 on Solana.
The integrator fee (0 if omitted) plus all percentage values must total less than 1. The percentages do not need to sum to 1.
Each amount rounds down and must be at least one base unit of the input token.
Every receiver is sanctions-screened when the transaction is built. A receiver accepted by /quote can still be rejected at transaction generation.
When the split is applied, feeCosts contains an entry named Distributions. Do not proceed if it is absent, and inspect the transaction data before execution.

Worked example

Set your API key first, then request the quote. This example charges a total partner fee of 2% of fromAmount: 1.4% to the configured integrator fee wallet and an additional 0.6% to a reseller.

export LIFI_API_KEY=your-api-key

curl --globoff -X GET 'https://li.quest/v1/quote?fromChain=1&toChain=137&fromToken=0x0000000000000000000000000000000000000000&toToken=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&fromAddress=0x1234567890123456789012345678901234567890&fromAmount=1000000000000000000&integrator=your-integrator-id&fee=0.014&distributionFees[0][receiver]=0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB&distributionFees[0][percentage]=0.006' \
  --header "x-lifi-api-key: $LIFI_API_KEY"

const params = new URLSearchParams({
  fromChain: '1',
  toChain: '137',
  fromToken: '0x0000000000000000000000000000000000000000',
  toToken: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174',
  fromAddress: '0x1234567890123456789012345678901234567890',
  fromAmount: '1000000000000000000',
  integrator: 'your-integrator-id',
  fee: '0.014',
  'distributionFees[0][receiver]': '0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB',
  'distributionFees[0][percentage]': '0.006',
})

const response = await fetch(`https://li.quest/v1/quote?${params}`, {
  headers: { 'x-lifi-api-key': process.env.LIFI_API_KEY! },
})
const quote = await response.json()
const distributions = quote.estimate.feeCosts.find((cost) => cost.name === 'Distributions')

The options fragment for the same split on POST /v1/advanced/routes:

{
  "options": {
    "integrator": "your-integrator-id",
    "fee": 0.014,
    "distributionFees": [
      { "receiver": "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB", "percentage": 0.006 }
    ]
  }
}

To pay additional recipients, add more { receiver, percentage } entries. LI.FI’s own service fee is resolved separately and must not be represented as a distributionFees recipient. Passing fee for an integrator that is not configured for fee collection is rejected; distributionFees can be sent without integrator/fee.

The addresses and percentages above are illustrative placeholders. Use your own configured wallet addresses and agreed revenue split when constructing real requests.

Response shape

When the split is applied, feeCosts contains one Distributions entry. Its amount is the total distributed and feeSplit.recipients[] lists each receiver with its own amount. For the worked example above:

{
  "name": "Distributions",
  "description": "Partner-specified fee distribution",
  "percentage": "0.0060",
  "token": { "address": "0x0000000000000000000000000000000000000000", "chainId": 1, "symbol": "ETH", "decimals": 18 },
  "amount": "6000000000000000",
  "included": true,
  "feeSplit": {
    "integratorFee": "0",
    "lifiFee": "0",
    "recipients": [
      {
        "name": "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
        "fee": "6000000000000000",
        "type": "DISTRIBUTION",
        "walletAddress": "0xBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB"
      }
    ]
  }
}

The integrator fee keeps its own separate feeCosts entry. Use the quote’s estimate.toAmount for the expected destination-token amount. Do not derive it by subtracting feeCosts[].amount from fromAmount, since these amounts may be denominated in different tokens. The /status response carries the same Distributions entry, rebuilt from the on-chain FeesForwarded recipients on EVM/Tron.

Config/setup for partners

Receiver entries are supplied per request rather than through the integrator fee-wallet configuration. Configure the integrator fee wallet in portal.li.fi as usual when you also collect an integrator fee. Contact LI.FI support if you need help validating a production setup.

Backward compatibility

When distributionFees is omitted, existing single-wallet fee behavior can continue to use the configured fee contract for that chain. When it is supplied:

EVM and Tron require FeeForwarder on the source chain. A legacy FeeCollector-only chain rejects the request instead of applying the split.
Solana does not use FeeForwarder; extra receivers are paid with transfer instructions, with at most 2 entries. On swap-and-bridge routes the percentages apply to the swap output; same-chain smart-deposit routes reject the parameter.
Treat the split as active only when the returned feeCosts contains Distributions and the transaction data matches the expected amounts.

Existing withdrawal endpoints remain available for fees previously accumulated in FeeCollector.

Event changes

For partners who parse on-chain events, the EVM fee event signature has changed. Previous event (contract):

event FeesCollected(
    address indexed _token,
    address indexed _integrator,
    uint256 _integratorFee,
    uint256 _lifiFee
);

New event (contract):

struct FeeDistribution {
    address recipient;
    uint256 amount;
}

event FeesForwarded(
    address indexed token,
    FeeDistribution[] distributions
);

The distributions array carries one FeeDistribution entry per resolved recipient, including entries produced from distributionFees[].receiver. This sample transaction shows fees forwarded directly from the LiFiDiamond address to the configured fee receiving wallets. The Status API has been updated to correctly parse the new event format. Fee data, including integratorFeeCost, continues to be returned in the same /status response structure.

What is not changing

No breaking API response structure changes
No changes required in partner integration code unless you opt in to distributionFees
The FeeForwarder contract migration itself applies to EVM/Tron. Bitcoin, Sui, Move, and Stellar still send integrator fees directly and do not support distributionFees. Solana also sends integrator fees directly, and additionally supports distributionFees (max 2 receivers)
Existing fees accumulated in FeeCollector are not automatically migrated; see the section below for how to withdraw them

Withdrawing previously collected fees

Fees collected through the legacy FeeCollector contract before the FeeForwarder upgrade are not migrated automatically. They remain in the FeeCollector contract and must be withdrawn manually.

Only the wallet address that was designated for fee collection when the fees were accrued can withdraw those fees. If you have since updated your fee wallet, use the original wallet to claim older balances.

Check your legacy balances

Via the Partner Portal: Log in to portal.li.fi and review your fee balances dashboard. Via the API:

GET https://li.quest/v1/integrators/{integratorId}

This returns your fee balances per chain and per token:

{
  "integratorId": "your-integrator-id",
  "feeBalances": [
    {
      "chainId": 137,
      "tokenBalances": [
        {
          "token": {
            "address": "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
            "symbol": "USDC",
            "decimals": 6,
            "chainId": 137,
            "name": "USD Coin",
            "priceUSD": "1.00"
          },
          "amount": "50000000",
          "amountUsd": "50.00"
        }
      ]
    }
  ]
}

Withdraw legacy fees

Via the Partner Portal: Use the withdrawal feature in portal.li.fi. Via the API:

GET https://li.quest/v1/integrators/{integratorId}/withdraw/{chainId}

This returns a transaction request that you sign and submit from the original fee wallet:

{
  "transactionRequest": {
    "to": "0x...",
    "data": "0x...",
    "value": "0"
  }
}

The withdrawal endpoint is available for EVM chains only. On Solana, Sui, and Bitcoin, fees have always been sent directly to your wallet and do not require withdrawal.

Summary

	FeeCollector (legacy)	FeeForwarder (new)
Fee settlement	Accumulated, claimed manually	Forwarded immediately at execution
Manual withdrawal	Required	Not required
Additional fee recipients	Not supported	Supported via `distributionFees[]` on EVM/Tron (FeeForwarder) and Solana (transfer instructions)
Partner action needed	None	None unless adding recipient-specific fees
Backward compatible	—	Existing single-wallet flows can continue; `distributionFees` on EVM/Tron requires FeeForwarder

This is a backend contract upgrade. Partners do not need to take any action unless they want to add recipient-specific fees through distributionFees.

If you have questions about fee configuration, distributionFees[], or how the Status API reports fees for your transactions, reach out via your usual support channel.

Integration

Troubleshooting

FeeForwarder

Why this change?

What changes for partners?

Immediate fee forwarding

Multi-party fee distribution

Request parameters

Worked example

Response shape

Config/setup for partners

Backward compatibility

Event changes

What is not changing

Withdrawing previously collected fees

Check your legacy balances

Withdraw legacy fees

Summary

​Why this change?

​What changes for partners?

​Immediate fee forwarding

​Multi-party fee distribution

​Request parameters

​Worked example

​Response shape

​Config/setup for partners

​Backward compatibility

​Event changes

​What is not changing

​Withdrawing previously collected fees

​Check your legacy balances

​Withdraw legacy fees

​Summary

Why this change?

What changes for partners?

Immediate fee forwarding

Multi-party fee distribution

Request parameters

Worked example

Response shape

Config/setup for partners

Backward compatibility

Event changes

What is not changing

Withdrawing previously collected fees

Check your legacy balances

Withdraw legacy fees

Summary