FeeForwarder

LI.FI 已在受支持的 EVM 链上升级了其费用处理机制，从 FeeCollector 合约迁移到新的 FeeForwarder 合约。本页解释了发生了哪些变化、这对您的集成意味着什么，以及您需要做什么（如果需要的话）。

为什么进行此项变更？

之前的 FeeCollector 模型要求费用在合约中累积，之后再手动提取。这增加了运营开销，并延迟了向费用接收方的支付。有了 FeeForwarder，费用会在交易执行时立即转发到配置的接收方钱包。无需手动提取步骤。该合约还支持在一笔交易中把合作伙伴指定的费用转发给多个接收方，例如集成商费用之外再增加分销商或中间方费用。

对合作伙伴有哪些变化？

即时费用转发

在部署了 FeeForwarder 的链上，交易会调用新合约，费用在执行时自动分配。合作伙伴无需采取任何操作。

多方费用分配（`distributionFees[]`）

默认情况下，您配置的集成商 fee 会被转发到已配置的费用钱包。您可以通过下述 distributionFees 请求参数增加其他接收方费用。当需要在同一笔交易中支付多个合作伙伴时，此功能很有用。每个 distributionFees 条目都是 fromAmount 的额外百分比，而不是集成商 fee 内部的分成比例。在 EVM 和 Tron 上，FeeForwarder 会在同一笔链上交易中原子结算这些金额。在 Solana 上，每个接收方通过单独的转账指令收款，不经过 FeeForwarder 合约。 Solana 有一个例外：swap-and-bridge 路由会从 swap 输出中收取全部费用。此时每个分配金额是 swap 输出（以中间代币计）的 percentage，而非 fromAmount 的比例。同链 Solana 智能存款路由没有费用收取步骤，会拒绝 distributionFees。 distributionFees 与 intermediary 不是同一参数。intermediary 是由 LI.FI 配置分成比例的具名合作伙伴 ID，且必须同时提供 integrator 和 fee。distributionFees 则在请求中直接列出 receiver 地址和百分比。

请求参数

在 GET /v1/quote、GET /v1/quote/toAmount 以及 POST /v1/advanced/routes 的 options 中传入 distributionFees。返回的 step 会原样回传 distributionFees；两步调用流程中，请将该 step 原封不动地传给 POST /v1/advanced/stepTransaction，拆分会在构建交易时重新计算。 GET 端点必须使用索引查询键编码每个条目（distributionFees[0][receiver]、distributionFees[0][percentage]）。把 JSON 字符串放进单个 distributionFees 查询参数会返回校验错误。POST /v1/advanced/routes 则在 options.distributionFees 中发送 JSON 数组。

字段	类型	说明
`receiver`	`string`	源链格式的接收地址：EVM/Tron 为 20 字节 `0x` 前缀十六进制（全小写或有效的 EIP-55 校验和；大小写混合但校验和错误的地址会被拒绝），Solana 为 base58 公钥。格式必须与源链匹配。零地址和默认地址会被拒绝。
`percentage`	`number`	`fromAmount` 的额外比例（Solana swap-and-bridge 路由按以中间代币计的 swap 输出计算）；每个条目必须大于 `0` 且小于 `0.5`

限制与校验：

EVM/Tron 提供 1 至 10 个条目；Solana 最多 2 个。
集成商 fee（省略时按 0 计）与所有 percentage 的总和必须小于 1；各比例本身不需要加总为 1。
每笔金额向下取整，且必须至少为输入代币的一个最小单位。
每个 receiver 都会在构建交易时进行制裁名单筛查；被 /quote 接受的接收方仍可能在生成交易时被拒绝。
拆分生效时，feeCosts 会包含名为 Distributions 的条目。如果该条目缺失，请勿继续执行，并在执行前核对交易数据。

示例

先设置 API key，再请求报价。以下示例收取 fromAmount 的 2% 作为合作伙伴总费用：1.4% 发送到已配置的集成商费用钱包，另加 0.6% 发送给分销商。

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')

同一拆分在 POST /v1/advanced/routes 中的 options 片段：

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

如需支付更多接收方，可添加更多 { receiver, percentage } 条目。LI.FI 自身的服务费会单独解析，不应作为 distributionFees 接收方传入。为未配置费用收取的 integrator 传入 fee 会被拒绝；distributionFees 可以不带 integrator/fee 发送。

上述地址和百分比仅为示例占位符。构造真实请求时，请使用您自己配置的钱包地址和约定的分成比例。

响应结构

拆分生效时，feeCosts 会包含一个 Distributions 条目。其 amount 为分配总额，feeSplit.recipients[] 列出每个接收方及其各自金额。以上文示例为例：

{
  "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"
      }
    ]
  }
}

集成商 fee 仍保留其独立的 feeCosts 条目。预期目标代币到账量请使用报价中的 estimate.toAmount。不要用 fromAmount 减去所有 feeCosts[].amount 推算，因为这些金额可能以不同代币计价。/status 响应会包含相同的 Distributions 条目，在 EVM/Tron 上根据链上 FeesForwarded 事件的接收方重建。

合作伙伴的配置/设置说明

接收方条目随每次请求传入，不属于集成商费用钱包配置。如果同时收取集成商 fee，仍在 portal.li.fi 配置集成商费用钱包。如需协助验证生产环境配置，请联系 LI.FI 支持团队。

向后兼容性

省略 distributionFees 时，现有单钱包费用流程可以继续使用该链已配置的费用合约。提供该参数时：

EVM 和 Tron 源链必须已部署 FeeForwarder。仅支持旧版 FeeCollector 的链会拒绝请求，而不会静默执行拆分。
Solana 不使用 FeeForwarder；额外接收方通过转账指令支付，最多 2 条。swap-and-bridge 路由按 swap 输出计算比例；同链智能存款路由会拒绝该参数。
只有当返回的 feeCosts 包含 Distributions 且交易数据中的金额符合预期时，才应视为拆分已生效。

FeeCollector 中此前累积费用的提取端点仍然可用。

事件变更

对于解析链上事件的合作伙伴，EVM 费用事件签名已发生变化。 先前的事件（合约）：

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

新事件（合约）：

struct FeeDistribution {
    address recipient;
    uint256 amount;
}

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

distributions 数组中每个已解析接收方对应一条 FeeDistribution 记录，包括由 distributionFees[].receiver 产生的条目。这个示例交易展示了费用如何从 LiFiDiamond 地址直接转发到配置的费用接收钱包。 Status API 已更新，以正确解析新的事件格式。费用数据（包括 integratorFeeCost）仍在相同的 /status 响应结构中返回。

哪些内容没有变化

API 响应结构没有破坏性变化
除非选择启用 distributionFees，否则合作伙伴集成代码无需变更
FeeForwarder 合约迁移本身适用于 EVM/Tron。Bitcoin、Sui、Move 和 Stellar 仍直接发送集成商费用，且不支持 distributionFees。Solana 也直接发送集成商费用，并额外支持 distributionFees（最多 2 个接收方）
FeeCollector 中已累积的现有费用不会自动迁移；请参阅下方章节了解如何提取

提取先前收取的费用

在 FeeForwarder 升级之前通过旧版 FeeCollector 合约收取的费用不会自动迁移。它们仍保留在 FeeCollector 合约中，必须手动提取。

只有在费用累积时被指定用于费用收取的钱包地址才能提取这些费用。如果您此后更新了费用钱包，请使用原始钱包来领取较早的余额。

检查您的旧版余额

通过 Partner Portal： 登录 portal.li.fi 并查看您的费用余额仪表板。 通过 API：

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

这将按链和按代币返回您的费用余额：

{
  "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"
        }
      ]
    }
  ]
}

提取旧版费用

通过 Partner Portal： 使用 portal.li.fi 中的提取功能。 通过 API：

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

这将返回一个交易请求，您需要用原始费用钱包对其进行签名并提交：

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

提取端点仅适用于 EVM 链。在 Solana、Sui 和 Bitcoin 上，费用始终直接发送到您的钱包，无需提取。

小结

	FeeCollector（旧版）	FeeForwarder（新版）
费用结算	累积，手动领取	执行时立即转发
手动提取	需要	不需要
额外费用接收方	不支持	EVM/Tron（FeeForwarder）和 Solana（转账指令）可通过 `distributionFees[]` 支持
需要合作伙伴操作	无	无，除非添加接收方费用
向后兼容	—	现有单钱包流程可继续；EVM/Tron 上的 `distributionFees` 需要 FeeForwarder

这是一次后端合约升级。除非合作伙伴希望通过 distributionFees 添加接收方费用，否则无需采取任何操作。

如果您对费用配置、distributionFees[] 或 Status API 如何报告您交易的费用有疑问，请通过您常用的支持渠道联系我们。

​为什么进行此项变更？

​对合作伙伴有哪些变化？

​即时费用转发

​多方费用分配（distributionFees[]）

​请求参数

​示例

​响应结构

​合作伙伴的配置/设置说明

​向后兼容性

​事件变更

​哪些内容没有变化

​提取先前收取的费用

​检查您的旧版余额

​提取旧版费用

​小结

为什么进行此项变更？

对合作伙伴有哪些变化？

即时费用转发

多方费用分配（`distributionFees[]`）

请求参数

示例

响应结构

合作伙伴的配置/设置说明

向后兼容性

事件变更

哪些内容没有变化

提取先前收取的费用

检查您的旧版余额

提取旧版费用

小结