钱包

arrow_down

闪兑

arrow_down

银行卡

理财

开发者服务arrow_down

更多

arrow_down
activityactivityactivityactivity
  • themelight

  • languageIcon

  • menu
钱包 API
连接钱包
Skip to Content
Zh CnDocs
交易 API
订单模式

订单模式 API

概述

订单模式介绍

本 API 采用 订单模式（Order-based Model） 进行跨链兑换和资产转移。订单模式将整个交易过程分解为多个步骤，提供更好的可追踪性和用户体验。

同链与跨链：订单模式同时支持 同链 swap 和 跨链 兑换。当 fromChain == toChain 时为同链 swap（同一链上的代币兑换）；当 fromChain != toChain 时为跨链兑换或资产转移。请求参数与流程一致，仅根据链是否相同区分业务类型。

请求流程

  1. 获取报价：调用 /bgw-pro/swapx/order/getSwapPrice 获取预估输出数量和手续费
  2. 创建订单：调用 /bgw-pro/swapx/order/makeSwapOrder 创建订单并接收交易数据
  3. 签名交易：让用户使用钱包对交易进行签名
  4. 提交订单：使用已签名的交易调用 /bgw-pro/swapx/order/submitSwapOrder
  5. 监控状态：轮询 /bgw-pro/swapx/order/getSwapOrder 以跟踪订单完成情况
  6. 查询对账手续费（可选）：调用 /bgw-pro/swapx/order/checkOrdersFee 批量获取对账后实收费用

接口列表

API_HOST: https://bopenapi.bgwapi.io

1. 获取兑换价格

接口地址： POST /bgw-pro/swapx/order/getSwapPrice

请求头

Header说明
Content-Typeapplication/json

请求体参数

参数名称类型必填说明
fromChainstring是源链标识符（例如：“base”、“bnb”、“eth”）
fromContractstring是源链上的代币合约地址，主链币为空。
fromAmountstring是输入代币数量（以代币单位表示，例如 “2.0” 表示 2 个代币）
toChainstring是目标链标识符
toContractstring是目标链上的代币合约地址，主链币为空。
fromAddressstring是发起兑换的用户地址
toAddressstring否如果没有设置默认是 fromAddress。
feeRatestring否手续费率，0 或 0.001~0.02（即 0% 或 0.1%~2%），未设置时使用渠道默认值

请求示例

curl --location '{API_HOST}/bgw-pro/swapx/order/getSwapPrice' \
--header 'Content-Type: application/json' \
--data '{
    "fromChain": "base",
    "fromContract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "fromAmount": "2.0",
    "toChain": "bnb",
    "toContract": "0x55d398326f99059ff775485246999027b3197955",
    "fromAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5",
    "feeRate": "0.01"
}'

响应示例

{
  "status": 0,
  "error_code": 0,
  "data": {
    "toAmount": "1.885815",
    "market": "bkbridgev3.liqbridge",
    "slippage": "0",
    "priceImpact": "0.0571",
    "fee": {
      "totalAmountInUsd": "0.114185",
      "appFee": {
        "amountInUsd": "0.1",
        "items": [
          {
            "type": "app_fee",
            "token": {
              "chain": "base",
              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "symbol": "USDC",
              "decimals": 6
            },
            "amount": "0.1",
            "amountInUsd": "0.1"
          }
        ]
      },
      "platformFee": {
        "amountInUsd": "0.002",
        "items": [
          {
            "type": "platform_fee",
            "token": {
              "chain": "base",
              "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
              "symbol": "USDC",
              "decimals": 6
            },
            "amount": "0.002",
            "amountInUsd": "0.002"
          }
        ]
      },
      "gasFee": {
        "amountInUsd": "0.01",
        "items": [
          { "type": "bridge_gas_fee", "amountInUsd": "0.005" },
          { "type": "destination_gas_fee", "amountInUsd": "0.005" }
        ]
      },
      "lpFee": {
        "amountInUsd": "0.002185",
        "items": [
          { "type": "lp_fee", "amountInUsd": "0.002185" }
        ]
      }
    },
    "features": []
  },
  "msg": "success",
  "title": "",
  "timestamp": 1769944578163,
  "trace": "Root=1-697f3600-388d2064762bf6e27f653b29"
}

响应字段说明

字段名称类型说明
toAmountstring预估到账数量
marketstring推荐使用的市场/跨链桥
slippagestring推荐滑点（小数格式，如 “0.03” 表示 3%）
priceImpactstring价格影响（小数格式）
feeobject费用预估，可供参考
fee.totalAmountInUsdstring总费用（美元）
fee.appFeeobject对接方手续费详情
fee.platformFeeobject平台费
fee.gasFeeobjectGas 费
fee.lpFeeobjectLP 费
fee.swapFeeobjectswap 阶段费用
features[]string支持 Gas 特性，目前只支持 “no_gas”，表示可用输入代币支付 Gas 费用
eip7702Boundbool是否绑定 EIP7702 合约
eip7702Contractstring已绑定合约地址
eip7702IsBgwbool是否是绑定的 BGW EIP7702 合约
tokenInfoarray代币信息列表（可选），包含 symbol、address、decimals、price、icon

2. 创建兑换订单

接口地址： POST /bgw-pro/swapx/order/makeSwapOrder

请求头

Header说明
Content-Typeapplication/json

请求体参数

参数名称类型必填说明
fromChainstring是源链标识符（例如：“base”、“bnb”、“eth”）
fromContractstring是源链上的代币合约地址，主链币为空。
fromAmountstring是输入代币数量（以代币单位表示）
toChainstring是目标链标识符
toContractstring是目标链上的代币合约地址，主链币为空。
fromAddressstring是发起兑换的用户地址
toAddressstring是在目标链上接收代币的地址
marketstring是指定使用的市场/跨链桥（例如：“bkbridgev3.liqbridge”）
slippagestring否滑点（小数格式，如 “0.03” 表示 3%）
feeRatestring否手续费率，0 或 0.001~0.02（即 0% 或 0.1%~2%），未设置时使用渠道默认值
featurestring否Gas 特性，默认使用用户钱包主链币支付 Gas；如传 “no_gas”，表示使用输入代币支付 Gas。注：需要 getSwapPrice 返回对应特性才能支持。
toMinAmountstring否最小到账数量（可选）
overrideEip7702bool否是否允许覆盖已绑定的非 BGW EIP-7702 合约（仅 NoGas 场景有效）。客户端应先从 getSwapPrice 响应的 eip7702Bound/eip7702IsBgw 判断，经用户确认后再置此标志。

注意：客户端需自行检查发起交易钱包是否足额的主链币余额；当不足时需使用 “no_gas” 特性，将 feature 参数设置为 “no_gas”。

请求示例

# 普通交易 request
curl --location '{API_HOST}/bgw-pro/swapx/order/makeSwapOrder' \
--header 'Content-Type: application/json' \
--data '{
    "fromChain": "base",
    "fromContract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "fromAmount": "2",
    "toChain": "bnb",
    "toContract": "0x55d398326f99059ff775485246999027b3197955",
    "fromAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5",
    "toAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5",
    "market": "bkbridgev3.liqbridge",
    "slippage": "0.03",
    "feeRate": "0.01"
}'
 
# no_gas (EIP7702) 交易 request
curl --location '{API_HOST}/bgw-pro/swapx/order/makeSwapOrder' \
--header 'Content-Type: application/json' \
--data '{
    "fromChain": "base",
    "fromContract": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "fromAmount": "2",
    "toChain": "bnb",
    "toContract": "0x55d398326f99059ff775485246999027b3197955",
    "fromAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5",
    "toAddress": "0x2E1276244540B7996fbF4F8DF90229BAD36fB4F5",
    "market": "bkbridgev3.liqbridge",
    "slippage": "0.03",
    "feeRate": "0.01",
    "feature": "no_gas"
}'

响应示例

普通交易

{
  "status": 0,
  "error_code": 0,
  "data": {
    "orderId": "34b34a3391da45928f6c9673fba1a4e8",
    "txs": [
      {
        "kind": "transaction",
        "chainName": "base",
        "chainId": "8453",
        "data": {
          "to": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "calldata": "0xa9059cbb000000000000000000000000803f5ebe49485745a94205b1f129f63326d5383600000000000000000000000000000000000000000000000000000000001e8480",
          "gasLimit": "54526",
          "gasPrice": "9000000",
          "nonce": 308,
          "value": "0",
          "baseFee": "5820569",
          "maxFeePerGas": "11139700",
          "maxPriorityFeePerGas": "2408846",
          "supportEIP1559": true
        }
      }
    ]
  },
  "msg": "success",
  "title": "",
  "timestamp": 1772619146682,
  "trace": "Root=1-69a80589-5a8c90f163bf21d31317a994"
}

no_gas (EIP7702) 交易

{
  "status": 0,
  "error_code": 0,
  "data": {
    "orderId": "ccb8d3f244d64e928ea32f1f8127a7b7",
    "signatures": [
      {
        "kind": "signature",
        "chainName": "bnb",
        "chainId": "56",
        "hash": "0xdbcc895aa03a4c3a286d66fdf6a811884b1d1338f2bef8de7855aa9cb301ff32",
        "data": {
          "signType": "eip712",
          "types": {
            "Aggregator": [
              {
                "name": "chainId",
                "type": "uint256"
              },
              {
                "name": "msgSender",
                "type": "address"
              },
              {
                "name": "deadline",
                "type": "uint256"
              },
              {
                "name": "nonce",
                "type": "uint256"
              },
              {
                "name": "adminContract",
                "type": "address"
              },
              {
                "name": "calls",
                "type": "Call[]"
              }
            ],
            "Call": [
              {
                "name": "target",
                "type": "address"
              },
              {
                "name": "value",
                "type": "uint256"
              },
              {
                "name": "callData",
                "type": "bytes"
              }
            ],
            "EIP712Domain": [
              {
                "name": "name",
                "type": "string"
              },
              {
                "name": "version",
                "type": "string"
              },
              {
                "name": "chainId",
                "type": "uint256"
              },
              {
                "name": "verifyingContract",
                "type": "address"
              }
            ]
          },
          "primaryType": "Aggregator",
          "domain": {
            "chainId": "56",
            "name": "BW7702Admin",
            "verifyingContract": "0x8C80e4d123e1A9E787B74a150D3220Dabf327707",
            "version": "1"
          },
          "message": {
            "adminContract": "0x8C80e4d123e1A9E787B74a150D3220Dabf327707",
            "calls": [
              {
                "callData": "0xa9059cbb000000000000000000000000b317d9b4b00c7664381db8f3132c774c3c99398c0000000000000000000000000000000000000000000000000087f027d26b47a8",
                "target": "0x55d398326f99059fF775485246999027B3197955",
                "value": "0"
              },
              {
                "callData": "0xa9059cbb000000000000000000000000e84e684c634f2d9de3b5ea471c092f998f7d8b6e0000000000000000000000000000000000000000000000001b397d3f7c5cb858",
                "target": "0x55d398326f99059fF775485246999027B3197955",
                "value": "0"
              }
            ],
            "chainId": "56",
            "deadline": "1770969477",
            "msgSender": "0x0c1A29c1827cf064e7DB0256625a1b5cc16b246A",
            "nonce": "5770969357001941564"
          }
        }
      }
    ]
  },
  "msg": "success",
  "title": "",
  "timestamp": 1770969357741,
  "trace": "Root=1-698ed90c-0a99621e16d55da149bc0c0c"
}

approve + swap 的交易

{
  "status": 0,
  "error_code": 0,
  "data": {
    "orderId": "11221652138b4ff095871ae267bded4d",
    "txs": [
      {
        "kind": "transaction",
        "chainName": "base",
        "chainId": "8453",
        "data": {
          "to": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
          "calldata": "0x095ea7b30000000000000000000000006d0034c7da87e8f0526b21aa890d40a77c755b68ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
          "gasLimit": "100000",
          "gasPrice": "8121700",
          "nonce": 13,
          "value": "0",
          "baseFee": "5002444",
          "maxFeePerGas": "10003666",
          "maxPriorityFeePerGas": "2500000",
          "supportEIP1559": true
        }
      },
      {
        "kind": "transaction",
        "chainName": "base",
        "chainId": "8453",
        "data": {
          "to": "0x6D0034c7DA87e8f0526b21aa890d40A77C755B68",
          "calldata": "0xd984396a000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000002e00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000833589fcd6edb6e08f4c7c32d4f71b54bda029130000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a793219b9b9219303e718124e1f09f3feca8220a00000000000000000000000000000000000000000000000000000000001e84800000000000000000000000000000000000000000000000000003561a39eca340000000000000000000000000000000000000000000000000000370849ab9e5000000000000000000000000000000000000000000000000000000000069a83aef0000000000000000000000000000000011221652138b4ff095871ae267bded4d0000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001e0bd56bf09cda7260baa5dfdffcfd844d0bc366c9de2091c6aa06c7eb09de449f600000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000041e6fa26b66652b4ff1dcd34be62e9612406c3ea47788d33879223f1ba278ca05b11e491a846dfe03e49a9243dc230ea1d62c8cbf4bf176a319243d82ef3cf444f1b000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000001e000000000000000000000000000000000000000000000000000000000000003600000000000000000000000000000000000000000000000000000000000002710000000000000000000000000000000000000000000000000000000000000000600000000000000000000000000000000000000000000000000000000000000000000000000000000000000006d0034c7da87e8f0526b21aa890d40a77c755b68000000000000000000000000be96d4964d89c17c2c8c4d230313b8b6f7f6507a000000000000000000000000e846373c1a92b167b4e9cd5d8e4d6b1db9e90ec7000000000000000000000000833589fcd6edb6e08f4c7c32d4f71b54bda0291300000000000000000000000060a3e35cc302bfa44cb288bc5a4f316fdb1adb420000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000320000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000000001000000000000000000000000de956dc64264bb60b6abef225432b8a6b68c81ad0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000a07e22067f556af6cb7d6118adaf94647269a14100000000000000000000000060a3e35cc302bfa44cb288bc5a4f316fdb1adb42000000000000000000000000c1cba3fcea344f92d9239c08c0568f6f2f0ee4520000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000027100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000271000000000000000000000000000000000000000000000000000000000000000060000000000000000000000000000000000000000000000000000000000000002000000000000000000000000a793219b9b9219303e718124e1f09f3feca8220a000000000000000000000000de956dc64264bb60b6abef225432b8a6b68c81ad000000000000000000000000667701e51b4d1ca244f17c78f7ab8744b4c99f9b000000000000000000000000c1cba3fcea344f92d9239c08c0568f6f2f0ee452000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000000",
          "gasLimit": "932679",
          "gasPrice": "8121700",
          "nonce": 14,
          "value": "0",
          "baseFee": "5002444",
          "maxFeePerGas": "10003666",
          "maxPriorityFeePerGas": "2500000",
          "supportEIP1559": true
        }
      }
    ]
  },
  "msg": "success",
  "title": "",
  "timestamp": 1772632695884,
  "trace": "Root=1-69a83a77-59bfd5dd5a523e1f1c962760"
}

响应字段说明

字段名称类型说明
orderIdstring订单 ID，用于后续提交和查询
toMinAmountstring二次询价用户收到的最小金额
txs/signaturesarray待签名的交易数组 / EIP7702 授权消息签名。txs 和 signatures 只会出现一个，详见下方「txs 和 signatures 字段说明」。
eip7702Boundbool是否已绑定 EIP-7702 合约
eip7702Contractstring已绑定的 EIP-7702 合约地址（可选）
eip7702IsBgwbool已绑定的 EIP-7702 合约是否为 BGW 合约

txs 和 signatures 字段说明

所有操作都遵循以下基本结构：

{
  "kind": "transaction | signature",
  "chainName": "链名称",
  "chainId": "链标识",
  "data": {
    /* 业务数据字段 */
  }
}
字段类型必填说明
kindstring✅操作类型：transaction（交易）或 signature（签名）。为 signature 时需关注 data.signType 实现对应签名
chainNamestring✅链名称：ethereum、bsc、base、arbitrum、solana 等
chainIdstring✅链标识
dataobject✅操作的详细数据，根据链和操作类型而异

3. 提交兑换订单

接口地址： POST /bgw-pro/swapx/order/submitSwapOrder

请求头

Header说明
Content-Typeapplication/json

请求体参数

参数名称类型必填说明
orderIdstring是从 makeSwapOrder 接口返回的订单 ID
signedTxsstring[]是已签名的交易十六进制字符串数组（带 “0x” 前缀）

请求示例

curl --location '{API_HOST}/bgw-pro/swapx/order/submitSwapOrder' \
--header 'Content-Type: application/json' \
--data '{
    "orderId": "8d07e1afe0b44485a225f9c0c1afb7a4",
    "signedTxs": [
        "0x02f8b282210581f1843b9aca00847735940082d4fe94833589fcd6edb6e08f4c7c32d4f71b54bda0291380b844a9059cbb000000000000000000000000803f5ebe49485745a94205b1f129f63326d5383600000000000000000000000000000000000000000000000000000000001e8480c001a02af477359b2a527b16068e47be735a78da9f99f44188c17f987734ba0d5d750da00326f823a5665e57871935df89b52ad670c4a4108ee27016c8bb1b4580e1b1c4"
    ]
}'
 
# 提交 approve + swap 的交易签名
curl --location '{API_HOST}/bgw-pro/swapx/order/submitSwapOrder' \
--header 'Content-Type: application/json' \
--data '{
    "orderId": "8d07e1afe0b44485a225f9c0c1afb7a4",
    "signedTxs": [
        "0xd4dcc6161a285b3e9cf1ba2ac67e18050b12d5a80584d945c334884a8a904ed171aae6a714c0312151e582818fbece79bf4d0c0f2f641b3b8eb8b956796058441b",
        "0xac47da5accbdaf8c792bae19ac6d8a4d298adc9c1d89403a13fd1160193a1f4b3c55ba9d49875bfae0bbdb6135f63d59165cff274e530320d0add90546cb2cc801"
    ]
}'

响应示例

{
  "status": 0,
  "data": {
    "orderId": "8d07e1afe0b44485a225f9c0c1afb7a4"
  },
  "msg": "success"
}

响应字段说明

字段名称类型说明
orderIdstring订单 ID

4. 查询兑换订单

接口地址： POST /bgw-pro/swapx/order/getSwapOrder

查询订单状态、链上交易及费用信息。响应中的 fee 为下单时的预估手续费快照，不代表对账后实收；对账后费用请使用第 5 节 checkOrdersFee。若订单无费用方案或仍为 draft 状态，可能不返回 fee。

fee 各 bucket 可包含 items 明细，便于在订单详情中展示。items[] 各字段按条可选：token 可能为空对象；token.symbol / token.address 可能为空字符串；amountInStableCoin 为稳定币计价金额（可选）。

请求头

Header说明
Content-Typeapplication/json

请求体参数

参数名称类型必填说明
orderIdstring是要查询的订单 ID

请求示例

curl --location '{API_HOST}/bgw-pro/swapx/order/getSwapOrder' \
--header 'Content-Type: application/json' \
--data '{
    "orderId": "baafe989e8384a41a67da030e6f2535e"
}'

响应示例

{
  "status": 0,
  "error_code": 0,
  "data": {
    "orderId": "6f6704fd522540638a07ccaab375e551",
    "status": "success",
    "fromChain": "base",
    "fromContract": "",
    "fromAmount": "0.003",
    "toChain": "arbitrum",
    "toContract": "",
    "toAmount": "0.00289867",
    "receiveAmount": "0.00289289",
    "gasFee": {
      "fee": "0.00001619722899664",
      "gasPrice": "0.00000000001",
      "gasLimit": "2342997",
      "gasUsed": "1617252"
    },
    "txs": [
      {
        "chain": "base",
        "txId": "0x2a726e8061fcbe035124d886645a9fc190a71e0c4085e371ecb462b22813c3cb",
        "stage": "approve",
        "tokens": [
          {
            "symbol": "DAI",
            "address": "0x50c5725949a6f0c72e6c4a641f24049a917db0cb"
          }
        ]
      },
      {
        "chain": "base",
        "txId": "0x53a34898a989a5b1ef9481cd12c436db63dd1483366079abd97396c47dfd076f",
        "stage": "source",
        "tokens": [
          { "symbol": "ETH", "address": "" },
          { "symbol": "USDC", "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "decimals": 6 }
        ]
      },
      {
        "chain": "base",
        "txId": "0x4e7265aa2a49e26bc16a555c197ea313f8bdda647834e570118f9c6ebda49858",
        "stage": "bridge",
        "tokens": [
          { "symbol": "USDC", "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "decimals": 6 }
        ]
      },
      {
        "chain": "arbitrum",
        "txId": "0xe8a2848897ff8cf80a70694ed5428aff01b54a4df6b9e68db940ad9741ead006",
        "stage": "bridge",
        "tokens": [
          { "symbol": "USDC", "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "decimals": 6 }
        ]
      },
      {
        "chain": "arbitrum",
        "txId": "0x2580cf15947f523193fbb722a55aa829d90aa74ce17c8e3f555f828483cb3475",
        "stage": "target",
        "tokens": [
          { "symbol": "USDC", "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "decimals": 6 },
          { "symbol": "ETH", "address": "" }
        ]
      }
    ],
    "createTime": 1782302199,
    "updateTime": 1782302222,
    "tokenInfo": [
      {
        "symbol": "ETH",
        "address": "",
        "decimals": 18,
        "price": "1677.6631688938198",
        "icon": "https://cdn.bitkeep.vip/operation/u_b_946f8ef0-418c-11ee-aa96-5720907ab25c.png",
        "chain": "base"
      },
      {
        "symbol": "ETH",
        "address": "",
        "decimals": 18,
        "price": "1678.9108978807574",
        "icon": "https://cdn.bitkeep.vip/operation/u_b_3edc5f40-514f-11ee-814d-ff3febb53c37.png",
        "chain": "arbitrum"
      }
    ],
    "chainInfo": [
      {
        "chain": "base",
        "name": "Base",
        "icon": "https://cdn.bitkeep.vip/operation/u_b_29c33610-dbb8-11f0-b308-351c8ea61986.jpeg"
      },
      {
        "chain": "arbitrum",
        "name": "Arbitrum One",
        "icon": "https://cdn.bitkeep.vip/u_b_ba4ee9e0-9afd-11ec-aac8-bf8a172584ab.png"
      }
    ],
    "fee": {
      "totalAmountInUsd": "0.18216335206906316516729207296",
      "appFee": {
        "amountInUsd": "0.050221",
        "items": [
          {
            "type": "app_fee",
            "token": {
              "chain": "base",
              "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "symbol": "USDC",
              "decimals": 6
            },
            "amount": "0.050221",
            "amountInStableCoin": "0.050221",
            "amountInUsd": "0.050221"
          }
        ]
      },
      "platformFee": {
        "amountInUsd": "0.001987",
        "items": [
          {
            "type": "platform_fee",
            "token": {
              "chain": "base",
              "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "symbol": "USDC",
              "decimals": 6
            },
            "amount": "0.001987",
            "amountInStableCoin": "0.001987",
            "amountInUsd": "0.001987"
          }
        ]
      },
      "gasFee": {
        "amountInUsd": "0.08600371100898569816729207296",
        "items": [
          {
            "type": "bridge_gas_fee",
            "token": {
              "chain": "base",
              "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "symbol": "USDC",
              "decimals": 6
            },
            "amount": "0.002331",
            "amountInStableCoin": "0.002331",
            "amountInUsd": "0.002331"
          },
          {
            "type": "destination_gas_fee",
            "token": {
              "chain": "base",
              "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
              "symbol": "USDC",
              "decimals": 6
            },
            "amount": "0.006673",
            "amountInStableCoin": "0.006673",
            "amountInUsd": "0.006673"
          },
          {
            "type": "target_swap_gas_fee",
            "token": {
              "chain": "arbitrum",
              "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
              "symbol": "USDC"
            },
            "amount": "0.07691956918964329",
            "amountInStableCoin": "0.07691956918964329",
            "amountInUsd": "0.07699971100898569816729207296"
          }
        ]
      },
      "lpFee": {
        "amountInUsd": "0.014908",
        "items": [
          {
            "type": "lp_fee",
            "token": {},
            "amountInStableCoin": "0.014908",
            "amountInUsd": "0.014908"
          }
        ]
      },
      "swapFee": {
        "amountInUsd": "0.029043641060077467",
        "items": [
          {
            "type": "source_swap_fee",
            "token": { "chain": "base", "symbol": "ETH", "decimals": 18 },
            "amount": "0.000009",
            "amountInStableCoin": "0.01508866191780822",
            "amountInUsd": "0.01508866191780822"
          },
          {
            "type": "target_swap_fee",
            "token": { "chain": "arbitrum", "symbol": "ETH", "decimals": 18 },
            "amount": "0.000008265574618857",
            "amountInStableCoin": "0.013954979142269247",
            "amountInUsd": "0.013954979142269247"
          }
        ]
      }
    }
  },
  "msg": "success",
  "title": "",
  "timestamp": 1782302226553,
  "trace": "Self=1-6a3bc612-032113cb71c3ada73d6e41d7;Root=1-6a3bc612-4ff13a7847e54a5a160ac9fc"
}

响应字段说明

字段名称类型说明
orderIdstring订单 ID
statusstring订单状态，详见「交易状态」
fromChainstring源链标识符
fromContractstring源链代币合约地址
fromAmountstring发送的代币数量
toChainstring目标链标识符
toContractstring目标链代币合约地址
toAmountstring预期到账数量
receiveAmountstring实际到账数量（订单成功后显示）
gasFeeobject订单上链的 Gas 消耗详情，字段因链而异
gasFee.feestringnative token 手续费，全链通用
gasFee.gasPricestringGas 单价（EVM 链）
gasFee.gasLimitstringGas 上限（EVM 链）
gasFee.gasUsedstring实际消耗 Gas（EVM 链）
gasFee.energyUsedstring能量消耗（TRX 链）
gasFee.netUsedstring带宽消耗（TRX 链）
txsarray交易列表
feeobject预估手续费快照，结构见「Fees 说明」
fee.totalAmountInUsdstring费用合计（USD）
fee.appFeeobject对接方手续费
fee.platformFeeobject平台费
fee.gasFeeobjectGas 费
fee.lpFeeobjectLP 费
fee.swapFeeobjectswap 阶段费用
fee.*.amountInUsdstring该费用类型的 USD 合计
fee.*.itemsarray费用明细（可选）
fee.*.items[].typestring细项类型：app_fee；Gas 类 no_gas_fee、bridge_gas_fee、destination_gas_fee、swap_gas_fee、target_swap_gas_fee、ata_rent_fee 等；桥接平台费 platform_fee；swap fee source_swap_fee、target_swap_fee
fee.*.items[].tokenobject代币信息（可选）：chain、address、symbol、decimals；可能为空对象
fee.*.items[].amountstring代币原始数量（可选）
fee.*.items[].amountInUsdstringUSD 金额
messagestring错误信息（失败时显示）
createTimeint64订单创建时间（Unix 时间戳，秒）
updateTimeint64订单最后更新时间（Unix 时间戳，秒）
tokenInfoarray代币信息列表，包含 symbol、address、decimals、price、icon
chainInfoarray链信息列表，包含 chain、name、icon

交易对象 (txs[]) 字段说明

字段名称类型说明
chainstring交易所在链
txIdstring交易哈希
stagestring交易阶段：source=源链发起的交易, target=目标链收到的交易, swap=同链 swap, bridge=跨链中间阶段, refund=退款的 tx, approve=授权交易
tokensarray该 tx 中涉及到的代币列表（可选），跨链各阶段及退款时填充

交易状态

status说明
init创建了订单，但尚未通过 submitSwapOrder 提交签名
processing进行中
success订单成功
failed订单失败
refunding退款中
refunded已退款

5. 批量查询对账后手续费

接口地址： POST /bgw-pro/swapx/order/checkOrdersFee

批量查询已提交订单的对账后手续费（实收口径），用于对账与结算。仅适用于 ToB 订单模式（/order/*），不包含 PayFi。鉴权方式与其它订单接口相同，见 认证。

与 getSwapOrder 的区别：

接口fee 含义
getSwapOrder下单时预估快照
checkOrdersFee对账后实收

对账结果的 fee 与 getSwapOrder 返回的 fee 对象结构相同（字段名与嵌套方式一致），但各 bucket（appFee / platformFee / gasFee 等）按实收数据出现，未返回的 bucket 表示当前无对账明细，不要默认与预估快照字段一一对应。totalAmountInUsd 为已返回 bucket 的合计。

请求头

Header说明
Content-Typeapplication/json

请求体参数

参数名称类型必填说明
orderIdsstring[]是订单 ID 列表，1～50 个；每个元素为非空字符串；重复 ID 按首次出现顺序去重

请求示例

curl --location '{API_HOST}/bgw-pro/swapx/order/checkOrdersFee' \
--header 'Content-Type: application/json' \
--data '{
    "orderIds": [
        "baafe989e8384a41a67da030e6f2535e"
    ]
}'

响应示例

{
  "status": 0,
  "error_code": 0,
  "data": {
    "items": [
      {
        "orderId": "baafe989e8384a41a67da030e6f2535e",
        "fee": {
          "totalAmountInUsd": "0.017667",
          "gasFee": {
            "amountInUsd": "0.017667",
            "items": [
              {
                "type": "destination_gas_fee",
                "token": {
                  "chain": "base",
                  "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
                  "symbol": "USDC",
                  "decimals": 6
                },
                "amount": "0.009628",
                "amountInUsd": "0.009628"
              },
              {
                "type": "no_gas_fee",
                "token": {
                  "chain": "base",
                  "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  "symbol": "",
                  "decimals": 6
                },
                "amount": "0.008039",
                "amountInUsd": "0.008039"
              },
              {
                "type": "bridge_gas_fee",
                "amount": "0",
                "amountInUsd": "0"
              }
            ]
          }
        }
      }
    ]
  },
  "msg": "success",
  "title": "",
  "timestamp": 1772547586003,
  "trace": "Root=1-69a6ee01-47b275fc4a709e6e349fd7f4"
}

响应字段说明

字段名称类型说明
itemsarray查询结果列表，顺序与去重后的请求 orderIds 一致
items[].orderIdstring订单 ID
items[].feeobject对账后手续费；结构同 getSwapOrder 的 fee（见「Fees 说明」），但可能只含部分 bucket（如仅 gasFee）。对账未就绪、无费用或无法聚合时为 null

错误与约束

  • orderIds 为空、超过 50 个、或包含空字符串：error_code 80006。
  • 任一 orderId 不存在、不属于当前 partner、或为未进入 orders 表的 draft 订单：整单失败，error_code 80014，不返回部分成功的 items（响应中不指明具体哪一笔订单无效）。
  • PayFi 订单 ID 不在本接口范围内，按订单不存在处理。

使用建议

  • 日常查单、展示交易进度：使用 getSwapOrder。
  • 对账、结算、核对实收手续费：使用 checkOrdersFee。
  • 单次请求不超过 50 笔，更多订单请分批查询。

Resources

支持的链列表

  • chainID 为请求参数中的 fromChain 和 toChain
chainschainID是否支持同链是否支持跨链noGas 使用门槛 (USD)
Ethereumeth✅✅5
Solanasol✅✅5
Bscbnb✅✅2
Basebase✅✅5
Arbitrumarbitrum✅✅5
Avalanche-Cavax_c✅❌❌
Trontrx❌✅15
Polygonmatic✅✅5
Morphmorph✅✅1
HyperCorehyperliquid✅✅❌
HyperEvmhyper_evm✅❌❌

当订单金额（USD）≥ 该值时，支持 no_gas 特性（使用输入代币支付 Gas）。

注意： 当 HyperCore 作为 fromChain 时，应答数据中使用 signatures 字段，而不是 txs 字段。签名方式请参考 NoGas 功能文档。

跨链限额

From chainliqBridge 限额CCTP(Fast Mode) 限额CCTP(Standard Mode) 限额relaylink 限额Across 限额DeBridge 限额LiFi 限额
Ethereum1U-200,000U3U-500,000U3U-500,000U1U-10,000U3U-10,000U50U-3,000,000U1U-10,000U
Solana1U-200,000U3U-500,000U3U-500,000U❌11U-10,000U50U-3,000,000U❌
Bsc1U-200,000U❌❌❌3U-10,000U50U-3,000,000U3U-10,000U
Base1U-200,000U3U-500,000U3U-500,000U❌3U-10,000U50U-3,000,000U5U-10,000U
Arbitrum1U-200,000U3U-500,000U3U-500,000U1U-10,000U3U-10,000U50U-3,000,000U3U-10,000U
Polygon1U-50,000U3U-500,000U3U-500,000U1U-10,000U3U-10,000U❌1U-10,000U
Morph5U-50,000U3U-500,000U3U-500,000U1U-10,000U❌❌3U-500U
Tron10U-200,000U❌❌❌❌50U-3,000,000U❌
HyperCore❌❌❌1U-10,000U❌❌❌

Fees 说明

费用类型

系统中包含以下几种费用类型：

1. 平台费用 (Platform Fee)

  • 说明：平台服务费，用于支持平台运营和维护。
  • 计算方式：基于交易金额按百分比收取
  • 扣除时机：在跨链桥上链或兑换过程中扣除
  • 包含内容：平台服务费

2. 对接方手续费 (App Fee)

  • 说明：对接方可以设置的自定义手续费
  • 计算方式：
  • 按比例：通过 feeRate 参数设置百分比，0 或 0.001~0.02（即 0% 或 0.1%~2%）（例如：0.01 表示 1%）
  • 固定金额：支持设置固定金额的手续费
  • 分佣方式：先留在平台方，定期结算
  • 配置位置：在 getSwapPrice 和 makeSwapOrder 请求中通过 feeRate 参数设置

3. LP 费 (LP Fee)

  • 说明：流动性提供者费用，由底层协议收取。
  • 计算方式：基于交易金额按一定比例收取，不同 market 比例有所不同

4. Gas 费 (Gas Fee)

  • 说明：链上交易消耗的网络 Gas 费用，按实际消耗计算。

5. Swap 费 (Swap Fee)

  • 说明：swap 阶段的费用。

各接口 fee 口径

接口fee 含义是否含 items 明细
getSwapPrice询价阶段预估可有
getSwapOrder下单时预估快照可有
checkOrdersFee对账后实收可有

费用结构

费用信息在响应中以 fee 对象返回。以下为汇总示例（常见于 getSwapPrice）：

{
    "fee": {
        "totalAmountInUsd": "0.15",
        "appFee": {
            "amountInUsd": "0.10"
        },
        "platformFee": {
            "amountInUsd": "0.03"
        }
    }
}

getSwapOrder / checkOrdersFee 可在各 bucket 下附带 items 明细。单条明细常见字段为 type、amountInUsd；token、amount 按条可选。appFee / platformFee 示例：

{
    "appFee": {
        "amountInUsd": "0.04221",
        "items": [
            {
                "type": "app_fee",
                "token": {
                    "chain": "base",
                    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                    "symbol": "USDC",
                    "decimals": 6
                },
                "amount": "0.04221",
                "amountInUsd": "0.04221"
            }
        ]
    }
}

getSwapOrder 的 gasFee.items 可能较简略（仅 type + amountInUsd，bridge_gas_fee 可为 0 占位）：

{
    "gasFee": {
        "amountInUsd": "0.017667",
        "items": [
            { "type": "no_gas_fee", "amountInUsd": "0.008039" },
            { "type": "bridge_gas_fee", "amountInUsd": "0" },
            { "type": "destination_gas_fee", "amountInUsd": "0.009628" }
        ]
    }
}

checkOrdersFee 可能只返回已对账的 bucket（例如仅 gasFee），且 items 通常更完整。

错误码说明

  • 所有接口遵循同一套错误码格式，不同报错差别在于返回的 error_code 和 message 不同。
  • 调用方可按以下顺序实现错误处理逻辑：
  1. 判断 HTTP statusCode 是否等于 200，否则直接错误提示
  2. 判断 response 中 status 是否等于 0：若为 0 则解析 data；若为 1 则说明该请求异常，执行下一步
  3. 根据 error_code 匹配下方错误码列表执行对应处理；若遇到不认识的 error_code，全部 fallback 到 80000

错误码列表

错误码说明
80000系统内部错误，接入方无法主动规避，需联系我方排查或重试
80001代币余额不足
80002交易金额低于最小限制
80003交易金额超过最大限制
80004订单已过期
80005流动性不足，当前无法完成交易
80006请求参数非法（格式错误、缺失必填字段、值超出范围等）
80007Partner 不存在或无效
80008反向询价计算未收敛（仅 PayFi Swap 的 minAmountOut 模式）
80009获取代币信息失败（代币不存在或服务异常）
80010获取代币价格或 Gas 价格失败
80011生成交易 calldata 失败（仅 PayFi Swap）
80012询价失败（无可用报价、所有市场均失败等）
80013不支持的链（链配置不存在或无可用市场）
80014订单不存在（Order 模式接口；checkOrdersFee 时任一 orderId 无效则整单失败）
80015订单已提交，不可重复提交（仅 Order 模式接口）
80016主链币余额不足以支付 Gas 费用
80017NoGas 特性对该交易不可用
80018手续费率非法（需为 0 或 0.001~0.02）
80021NoGas 未达到使用门槛
80022风险检查未通过

异常响应示例

{
  "status": 1,
  "error_code": 80000,
  "data": null,
  "msg": "system err",
  "title": "",
  "timestamp": 1769580545990,
  "trace": "Root=1-6979a801-6ba8a7696bc0d4256c5b603c"
}
Last updated on
指令模式Nogas 功能