订单模式 API
1. 获取兑换价格
接口地址： POST /bgw-pro/swapx/order/getSwapPrice
请求头
| Header | 说明 |
|---|---|
| Content-Type | application/json |
请求体参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fromChain | string | 是 | 源链标识符（例如：“base”、“bnb”、“eth”） |
| fromContract | string | 是 | 源链代币合约地址；主链币地址见 主链币地址 |
| fromAmount | string | 是 | 输入代币数量（以代币单位表示，例如 “2.0” 表示 2 个代币） |
| toChain | string | 是 | 目标链标识符 |
| toContract | string | 是 | 目标链代币合约地址；主链币地址见 主链币地址 |
| fromAddress | string | 是 | 发起兑换的用户地址 |
| toAddress | string | 否 | 如果没有设置默认是 fromAddress。 |
| feeRate | string | 否 | 手续费率，0 或 0.0001~0.02（即 0% 或 0.01%~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"
}响应字段说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| toAmount | string | 预估到账数量 |
| market | string | 推荐使用的市场/跨链桥 |
| slippage | string | 推荐滑点（小数格式，如 “0.03” 表示 3%） |
| priceImpact | string | 价格影响（小数格式） |
| fee | object | 费用预估，可供参考 |
| fee.totalAmountInUsd | string | 总费用（美元） |
| fee.appFee | object | 对接方手续费详情 |
| fee.platformFee | object | 平台费 |
| fee.gasFee | object | Gas 费 |
| fee.lpFee | object | LP 费 |
| fee.swapFee | object | swap 阶段费用 |
| features | []string | 支持 Gas 特性，目前只支持 “no_gas”，表示可用输入代币支付 Gas 费用 |
| eip7702Bound | bool | 是否绑定 EIP7702 合约 |
| eip7702Contract | string | 已绑定合约地址 |
| eip7702IsBgw | bool | 是否是绑定的 BGW EIP7702 合约 |
| tokenInfo | array | 代币信息列表（可选），包含 symbol、address、decimals、price、icon |
2. 创建兑换订单
接口地址： POST /bgw-pro/swapx/order/makeSwapOrder
请求头
| Header | 说明 |
|---|---|
| Content-Type | application/json |
请求体参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| fromChain | string | 是 | 源链标识符（例如：“base”、“bnb”、“eth”） |
| fromContract | string | 是 | 源链代币合约地址；主链币地址见 主链币地址 |
| fromAmount | string | 是 | 输入代币数量（以代币单位表示） |
| toChain | string | 是 | 目标链标识符 |
| toContract | string | 是 | 目标链代币合约地址；主链币地址见 主链币地址 |
| fromAddress | string | 是 | 发起兑换的用户地址 |
| toAddress | string | 是 | 在目标链上接收代币的地址 |
| market | string | 是 | 指定使用的市场/跨链桥（例如：“bkbridgev3.liqbridge”） |
| slippage | string | 否 | 滑点（小数格式，如 “0.03” 表示 3%） |
| feeRate | string | 否 | 手续费率，0 或 0.0001~0.02（即 0% 或 0.01%~2%），未设置时使用渠道默认值 |
| feature | string | 否 | Gas 特性，默认使用用户钱包主链币支付 Gas；如传 “no_gas”，表示使用输入代币支付 Gas。注：需要 getSwapPrice 返回对应特性才能支持。 |
| toMinAmount | string | 否 | 最小到账数量（可选） |
| overrideEip7702 | bool | 否 | 是否允许覆盖已绑定的非 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": {
"toAmount": "1.885815",
"market": "bkbridgev3.liqbridge",
"slippage": "0.03",
"priceImpact": "0.0571",
"features": [],
"eip7702Bound": false,
"eip7702IsBgw": false,
"fee": {
"totalAmountInUsd": "0.114185",
"appFee": { "amountInUsd": "0.1" },
"platformFee": { "amountInUsd": "0.002" },
"gasFee": { "amountInUsd": "0.01" },
"lpFee": { "amountInUsd": "0.002185" },
"swapFee": { "amountInUsd": "0" }
},
"tokenInfo": [
{
"symbol": "USDC",
"address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"decimals": 6,
"price": "0.9998",
"icon": "https://cdn.bitkeep.vip/operation/u_b_usdc.png",
"chain": "base"
},
{
"symbol": "USDT",
"address": "0x55d398326f99059ff775485246999027b3197955",
"decimals": 18,
"price": "0.9999",
"icon": "https://cdn.bitkeep.vip/operation/u_b_usdt.png",
"chain": "bnb"
}
],
"orderId": "34b34a3391da45928f6c9673fba1a4e8",
"toMinAmount": "1.829241",
"deadline": 1772619266,
"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": {
"toAmount": "0.0007",
"market": "bkbridgev3.liqbridge",
"slippage": "0.03",
"priceImpact": "0.001",
"eip7702Bound": true,
"eip7702Contract": "0x8C80e4d123e1A9E787B74a150D3220Dabf327707",
"eip7702IsBgw": true,
"orderId": "ccb8d3f244d64e928ea32f1f8127a7b7",
"toMinAmount": "0.000679",
"deadline": 1770969477,
"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": {
"toAmount": "1.885815",
"market": "bkbridgev3.liqbridge",
"slippage": "0.03",
"priceImpact": "0.0571",
"eip7702Bound": false,
"eip7702IsBgw": false,
"orderId": "11221652138b4ff095871ae267bded4d",
"toMinAmount": "1.829241",
"deadline": 1772632815,
"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"
}响应字段说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| toAmount | string | 预估到账数量，含义同 getSwapPrice |
| market | string | 实际使用的市场/跨链桥，等于请求参数 market |
| slippage | string | 展示用滑点（小数格式）。显式传入时为传入值；未传入或非法时为该 market 的推荐滑点 |
| priceImpact | string | 价格影响（小数格式） |
| features | []string | 可用 Gas 特性列表，含义同 getSwapPrice |
| fee | object | 费用预估，结构同 getSwapPrice 的 fee |
| tokenInfo | array | 代币信息列表（可选），结构同 getSwapPrice |
| orderId | string | 订单 ID，用于后续提交和查询 |
| toMinAmount | string | 二次询价用户收到的最小金额 |
| deadline | int64 | 本次交易数据（txs/signatures）的有效期（unix 秒）。超时后需重新调用 getSwapPrice + makeSwapOrder，使用过期数据 submitSwapOrder 会返回 error_code 80004（订单已过期） |
| txs/signatures | array | 待签名的交易数组 / EIP7702 授权消息签名。txs 和 signatures 只会出现一个，详见下方「txs 和 signatures 字段说明」。 |
| eip7702Bound | bool | 是否已绑定 EIP-7702 合约 |
| eip7702Contract | string | 已绑定的 EIP-7702 合约地址（可选） |
| eip7702IsBgw | bool | 已绑定的 EIP-7702 合约是否为 BGW 合约 |
txs 和 signatures 字段说明
所有操作都遵循以下基本结构：
{
"kind": "transaction | signature",
"chainName": "链名称",
"chainId": "链标识",
"data": {
/* 业务数据字段 */
}
}| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| kind | string | ✅ | 操作类型：transaction（交易）或 signature（签名）。为 signature 时需关注 data.signType 实现对应签名 |
| chainName | string | ✅ | 链名称：ethereum、bsc、base、arbitrum、solana 等 |
| chainId | string | ✅ | 链标识 |
| data | object | ✅ | 操作的详细数据，根据链和操作类型而异 |
3. 提交兑换订单
接口地址： POST /bgw-pro/swapx/order/submitSwapOrder
请求头
| Header | 说明 |
|---|---|
| Content-Type | application/json |
请求体参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderId | string | 是 | 从 makeSwapOrder 接口返回的订单 ID |
| signedTxs | string[] | 是 | 已签名的交易十六进制字符串数组（带 “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"
}响应字段说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| orderId | string | 订单 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-Type | application/json |
请求体参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderId | string | 是 | 要查询的订单 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"
}响应字段说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| orderId | string | 订单 ID |
| status | string | 订单状态，详见「交易状态」 |
| fromChain | string | 源链标识符 |
| fromContract | string | 源链代币合约地址；主链币地址见 主链币地址 |
| fromAmount | string | 发送的代币数量 |
| toChain | string | 目标链标识符 |
| toContract | string | 目标链代币合约地址；主链币地址见 主链币地址 |
| toAmount | string | 预期到账数量 |
| receiveAmount | string | 实际到账数量（订单成功后显示） |
| gasFee | object | 订单上链的 Gas 消耗详情，字段因链而异 |
| gasFee.fee | string | native token 手续费，全链通用 |
| gasFee.gasPrice | string | Gas 单价（EVM 链） |
| gasFee.gasLimit | string | Gas 上限（EVM 链） |
| gasFee.gasUsed | string | 实际消耗 Gas（EVM 链） |
| gasFee.energyUsed | string | 能量消耗（TRX 链） |
| gasFee.netUsed | string | 带宽消耗（TRX 链） |
| txs | array | 交易列表 |
| fee | object | 预估手续费快照，结构见「Fees 说明」 |
| fee.totalAmountInUsd | string | 费用合计（USD） |
| fee.appFee | object | 对接方手续费 |
| fee.platformFee | object | 平台费 |
| fee.gasFee | object | Gas 费 |
| fee.lpFee | object | LP 费 |
| fee.swapFee | object | swap 阶段费用 |
| fee.*.amountInUsd | string | 该费用类型的 USD 合计 |
| fee.*.items | array | 费用明细（可选） |
| fee.*.items[].type | string | 细项类型：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[].token | object | 代币信息（可选）：chain、address、symbol、decimals；可能为空对象 |
| fee.*.items[].amount | string | 代币原始数量（可选） |
| fee.*.items[].amountInUsd | string | USD 金额 |
| message | string | 订单失败（failed）或已退款（refunded）状态下的错误信息 |
| createTime | int64 | 订单创建时间（Unix 时间戳，秒） |
| updateTime | int64 | 订单最后更新时间（Unix 时间戳，秒） |
| tokenInfo | array | 代币信息列表，包含 symbol、address、decimals、price、icon |
| chainInfo | array | 链信息列表，包含 chain、name、icon |
交易对象 (txs[]) 字段说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| chain | string | 交易所在链 |
| txId | string | 交易哈希 |
| stage | string | 交易阶段：source=源链发起的交易, target=目标链收到的交易, swap=同链 swap, bridge=跨链中间阶段, refund=退款的 tx, approve=授权交易 |
| tokens | array | 该 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-Type | application/json |
请求体参数
| 参数名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| orderIds | string[] | 是 | 订单 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"
}响应字段说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| items | array | 查询结果列表，顺序与去重后的请求 orderIds 一致 |
| items[].orderId | string | 订单 ID |
| items[].fee | object | 对账后手续费；结构同 getSwapOrder 的 fee（见「Fees 说明」），但可能只含部分 bucket（如仅 gasFee）。对账未就绪、无费用或无法聚合时为 null |
错误与约束
orderIds为空、超过 50 个、或包含空字符串：error_code80006。- 任一
orderId不存在、不属于当前 partner、或为未进入orders表的 draft 订单：整单失败，error_code80014，不返回部分成功的items（响应中不指明具体哪一笔订单无效）。 - PayFi 订单 ID 不在本接口范围内，按订单不存在处理。
使用建议
- 日常查单、展示交易进度：使用
getSwapOrder。 - 对账、结算、核对实收手续费：使用
checkOrdersFee。 - 单次请求不超过 50 笔，更多订单请分批查询。
6. 获取支持的链列表
接口地址： POST /bgw-pro/swapx/order/chains
返回当前 ToB 订单模式下各链的「同链兑换（Swap）」与「跨链桥接（Bridge）」支持情况，包括各渠道（market）的启用状态、no_gas 能力及跨链限额。
请求头
| Header | 说明 |
|---|---|
| Content-Type | application/json |
请求体参数
无。请求体可为空对象 {}。
请求示例
curl --location '{API_HOST}/bgw-pro/swapx/order/chains' \
--header 'Content-Type: application/json' \
--data '{}'响应示例
{
"status": 0,
"error_code": 0,
"data": {
"chains": [
{
"chainId": "avax_c",
"swap": {
"enabled": true,
"markets": {
"bgwevmaggregator": { "enabled": true, "noGas": false }
}
},
"bridge": {
"enabled": false,
"markets": {}
}
},
{
"chainId": "eth",
"swap": {
"enabled": true,
"noGasMin": "5",
"markets": {
"bgwevmaggregator": { "enabled": true, "noGas": true }
}
},
"bridge": {
"enabled": true,
"noGasMin": "5",
"markets": {
"bkbridgev3.liqbridge": { "enabled": true, "noGas": true, "min": "1", "max": "200000" },
"bkbridgev3.across": { "enabled": true, "noGas": false, "min": "3", "max": "10000" },
"bkbridgev3.cctp": { "enabled": true, "noGas": false, "min": "3", "max": "500000" },
"debridge": { "enabled": true, "noGas": false, "min": "50", "max": "3000000" },
"relaylink": { "enabled": true, "noGas": false, "min": "1", "max": "10000" },
"lifi": { "enabled": true, "noGas": false, "min": "1", "max": "10000" }
}
}
},
{
"chainId": "trx",
"swap": {
"enabled": false,
"markets": {}
},
"bridge": {
"enabled": true,
"noGasMin": "15",
"markets": {
"bkbridgev3.liqbridge": { "enabled": true, "noGas": true, "min": "10", "max": "200000" },
"debridge": { "enabled": true, "noGas": false, "min": "50", "max": "3000000" }
}
}
}
]
},
"msg": "success",
"title": "",
"timestamp": 1782302226553,
"trace": "Root=1-6a3bc612-4ff13a7847e54a5a160ac9fc"
}响应字段说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| chains | array | 支持的链列表，按 chainId 字典序排序 |
| chains[].chainId | string | 链标识，与请求参数中的 fromChain/toChain 取值一致，如 “eth” |
| chains[].swap | object | 同链兑换（fromChain == toChain）支持情况，结构见「ChainCapability 说明」 |
| chains[].bridge | object | 跨链桥接（fromChain != toChain）支持情况，结构见「ChainCapability 说明」 |
ChainCapability 说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| enabled | bool | 该业务（swap/bridge）在该链上是否至少有一个渠道可用 |
| noGasMin | string | 达到该 USD 金额才允许使用 feature=no_gas；没有任何已启用且支持 no_gas 的渠道时省略 |
| markets | object | key 为渠道/market ID（如 “bgwevmaggregator”、“bkbridgev3.liqbridge”），value 为该渠道详情，见「MarketLimit 说明」 |
MarketLimit 说明
| 字段名称 | 类型 | 说明 |
|---|---|---|
| enabled | bool | 该渠道在该链上是否启用；可能因平台策略调整被临时禁用而为 false |
| noGas | bool | 该渠道是否具备 no_gas（Gas 代付）能力；具体某笔交易能否使用仍以下单时的实时校验为准 |
| min | string | 该渠道跨链最低限额（USD），可选；仅 bridge 渠道可能返回，不限制时省略 |
| max | string | 该渠道跨链最高限额（USD），可选；仅 bridge 渠道可能返回，不限制时省略 |
Resources
Fees 说明
费用类型
系统中包含以下几种费用类型：
1. 平台费用 (Platform Fee)
- 说明：平台服务费，用于支持平台运营和维护。
- 计算方式：基于交易金额按百分比收取
- 扣除时机：在跨链桥上链或兑换过程中扣除
- 包含内容：平台服务费
2. 对接方手续费 (App Fee)
- 说明：对接方可以设置的自定义手续费
- 计算方式：
- 按比例：通过
feeRate参数设置百分比，0 或 0.0001~0.02（即 0% 或 0.01%~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 通常更完整。
Last updated on