无 gas 交易

无 gas 执行让用户可以在不持有源链原生代币的情况下完成交换或 bridge。用户签署的是一个 EIP-712 载荷，而不是发送交易。LI.FI 会在链上中继该载荷并支付 gas，随后以输入代币收取中继成本，并在报价中单独列出。本指南只涵盖无 gas 方式在标准集成基础上新增的内容。关于它所依赖的基础概念，请参阅请求路由与报价、报价与路由的区别、状态跟踪，以及关于身份验证和速率限制的 API 参考。

工作原理

获取可签名的步骤

在标准报价请求中加入 gasless=true，或在路由请求中设置 options.gasless: true，并针对所选步骤提交交易数据。两种方式都会返回一个携带 EIP-712 载荷、过期时间，以及成本估算中中继费用条目的步骤。

签名

用户使用 eth_signTypedData_v4 对类型化数据进行签名。用户账户不会发出任何交易，也不需要原生代币。

中继

将已签名的步骤提交到 POST /v1/advanced/relay。LI.FI 会验证签名，将载荷与原始报价进行校验，并从中继账户广播交易。响应中会携带一个任务 ID。

跟踪

轮询 GET /v1/status?taskId=...，直到转账状态变为 DONE 或 FAILED。

已签名的载荷是一批通过用户自己的账户、在 EIP-7702 委托下执行的调用：中继费用转账、ERC-20 输入代币的授权，以及交换或 bridge 调用。中继器只能按签名内容原样提交这批调用，且整批调用要么全部成功要么全部回滚。只要其中一个调用回滚，其余调用（包括费用转账）也会一并回滚。

前置条件

前置条件	说明
源链	LI.FI 当前为该账户已安装的委托合约提供中继服务的 EVM 链。可用性在报价时确定。目标链可以是 LI.FI 支持的任意链。
`fromAddress`	每个无 gas 请求都必须提供。账户的链上状态决定了载荷的构建方式。
账户类型	一个已经通过 EIP-7702 委托给 LI.FI 代为中继的委托合约的 EOA，目前为 Calibur。通过 ERC-1271 签名的智能合约钱包不受支持。

未完成委托的 EOA 目前无法获得服务。/v1/quote 在这种情况下可能返回一个通用的”无可用报价”错误。要获取针对该账户和链的具体原因，请改为请求路由，并检查 unavailableRoutes.filteredOut[].reason。

第一步：获取可签名的步骤

两种标准报价流程均无需改动即可使用。无 gas 只是一个请求标志。在标准报价请求中加入 gasless=true，响应即为可签名的步骤：

curl --request GET \
  --url 'https://li.quest/v1/quote?fromChain=42161&toChain=42161&fromToken=0xaf88d065e77c8cC2239327C5EDb3A432268e5831&toToken=0x82aF49447D8a07e3bd95BD0d56f35241523fBab1&fromAmount=50000000&fromAddress=0xYOUR_USER_ADDRESS&integrator=YOUR_INTEGRATOR_NAME&gasless=true' \
  --header 'x-lifi-api-key: YOUR_API_KEY'

const params = new URLSearchParams({
  fromChain: '42161',                                            // Arbitrum
  toChain: '42161',
  fromToken: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',       // USDC
  toToken: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1',         // WETH
  fromAmount: '50000000',                                        // 50 USDC（6 位小数）
  fromAddress: '0xYOUR_USER_ADDRESS',                            // 无 gas 场景必填
  integrator: 'YOUR_INTEGRATOR_NAME',
  gasless: 'true',
})

const step = await fetch(`https://li.quest/v1/quote?${params}`, {
  headers: { 'x-lifi-api-key': API_KEY },
}).then((res) => res.json())

如果想从多条路由中选择，可在标准的 /v1/advanced/routes 请求体中设置 options.gasless: true 来请求路由。这些路由已经计入了中继费用，但尚未携带可签名的载荷。将所选路由的步骤原样提交到 /v1/advanced/stepTransaction，响应会以与单次报价相同的结构返回。

无 gas 方式不适用于 /v1/quote/toAmount，也不能与 executionType=message 或 executionType=all 组合使用，这类请求会被拒绝。/v1/quote/contractCalls 不支持无 gas 执行，会忽略 gasless 字段，请求会按普通合约调用报价继续处理。反向报价会被拒绝，因为其收敛计算只能求解基于百分比的费用，无法求解以固定 gas 计价的中继费用。

可签名的步骤

一个无 gas 步骤是一个标准的 LI.FI 步骤，外加两个额外属性，以及成本估算中的中继费用条目：

{
  "id": "9d5cbeeb-...",
  "type": "lifi",
  "tool": "sushiswap",
  "action": { /* 与往常相同 */ },
  "estimate": {
    "feeCosts": [
      { "name": "LIFI Gasless Relay Fee", "included": true /* ... */ }
    ]
    // ...
  },

  // 用户要签名的载荷。
  "typedData": [
    {
      "primaryType": "SignedBatchedCall",
      "domain": {
        "name": "Calibur",
        "version": "1.0.0",
        "chainId": 42161,
        "verifyingContract": "0xYOUR_USER_ADDRESS",  // 用户自己的账户
        "salt": "0x..."
      },
      "types": { /* EIP712Domain, SignedBatchedCall, BatchedCall, Call */ },
      "message": {
        "batchedCall": {
          "calls": [
            { "to": "0x...", "value": "0", "data": "0x..." },  // 中继费用转账
            { "to": "0x...", "value": "0", "data": "0x..." },  // 授权（仅限 ERC-20 输入）
            { "to": "0x...", "value": "0", "data": "0x..." }   // 交换或 bridge 调用
          ],
          "revertOnFailure": true
        },
        "nonce": "...",
        "keyHash": "0x00...00",
        "executor": "0x...",
        "deadline": 1765432100
      }
    }
  ],

  // 签名不再被接受的 Unix 秒数时间点。
  "expiresAt": 1765432100
}

typedData 可直接用于 eth_signTypedData_v4。在 EIP-7702 委托下，执行这批调用的账户就是用户自己的地址，这也是为什么 domain.verifyingContract 是该地址。委托实现通过 domain.salt 绑定。
expiresAt 是 Unix 秒数，与载荷中的 deadline 相等。有效期很短，以分钟而非小时计。过期后请重新请求报价，不会产生任何费用。
transactionRequest 在这里不会用到。执行是通过已签名的类型化数据和中继接口完成的。

提交到中继接口的步骤必须与收到时完全一致。LI.FI 会将其与报价时存储的记录进行校验，因此对调用、金额、接收方或截止时间的任何改动都会被拒绝。

第二步：签署载荷

使用标准的 EIP-712 类型化数据签名方式进行签名。通过 JSON-RPC 将载荷传递给钱包时，请原样使用，因为 types 对象中包含了钱包会校验的 EIP712Domain 条目。

const [payload] = step.typedData

const signature = await walletClient.signTypedData({
  account,
  domain: payload.domain,
  types: payload.types,
  primaryType: payload.primaryType,
  message: payload.message,
})

const [payload] = step.typedData

// ethers 会自行推导 domain 类型，且会拒绝显式的 EIP712Domain 条目。
const { EIP712Domain, ...types } = payload.types

const signature = await signer.signTypedData(payload.domain, types, payload.message)

第三步：提交中继请求

将该步骤原样提交，并在类型化数据条目中附上签名：

TypeScript

const relayBody = {
  ...step,
  typedData: [{ ...step.typedData[0], signature }],
}

const response = await fetch('https://li.quest/v1/advanced/relay', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-lifi-api-key': API_KEY,
  },
  body: JSON.stringify(relayBody),
})

请求被接受时，接口返回 200：

{
  "status": "ok",
  "data": {
    "taskId": "0x2f8a...c41d"
  }
}

“已接受”意味着 LI.FI 已经验证了已签名的执行内容，将其持久化记录，并且下游执行方已接受该任务进行提交。请保存返回的任务 ID，并在收到确认后使用状态接口进行跟踪。如果请求在收到该确认之前失败，请将结果视为不确定状态，并遵循下文的重试指引，而不要假定载荷是否已被接受。

中继错误

拒绝会采用 LI.FI 标准的错误响应格式：与其他所有接口相同的响应体结构、相同的数字错误码，以及相同的 HTTP 状态码。状态码和 code 标明了应对方式，message 则说明具体是哪项检查未通过，供你记录日志或用于支持排查。

HTTP	`code`	含义	应对方式
400	1011	已签名的载荷永远无法执行。签名、载荷完整性、账户状态或试运行阶段的验证失败，未提交任何内容。	请求一个新的报价并让用户重新签名。重新提交会以相同方式失败。
404	1003	已签名的步骤无法匹配到一个有效的报价完整性记录，因为其绑定关系缺失、已过期，或在被接受前已被消耗。	请求一个新的报价。
409	1007	该已签名报价的 nonce 与链上状态不再匹配，或 gas 价格发生变化，导致报价中的费用不再足以覆盖执行成本。	在状态稳定后请求新的报价；但如果这紧跟在一次不确定的 `424` 之后，请先核实原始执行情况，再提交替代请求。
422	1004	中继无法为该请求提供服务。无 gas 中继已关闭，或该账户需要中继不支持的某项能力。	请勿重试，请联系 LI.FI。
424	1008	中继无法确认接受流程是否已完成。该失败可能发生在持久化记录建立之前，也可能发生在下游提交已经开始之后。	将结果视为不确定状态。不要立即签署或提交另一笔不同的执行。以退避方式重试完全相同的请求。后续如果返回 `404`，意味着需要重新报价；如果返回 `409`，则可能是原始执行已经推进，需先核实再替换。

在下游提交之前报告的失败不会广播交易，也不会向用户收费。424 情况有所不同：它可能代表一个不确定的下游结果，不能被当作”未提交任何内容”的证据。

第四步：跟踪执行

状态跟踪的方式与状态跟踪指南中描述的一致，但有两个无 gas 场景特有的地方。从中继被接受的那一刻起，即使还没有任何交易产生，执行就可以通过任务 ID 进行查询。一旦响应中出现了交易哈希，同一笔执行也可以通过该哈希查询。

curl

curl --request GET \
  --url 'https://li.quest/v1/status?taskId=0x2f8a...c41d' \
  --header 'x-lifi-api-key: YOUR_API_KEY'

有两种状态是无 gas 场景特有的：

`status`	`substatus`	含义
`PENDING`	无	已接受，尚未广播任何交易。
`FAILED`	`EXPIRED`	签名截止时间在广播前已过期。未产生任何花费或收费，请重新请求报价。
`FAILED`	`UNKNOWN_FAILED_ERROR`	执行失败，`substatusMessage` 中会携带具体原因。失败的批次是原子性回滚的，因此不会收取任何费用。

其余部分遵循标准的状态语义。响应会将该笔转账归属到发起签名的用户地址，而不是中继账户，因此你的记账方式与用户自行提交交易时保持一致。

费用

中继费用覆盖了 LI.FI 代表用户执行交易所花费的 gas。它是一个以 gas 计价的固定金额，依据链的 gas 特征和报价时的实时 gas 价格计算得出，随后换算为输入代币。该数值在 /v1/quote、/v1/advanced/routes 和 /v1/advanced/stepTransaction 中保持一致。它会以固定名称 LIFI Gasless Relay Fee（included: true）出现在成本估算中，这意味着它会在路由前从 fromAmount 中扣除，报价中的输出金额已经反映了这一点。用户的总支出正好等于 fromAmount。在链上，费用转账是已签名批次中的第一个调用。它受签名保护，中继器无法改动，并且与交换操作是原子性的，因此除非交换成功执行，否则无法收取该费用。被拒绝的中继请求、过期的签名和失败的执行都不会产生任何收费。

费用在已签名的报价中是固定的，但如果 gas 价格变动超出可接受的容差范围，中继时的检查仍会以 409 拒绝该请求。届时请重新请求报价。

无法提供无 gas 服务的情况

在 /v1/quote 上，拒绝会以标准的”未找到”错误返回。在 /v1/advanced/routes 上，它会出现在 unavailableRoutes.filteredOut 中，其中 reason 是一句人类可读的说明，遵循与其他所有路由过滤条件相同的约定。你可以将其展示给用户，或写入日志，但不要以编程方式对其进行匹配。以下情况会导致无 gas 请求被拒绝：

该账户是未完成委托的 EOA，或委托给了 LI.FI 不提供中继服务的合约；
该账户是智能合约钱包；
请求中未携带 fromAddress；
该路由在输入金额之外还收取固定的原生代币费用，无 gas 用户无法承担这笔费用，其他工具可能仍可服务该笔交易；
中继费用扣除后，剩余的输入金额不足以支撑执行，这也是该功能对交易规模设下限的原因。

操作注意事项

将每个已签名的报价视为独立的一次执行

不同的报价使用各自独立的、带键值的 nonce，可以为同一账户并存。409 nonce 冲突意味着该已签名报价对应的 nonce 与链上状态不再匹配，例如因为同一笔执行已经被消耗。请重新请求报价，而不要重新签名或修改旧的载荷。

在签名时才请求报价

签名截止时间很短。请在用户准备好签名时才请求报价，并在签名完成后立即中继。费用过期和报价过期属于常见的拒绝情形，且都不会产生任何费用，重新获取并重试即可。

不要缓存报价

每个报价都嵌入了账户状态和一个很短的截止时间。请将其视为一次性的签名载荷，遵守 expiresAt，并只在用户准备好签名时才请求它。

重试同一个载荷，但要处理状态变化

在超时或 424 之后，只应以退避方式重试完全相同的已签名请求，切勿立即另外创建一次替代执行。重试可能会恢复一个已存在的、尚未广播的记录；如果报价完整性记录在被接受前已被消耗，会返回 404；如果 nonce 或费用状态发生变化，会返回 409。收到 404 后请重新报价；收到 409 后，请先核实原始执行是否已经推进。成功收到确认后，请保存任务 ID 并跟踪状态，而不要重新提交该载荷。

后续步骤

Gas Fronting

在桥接资产的同时提供目标链原生 gas，让用户到账后即可交易。

状态跟踪

转账完整的状态与子状态词汇表。

错误码

API 返回的每个数字错误码及其含义。

API 参考

身份验证、速率限制和完整的接口列表。

​工作原理

​前置条件

​第一步：获取可签名的步骤

​可签名的步骤

​第二步：签署载荷

​第三步：提交中继请求

​中继错误

​第四步：跟踪执行

​费用

​无法提供无 gas 服务的情况

​操作注意事项

​后续步骤

Gas Fronting

状态跟踪

错误码

API 参考

工作原理

前置条件

第一步：获取可签名的步骤

可签名的步骤

第二步：签署载荷

第三步：提交中继请求

中继错误

第四步：跟踪执行

费用

无法提供无 gas 服务的情况

操作注意事项

后续步骤