Documentation Index
Fetch the complete documentation index at: https://docs.nexfi.robert.dpdns.org/llms.txt
Use this file to discover all available pages before exploring further.
Bridge 路线与订单
本页对照 Bridge 详细设计文档，补充跨链桥路线与订单接口的用途、参数、字段说明和示例。
GET /api/v1/bridge/routes
查询可用跨链路线，供钱包侧在跨链确认前展示最优路线、费用和预计到账时间。
Query 参数
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|
fromChainId | Integer | 是 | 源链 ID | 1 |
toChainId | Integer | 是 | 目标链 ID | 8453 |
fromToken | String | 是 | 源资产符号或标识 | USDC |
toToken | String | 是 | 目标资产符号或标识 | USDC |
amount | String | 是 | 跨链金额 | 1000 |
walletAddress | String | 否 | 用户钱包地址，用于部分 provider 报价或权限判断 | 0xabc... |
请求示例
GET /api/v1/bridge/routes?fromChainId=1&toChainId=8453&fromToken=USDC&toToken=USDC&amount=1000&walletAddress=0xabc...
响应字段
| 字段路径 | 类型 | 说明 | 示例 |
|---|
data.routes | Array | 可用路线列表 | [] |
data.routes[].routeId | String | 路线唯一 ID | route_base_usdc_01 |
data.routes[].providerKey | String | provider 标识 | across |
data.routes[].bridgeName | String | 展示名称 | Across |
data.routes[].estimatedReceiveAmount | String | 预计到账金额 | 998.42 |
data.routes[].bridgeFeeAmount | String | 跨链桥手续费 | 1.10 |
data.routes[].networkFeeAmount | String | 网络手续费 | 0.48 |
data.routes[].estimatedArrivalSeconds | Integer | 预计到账秒数 | 420 |
data.routes[].riskLevel | String | 路线风险等级：low medium high | medium |
响应示例
{
"code": 0,
"msg": "ok",
"data": {
"routes": [
{
"routeId": "route_base_usdc_01",
"providerKey": "across",
"bridgeName": "Across",
"estimatedReceiveAmount": "998.42",
"bridgeFeeAmount": "1.10",
"networkFeeAmount": "0.48",
"estimatedArrivalSeconds": 420,
"riskLevel": "medium"
}
]
}
}
业务说明
- 路线结果应按平台策略排序，不应随机返回。
- 若无可用路线，应返回空数组而不是伪造路线。
- 前端展示时应区分桥费与网络费，不应合并成单一费用字段。
POST /api/v1/bridge/orders
创建桥接订单，表示平台开始跟踪这次跨链请求，但不代表用户已经完成源链交易。
Body 参数
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|
routeId | String | 是 | 选中的路线 ID | route_base_usdc_01 |
fromChainId | Integer | 是 | 源链 ID | 1 |
toChainId | Integer | 是 | 目标链 ID | 8453 |
fromToken | String | 是 | 源资产 | USDC |
toToken | String | 是 | 目标资产 | USDC |
amount | String | 是 | 跨链金额 | 1000 |
senderAddress | String | 是 | 发起地址 | 0xabc... |
recipientAddress | String | 是 | 接收地址 | 0xabc... |
请求示例
{
"routeId": "route_base_usdc_01",
"fromChainId": 1,
"toChainId": 8453,
"fromToken": "USDC",
"toToken": "USDC",
"amount": "1000",
"senderAddress": "0xabc...",
"recipientAddress": "0xabc..."
}
响应字段
| 字段路径 | 类型 | 说明 | 示例 |
|---|
data.orderId | String | 平台订单号 | bridge_20260511_0001 |
data.status | String | 订单状态 | created |
data.providerKey | String | 对应 provider | across |
响应示例
{
"code": 0,
"msg": "ok",
"data": {
"orderId": "bridge_20260511_0001",
"status": "created",
"providerKey": "across"
}
}
业务说明
- 创建订单仅表示服务端开始跟踪订单生命周期。
- 用户仍需在钱包本地签名并广播源链交易。
- 订单后续应可关联 provider 订单号和源链交易哈希。
GET /api/v1/bridge/orders/{id}
根据平台订单号查询桥接订单状态，用于订单详情页和活动流状态刷新。
Path 参数
| 参数 | 类型 | 必填 | 说明 | 示例 |
|---|
id | String | 是 | 平台订单号 | bridge_20260511_0001 |
响应字段
| 字段路径 | 类型 | 说明 | 示例 |
|---|
data.orderId | String | 平台订单号 | bridge_20260511_0001 |
data.providerKey | String | provider 标识 | across |
data.status | String | 聚合后的订单状态 | bridging |
data.sourceTxHash | String | Null | 源链交易哈希 | 0x123... |
data.updatedAt | String | 最后更新时间 | 2026-05-11T10:00:00.000Z |
data.failReason | String | Null | 失败原因 | null |
响应示例
{
"code": 0,
"msg": "ok",
"data": {
"orderId": "bridge_20260511_0001",
"providerKey": "across",
"status": "bridging",
"sourceTxHash": "0x123...",
"updatedAt": "2026-05-11T10:00:00.000Z",
"failReason": null
}
}
订单状态说明
| 状态 | 含义 |
|---|
created | 订单已创建，等待用户发起源链交易 |
pending_source | 已检测到源链动作，但尚未进入桥接中状态 |
bridging | 第三方桥正在执行跨链 |
completed | 目标链到账完成 |
failed | 跨链失败 |
cancelled | 订单已取消或失效 |
业务说明
- 平台状态机应屏蔽 provider 原始状态差异，前端只消费统一状态。
sourceTxHash 在用户尚未广播源链交易时可能为空。- 失败场景下建议同时展示
failReason 与下一步处理建议。