交易状态

本指南说明如何使用 LI.FI 提供的 /status 端点检查跨链和交换交易的状态。

查询 status 端点

要获取转账状态，可以使用以下任一值查询 /status 端点：

发送交易哈希
接收交易哈希
transactionId

上述值只需提供其中一个，并需要通过 txHash 参数传入。

必填：

txHash

可选：

fromChain：加快请求速度（推荐）
toChain
bridge

对于交换交易，将 fromChain 和 toChain 设置为相同的值。bridge 参数可以省略。

const getStatus = async (txHash: string) => {
  const result = await axios.get('https://li.quest/v1/status', {
    params: { txHash },
  });
  return result.data;
};

示例响应

{
  "transactionId": "0x0959ee0fbb37a868752d7ae40b25dbfa3b7d72f499fa8386fd5f4105b18b62bd",
  "sending": {
    "txHash": "0x5862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826304846bbc93c0v",
    "txLink": "https://etherscan.io/tx/0x5862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826304846bbc93c0v",
    "amount": "60000000000000000000000",
    "token": {
      "symbol": "ORDS",
      "priceUSD": "0.012027801612559667"
    },
    "gasPrice": "23079962248",
    "gasUsed": "231727",
    "gasAmountUSD": "14.0296",
    "amountUSD": "721.6681",
    "includedSteps": [
      {
        "tool": "feeCollection",
        "fromAmount": "60000000000000000000000",
        "toAmount": "59820000000000000000000"
      },
      {
        "tool": "1inch",
        "fromAmount": "59820000000000000000000",
        "toAmount": "275101169247651913"
      }
    ]
  },
  "receiving": {
    "txHash": "0x2862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826604846bbc93c0v",
    "amount": "275101169247651913",
    "token": {
      "symbol": "ETH",
      "priceUSD": "2623.22"
    },
    "gasAmountUSD": "14.0296",
    "amountUSD": "721.6509"
  },
  "lifiExplorerLink": "https://scan.li.fi/tx/0x5862726dbc6643c6a34b3496bb15e91f11771f6756ccf83826304846bbc93c0e",
  "fromAddress": "0x14a980237fa9797fa27c5152c496cab65e36da4f",
  "toAddress": "0x14a980237fa9797fa27c5152c496cab65e36da4f",
  "tool": "1inch",
  "status": "DONE",
  "substatus": "COMPLETED",
  "substatusMessage": "The transfer is complete.",
  "metadata": {
    "integrator": "example_integrator"
  }
}

报价金额与成交金额

当 LI.FI 为该笔转账签发过报价时，GET /v1/status 会带上可选的 quote 对象，用来核对报价时的估算与实际结算结果。

quote.action 是当时请求的内容。
quote.estimate 记录报价金额与成本（toAmount、toAmountMin、费用、gas）。
sending 和 receiving 是实际成交的两端。用 receiving.amount 对比 quote.estimate.toAmount 和 quote.estimate.toAmountMin。

不需要额外查询参数。当 LI.FI 没有存下这笔报价时，该字段会被省略——例如交易从未经过 /quote 或 /stepTransaction、由合作方导入，或记录早于报价持久化。省略不是错误，也不会改变 status 或 substatus。 quote 在 status 仍为 PENDING 时就可能出现，因为它来自报价时的记录，而不是目标链结算。完整 schema 见 GET /v1/status API 参考。

Quote 对象

字段	说明
`stepId`	被报价 step 的 id，与 `/quote` 响应中的 `id` 一致。
`tool`	当时报价的工具。
`type`	被报价 step 的类型。
`action`	当时请求的转账（`Action`，与 `/quote` 相同）。
`estimate`	报价结果（`Estimate`，含预估值 `toAmount` 和最低值 `toAmountMin`）。
`includedSteps`	被报价的子步骤。每项含 `tool`、`type`、`action`、`estimate`。
`integrator`	签发报价时的 integrator（若已存储）。
`gasLimit`	报价时提议交易的 gas limit（字符串）。
`createdAt`	报价签发时间（ISO 8601）。

内部数据库字段会被去掉，不会出现在响应里。

核对已完成的转账

轮询 /status，直到 status 为 DONE。
若存在 quote，把 receiving.amount 与 quote.estimate.toAmountMin（报价最低值）和 quote.estimate.toAmount（报价估值）比较。
substatus: COMPLETED 表示转账成功结束，并不表示 receiving.amount 等于 quote.estimate.toAmount。实际到账可以与报价估值不同，但仍不低于 toAmountMin。
若不是足额交付，结合 PARTIAL / REFUNDED 和金额一起看。

示例

2026-09-14 在生产环境观察到的 GET /v1/status（已精简）。报价 toAmount 为 377946589；实际 receiving.amount 为 377639049，仍高于 toAmountMin 376056856。

curl "https://li.quest/v1/status?txHash=0x1f61dc6a35bdf60c1d1d5fe9bf983667c13afbc9d00d7d8d62a6720bb1aff20a&fromChain=999"

{
  "status": "DONE",
  "substatus": "COMPLETED",
  "tool": "mayan",
  "sending": {
    "txHash": "0x1f61dc6a35bdf60c1d1d5fe9bf983667c13afbc9d00d7d8d62a6720bb1aff20a",
    "amount": "378108480",
    "chainId": 999
  },
  "receiving": {
    "amount": "377639049",
    "chainId": 8453
  },
  "quote": {
    "stepId": "069e657a-5160-433e-a6bf-03264328ee0d:0",
    "tool": "mayan",
    "type": "lifi",
    "action": {
      "fromChainId": 999,
      "toChainId": 8453,
      "fromAmount": "378108480",
      "slippage": 0.005
    },
    "estimate": {
      "fromAmount": "378108480",
      "toAmount": "377946589",
      "toAmountMin": "376056856"
    },
    "includedSteps": [
      {
        "tool": "mayan",
        "type": "cross"
      }
    ],
    "integrator": "jumper.exchange",
    "gasLimit": "0x8c99c",
    "createdAt": "2025-09-15T01:32:52.376Z"
  }
}

const result = await axios.get('https://li.quest/v1/status', {
  params: { txHash, fromChain },
});
const actual = result.data.receiving?.amount;
const quotedMin = result.data.quote?.estimate?.toAmountMin;
const quoted = result.data.quote?.estimate?.toAmount;

if (actual && quotedMin) {
  // 金额是以目标代币最小单位表示的整数字符串。
  // 使用 BigInt，避免大额代币数量丢失精度。
  const actualAmount = BigInt(actual);
  const quotedMinimum = BigInt(quotedMin);
  const varianceFromEstimate = quoted
    ? actualAmount - BigInt(quoted)
    : undefined;

  console.log({
    belowQuotedMinimum: actualAmount < quotedMinimum,
    varianceFromEstimate: varianceFromEstimate?.toString(),
  });
}

状态值

状态	描述
`NOT_FOUND`	交易不存在或尚未被打包。
`INVALID`	哈希与所请求的工具不匹配。
`PENDING`	桥接仍在进行中。
`DONE`	交易已成功完成。
`FAILED`	桥接过程失败。

当 LI.FI 无法找到该哈希时，/status 可能返回 HTTP 404 和错误代码 1003（其他查询路径仍可能返回 NOT_FOUND 响应体）：

{ "message": "Transaction hash '0x…' not found on chain '1'", "code": 1003 }

如果未提供 fromChain，消息会是 Transaction hash is not found in any chain.。请将此响应视为 NOT_FOUND：广播后的头一两分钟内出现是正常的，如果持续存在则可能存在问题。参见未知和永远不会被打包的交易哈希。

子状态定义

PENDING

WAIT_SOURCE_CONFIRMATIONS：等待源链确认
WAIT_DESTINATION_TRANSACTION：等待目标交易
BRIDGE_NOT_AVAILABLE：桥接 API 不可用
CHAIN_NOT_AVAILABLE：源链/目标链 RPC 不可用
REFUND_IN_PROGRESS：退款进行中（如果支持）
UNKNOWN_ERROR：状态不确定

DONE

COMPLETED：转账成功
PARTIAL：仅完成部分转账（常见于 across、hop、stargate、amarok）
REFUNDED：代币已退回

FAILED

NOT_PROCESSABLE_REFUND_NEEDED：无法完成，需要退款
OUT_OF_GAS：交易 gas 耗尽
SLIPPAGE_EXCEEDED：接收金额过低
INSUFFICIENT_ALLOWANCE：授权额度不足
INSUFFICIENT_BALANCE：余额不足
EXPIRED：交易已过期
UNKNOWN_ERROR：未知或无效状态
REFUNDED：代币已退回

未知和永远不会被打包的交易哈希

LI.FI 查不到哈希，并不证明交易没有上链。原因可能是索引延迟、源链选择错误、交易仍在等待、被替换、从 mempool 丢弃，或记录的哈希并非最终广播的交易哈希。被丢弃的交易之后仍可能重新广播。

按源链情况设置有限的轮询窗口并采用退避策略；等待时间不是失败证据。
先在正确源链上查询原哈希的收据（EVM 使用 eth_getTransactionReceipt）。有收据表示原交易已上链，不应判为被替换：执行失败则按源链失败处理；执行成功则继续核对 LI.FI 和跨链后续状态。按应用要求等待确认，并考虑链重组。
没有收据时，再查原交易（EVM 使用 eth_getTransactionByHash）。仍处于 pending 时不能判为被替换；RPC 查不到或查询失败也不证明交易已被丢弃。
对普通 EVM 账户交易，可用 eth_getTransactionCount 的 latest nonce 缩小调查范围，但 nonce 前进也可能是原交易上链造成的。只有核实另一笔交易在同一源链、由同一发送账户使用同一 nonce 上链后，才能确认替换；不要用 pending nonce 证明上链。这套 nonce 规则不适用于非 EVM 交易或账户抽象的操作标识。
在将替代哈希绑定到原订单前，检查它实际执行的操作（接收方、value、calldata 及相关事件）是否延续原转账。加速、取消、改变用途都可能使用同一 nonce。取消不代表完成跨链操作；未知原始 nonce 或用途时，不自动绑定。

可在达到轮询上限后暂停自动查询，但应保留未确认状态及交易上下文，以便后续核对。超时、404 或 nonce 前进都不能单独证明失败或替换，也不应因此自动重发转账。

按钱包核对

当被跟踪的哈希未知，但用户的资金可能已经在另一个哈希下发生了转移时，请改为查询该钱包的转账记录，而不是查询哈希：

curl "https://li.quest/v1/analytics/transfers?wallet=0x590b7835c489b238156e8411187f05b3f018815d&fromTimestamp=1788681600&toTimestamp=1788685200&status=ALL"

使用 status=ALL 才会同时纳入 DONE、PENDING 和 FAILED；默认只返回 DONE。这些只是 LI.FI 已索引的候选，不是完整链上历史；没有结果不证明未发生替换。响应示例：

{
  "transfers": [
    {
      "status": "DONE",
      "tool": "relaydepository",
      "sending": {
        "chainId": 1,
        "txHash": "0xab28fe3857427db9b5f74a6465d309d3be885003015c6f6d483b162845936f15",
        "amount": "1174196371374981",
        "token": { "symbol": "ETH" }
      },
      "receiving": {
        "chainId": 4663,
        "txHash": "0xb568d4796d81f6f03f6e8b143175390c891a20d7372b79959c5e5c0f4ae54f3a"
      }
    }
  ]
}

链对、金额和时间只能筛选候选，不能确认身份。对候选的 sending.txHash，按上述流程核对源链、发送方、nonce、收据和用途；全部核实后才绑定原订单，并继续使用 /status?txHash=<sending.txHash> 跟踪。可选过滤条件包括 fromChain、toChain、integrator。参见 transfers 端点参考。

轮询指南

DONE 和 FAILED 是终态。一旦收到其中之一，应立即停止轮询。
采用退避策略：第一分钟内每 10 秒轮询一次，随后改为 30 秒，再改为 60 秒，并设置总时长上限。大多数 bridge 会在报价的 estimate.executionDuration 时间内完成。
持续的 404 / 1003（或 NOT_FOUND）不是终态证据。按上述源链流程核查；暂停轮询不等于确认失败或替换。

了解 LI.FI

支持的系统

LI.FI 架构

用户流程和示例

了解更多

更新日志

交易状态跟踪

交易状态

查询 status 端点

必填：

可选：

示例响应

报价金额与成交金额

Quote 对象

核对已完成的转账

示例

状态值

子状态定义

PENDING

DONE

FAILED

未知和永远不会被打包的交易哈希

按钱包核对

轮询指南

​交易状态

​查询 status 端点

​必填：

​可选：

​示例响应

​报价金额与成交金额

​Quote 对象

​核对已完成的转账

​示例

​状态值

​子状态定义

​PENDING

​DONE

​FAILED

​未知和永远不会被打包的交易哈希

​按钱包核对

​轮询指南

交易状态

查询 status 端点

必填：

可选：

示例响应

报价金额与成交金额

Quote 对象

核对已完成的转账

示例

状态值

子状态定义

PENDING

DONE

FAILED

未知和永远不会被打包的交易哈希

按钱包核对

轮询指南