# SwapBox V2 接口文档 ## 简言 SwapBox多链资产智能跨链兑换聚合器，包括同链兑换、跨链兑换和跨链Bridge功能。 SwapBox对接了多个兑换通道，能尽量满足用户各种兑换需求。 这里主要说明一下Nerve中继网络兑换通道。该链与其他区块链网络实现跨链兑换，其他链的资产或者Tokens在Nerve链注册并跨链到Nerve链后，在NerveSwap（AMM Swap & Muti-Routing）完成兑换或者直接通过Nerve跨链到目标链。再将成功兑换的资产跨链转出到目标链的账户地址上。 Nerve兑换通道当前已支持（BTC、Ethereum、BSC、Optimism、Arbitrum、Polygon …）EVM系链和非EVM链，未来会根据需要逐渐添加更多跨链支持。 Nerve兑换通道为每个已对接跨链的区块链，在Nerve链上分配了**链ID(chainId)**，并给其链上的资产和Tokens分配了**资产ID(assetId)。(注：这里的chainId是Nerve链给其他集成的链在Nerve链上分配的chainId，区别于EVM系链本身的chainId。EVM系链的chainId会在后续接口文档返回说明的nativeId字段描述。)** 每条链上的资产或者Tokens，我们都视为一种资产，其中每条链都会有一个主资产，例如Ethereum链上的代币（ETH）。主资产主要用于组装交易时，支付手续费。 我们还提供了SwapBox的js.sdk工具，用户可通过js.sdk组装跨链兑换交易。 ### 请求与返回 Domain : [https://swapbox.io](https://api.v2.nabox.io/nabox-api) restful访问格式： 添加请求头: language: en // en英文， cn中文 Content-Type: application/json;charset=UTF-8 Accept: application/json 返回格式： ``` //成功示例 { "code": 0, //返回码，0表示成功，其余表示失败 "msg": "成功", //返回信息 "data": { //返回数据 "xxxx":xxx } } //错误示例 { "code": 1002, "msg": "xxxx错误", "data": null } ``` #### 查询链配置 \*\*详细描述：\*\*查询Nabox当前支持的所有链的配置信息，所有应用，应该在打开DApp时，调用此接口获取链配置（链信息和主资产信息），并缓存在本地。 url: /api/config/chains //get \*\*参数：\*\*无 **返回：链配置列表接口** ``` { "id": 376, "nativeId": 1, //EVM系链的chainId "chain": "Ethereum", //链简称 "chainName": "Ethereum", //链全名 "prefix": "0x", //地址格式前缀 "chainId": 101, //Nerve链给其他对接的链分配的chainId "chainType": 2, //链类型： 1 NERVE系， 2 EVM系， 3 TRON， 4 COSMOS，5 BTC "icon": "https://files.nabox.io/icon/Ethereum.png", //链Logo "rpcUrl": "https://eth1.lava.build/", //默认节点RPC地址 "apiUrl": null, //默认节点API地址 "scanUrl": "https://etherscan.io/", //浏览器地址 "bridge": 1, //是否支持跨链Bridge "swap": 1, //是否支持兑换 "sort": 1, "status": 1, "configs": { //链上额外配置 "multiCallAddress": "0x6899aa1……", //EVM系 MultiCall合约地址 "crossAddress": "0xc707e0854d……", //NerveSwap通道注册跨链的多签合约地址 }, mainAsset:{……}, //主资产信息，详细属性资产配置接口 recommendAssets：[……], //推荐资产列表，详细属性资产配置接口 "rpcUrlList": [……], //节点RPC-URL列表 "apiUrlList": [……] //默认节点API服务接口URL列表 ``` #### 查询兑换资产列表 **详细描述：查询SwapBox支持的当前链可兑换资产列表，其中只有参数chain为必传。** 当需要查询单一资产（币种）时，NULS和NERVE链的资产是通过chainId和assetId来唯一锁定一个资产，其他链（例如EVM链），查询主代币时，assetId传1即可；其余erc20token，传参数contractAddress查询。 参数bridge：默认为”false”，当只需要查询可以使用跨链桥兑换时，该值传“true”。例如ETH链的USDT，跨链到BSC上USDT。通过Bridge的兑换方式，不受滑点影响。 url: /api/config/asset //post **参数：** ``` { "chain": "BSC", //链简称 "bridge": "false", //是否只查询能走bridge跨链桥的资产，默认false "chainId": 0, //NULS和Nerve链资产chainId "assetId": 0, //NULS和Nerve链资产assetId "contractAddress":"" //合约资产地址 } ``` **返回：资产信息列表** ``` { "id": 174595, "nativeId": 56, //EVM系链的原chainId "chain": "BSC", //链简称 "chainType": 2, //链类型:1 Nerve系，2 EVM系，3 TRON系，4 COSMOS系 "chainId": 102, //Nerve链给其他对接的链分配的chainId "assetId": 1, //资产ID, EVM链的主资产ID固定值为1，其余Token为0 "contractAddress": "", //Token合约地址，EVM链的Token需填写，代币则不用填写 "decimals": 18, //资产小数位 "assetName": "BNB", "symbol": "BNB", "assetType": 1, //资产类型: 1 主资产，2 Token资产 "icon": "https://files.nabox.io/icon/BNB.png", //资产Logo "nerveChainId": 9, "nerveAssetId": 25, "nulsCross": true, "status":1， "sort": 0, "source": "NerveSwap", //资产数据来源 "bridgeInfoList":[……] //可跨链的其他链对应资产信息 } ``` #### 查询兑换通道路由（支持本链兑换和跨链兑换） **详细描述：根据用户输入的链和兑换资产信息，路由各个通道可以兑换的路径，并返回路由信息。如果参数的fromChain和toChain一样，就是本链兑换** url: /api/swap/route //post **参数：** ``` { "dex": "", //Swap渠道方： NerveSwap, DODO, MetaPath, OKX, Owlto, Orbiter, 为空时查询所有渠道的路由 "fromChain": "NERVE", //发起链 "toChain": "NERVE", //目标链 "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //发起链地址 "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //目标链地址 "chainId": 9, //发起链资产的chainId "assetId": 1, //发起链资产的id, EVM链的主资产该值需填写1，其余Token为0 "contractAddress": "", //发起链资产的合约地址，若是代币，此字段不填 "swapChainId": 1, //目标链兑换资产的chainId "swapAssetId": 1, //目标链资产的ID, EVM链的代币该值需填写1，其余Token为0 "swapContractAddress": "", //目标链资产的合约地址，若是代币，此字段不填 "amount": "10.25", //发起资产数量 "slippage": "0.5" //滑点 } ``` 返回值：路由通道列表 ``` { "dex": "NerveSwap", //渠道方名称 "channel": "NerveSwap", //渠道方通道名称 "icon": "https://files.nabox.io/icon/nerve-icon.png", //渠道方Logo "best": 1, //是否为最优选路由 1是, 0否 "orderId": "4bab-2ad2……" //订单号，创建订单时使用 "priceImpact": "0", //价格影响 "approveAddress": "" //dex授权合约地址 "fromTokenAmount": 10, //发起资产数量 "toTokenAmount": "0.33641594", //预计可兑换数量 "minReceiveAmount": "0.33473386", //至少可兑换数量 "txHash": "1db57ebcc9d21d383a1502f4c1cef4……", //交易Hash "txHex": "3f000795e965243735653264313466……", //未签名交易Hex串 "from": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", "to": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", "fee": "0", //兑换手续费 "feeSymbol": "NVT", //兑换手续费符号 "crossFee": "1.2", //跨链手续费，一般为发起链主资产，或USDT "crossFeeSymbol": "NVT", //跨链手续费符号 "swapType": 1, //1:Swap, 2:Liquidity, 3:Bridge "dodoCrossRoute": {} //DODO跨链通道返回的路由信息,后续接口会作为参数 } ``` #### 生成兑换交易（支持本链兑换和跨链兑换） **详细描述：根据用户输入的通道信息，链信息和兑换资产信息，生成未签名的发起链交易txHex。** url: /api/swap/tx/encode //post **参数：** ``` { "dex": "NerveSwap", //渠道方名称 "channel": "NerveSwap", //渠道方通道名称 "fromChain": "NERVE", //发起链 "toChain": "NERVE", //目标链 "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //发起链地址 "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //目标链地址 "chainId": 9, //发起链资产的chainId "assetId": 1, //发起链资产的ID, EVM链和Tron链的代币该值需填写1，其余Token为0 "contractAddress": "", //发起链资产的合约地址，若是代币，此字段不填 "swapChainId": 1, //目标链兑换资产的chainId "swapAssetId": 1, //目标链资产的ID, EVM链和Tron链的代币该值需填写1，其余Token为0 "swapContractAddress": "", //目标链资产的合约地址，若是代币，此字段不填 "amount": "10.25", //发起资产数量 "slippage": "0.5" //滑点 "dodoCrossRoute": { //dodo跨链通道的路由信息， 只有当渠道方是dodo时必传 "encodeParams": { //route接口返回的路由信息，encodeParams属性 "amount": "string", "depositContract": "string", "fromAddress": "string", "fromChainId": 0, "sign": "string", "toAddress": "string", "toChainId": 0, "tokenAddress": "string" } } } ``` 返回值：未签名交易txHex ``` { "dex": "NerveSwap", //渠道方名称 "channel": "NerveSwap", //渠道方通道名称 "orderId": "", //交易订单号 "txData": "", //未签名交易txHex "from": "", //交易发起地址 "to": "", //交易接收地址 "value": "" //此次交易，用户需要发起的金额 } ``` #### 提交兑换订单 **详细描述：根据用户输入的链和兑换资产信息，检查合法性并创建订单。** url: /api/swap/tx/save //post **参数：** ``` { "orderId": "4bab-2ad2……" //订单号，路由接口返回的订单号 "channel": "", //兑换通道， 为空时查询所有通道的路由 "platform": "", //NERVE通道，渠道方配置，默认为空 "platformToken":"", //渠道方token，当platform不为空时，必须传对应渠道方的token "fromChain": "NERVE", //发起链 "toChain": "NERVE", //目标链 "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //发起链地址 "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //目标链地址 "chainId": 9, //发起链资产的chainId "assetId": 1, //发起链资产的ID, EVM链的代币该值需填写1，其余Token为0 "contractAddress": "", //发起链资产的合约地址 "swapChainId": 1, //目标链兑换资产的chainId "swapAssetId": 1, //目标链资产的ID, EVM链的代币该值需填写1，其余Token为0 "swapContractAddress": "", //目标链资产的合约地址 "amount": "10.25", //发起资产数量 "toTokenAmount": "97.113", //预计能够兑换到的金额 "slippage": "0.5", //滑点 "crossFee": "0.003" //跨链手续费，NerveSwap通道跨链时需要传此参数 } ``` 返回：订单详情 ``` { "createDate": "2024-03-08 13:59:51", //订单创建时间 "updateDate": "2024-03-08 13:59:51", "versionId": 0, "id": 3, "orderId": "5b5abad9-0894-43a7-950a-d593e20c8113", //订单号 "channel": "DODO", //兑换通道 "platform": "", //NerveSwap兑换渠道 "txHash": null, //交易hash "nerveTxHash": null, //NerveSwap通道链上兑换交易Hash "crossTxHash": null, //目标链地址接收兑换资产交易Hash "fromChain": "BSC", "fromAddress": "0x3b9A2911530a8FD6B3C7265E7d84117D70df845F", "toChain": "BSC", "toAddress": "0x3b9A2911530a8FD6B3C7265E7d84117D70df845F", "chainId": 102, "assetId": 1, "contractAddress": "", "decimal": 18, "symbol": "BNB", "assetIcon": "https://files.nabox.io/icon/BNB.png", "swapChainId": 102, "swapAssetId": 0, "swapContractAddress": "0x8cd6e29d3686d24d3c2018cee54621ea0f89313b", "swapDecimal": 8, "swapSymbol": "NULS", "swapAssetIcon": "http://nassets.oss-us-west-1.aliyuncs.com/NULS_1.png", "amount": "0.0001", //发起资产金额 "slippage": "0.5", //滑点 "toTokenAmount": "0.001", //实际兑换金额 "fee": "0", //兑换手续费 "crossFee": "0", //NerveSwap通道跨链手续费 "crossFeePrice": null, "swapType": 0, //1:swap, 2:liquidity, 3:bridge "swapChildType": 0, "pairAddress": null, "status": 0, //1：用户已发送交易, 2：处理中， 3：兑换成功， 4：兑换失败 "nerveStatus": 0, "ipUrl": "" } ``` #### 更新订单交易Hash **详细描述：订单创建后，前端需要对路由接口返回的未签名的交易txHex进行签名并广播， 广播成功后，将交易hash更新到订单上** url: /api/swap/tx/hash/update //post **参数：** ``` { "orderId": "4bab-2ad2……", //订单号 "txHash": "0x0795e96524373565……" //广播后的交易Hash "partnerOrderId": "123" //合作方通道交易订单号， 非必传 } ``` 返回：订单详情 #### 查询Bridge通道路由（跨链Bridge） **详细描述：根据用户输入的链和发起链资产信息，路由通道可以Bridge的路径，并返回路由信息。** url: /api/bridge/route //post **参数：** ``` { "channel": "", //兑换通道， 为空时查询所有通道的路由 "fromChain": "NERVE", //发起链 "toChain": "NERVE", //目标链 "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //发起链地址 "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //目标链地址 "chainId": 9, //发起链资产的chainId "assetId": 1, //发起链资产的ID, EVM链的代币该值需填写1，其余Token为0 "contractAddress": "", //发起链资产的合约地址 "amount": "10.25", //发起资产数量 "slippage": "0.5" //滑点 } ``` 返回值：路由通道列表 ``` { "channel": "NERVE", //通道名称 "icon": "https://files.nabox.io/icon/nerve-icon.png", //通道Logo "best": 1, //是否为最优选路由 1true, 0false "orderId": "4bab-2ad2……" //订单号，创建兑换订单时使用 "priceImpact": "0", //价格影响 "approveAddress": "" //授权合约地址 "fromTokenAmount": 10, //发起资产数量 "toTokenAmount": "0.33641594", //预计可兑换数量 "minReceiveAmount": "0.33473386", //至少兑换数量 "txHash": "1db57ebcc9d21d383a1502f4c1cef4……", //交易Hash "txHex": "3f000795e965243735653264313466……", //未签名交易hex串 "from": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", "to": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", "fee": "0", //兑换手续费 "feeSymbol": "NVT", //兑换手续费符号 "swapType": 1, //1:Swap, 2:Liquidity, 3:Bridge "dodoCrossRoute": {} //DODO跨链通道返回的路由信息,后续接口会作为参数 } ``` #### 生成Bridge交易（跨链Bridge） **详细描述：根据用户输入的通道信息，链信息和兑换资产信息，生成未签名的发起链交易txHex。** url: /api/bridge/tx/encode //post **参数：** ``` { "channel": "", //兑换通道， 为空时查询所有通道的路由 "fromChain": "NERVE", //发起链 "toChain": "NERVE", //目标链 "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //发起链地址 "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //目标链地址 "chainId": 9, //发起链资产的chainId "assetId": 1, //发起链资产的ID, EVM链和Tron链的代币该值需填写1，其余Token为0 "contractAddress": "", //发起链资产的合约地址 "amount": "10.25", //发起资产数量 "slippage": "0" //滑点 } ``` 返回值：未签名交易txHex ``` { "channel": "", //兑换通道 "orderId": "", //交易订单号 "txData": "", //未签名交易txHex "from": "", //交易发起地址 "to": "" //交易接收地址 } ``` #### 提交Bridge订单 **详细描述：根据用户输入的链和兑换资产信息，检查合法性并创建订单。** url: /api/bridge/tx/save //post **参数：** ``` { "orderId": "4bab-2ad2……" //订单号，路由接口返回的订单号 "channel": "", //兑换通道， 为空时查询所有通道的路由 "platform": "", //NERVE通道，渠道方配置，默认为空 "platformToken":"", //渠道方Token，当Platform不为空时，必须传对应渠道方的Token "fromChain": "NERVE", //发起链 "toChain": "NERVE", //目标链 "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //发起链地址 "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", //目标链地址 "chainId": 9, //发起链资产的chainId "assetId": 1, //发起链资产的ID, EVM链的代币该值需填写1，其余Token为0 "contractAddress": "", //发起链资产的合约地址 "amount": "10.25", //发起资产数量 "toTokenAmount": "97.113", //预计能够兑换到的金额 "slippage": "0", //滑点 "crossFee": "0.003" //跨链手续费，NerveSwap通道跨链时需要传此参数 } ``` 返回：订单详情 ``` { "createDate": "2024-03-08 13:59:51", //订单创建时间 "updateDate": "2024-03-08 13:59:51", "versionId": 0, "id": 3, "orderId": "5b5abad9-0894-43a7-950a-d593e20c8113", //订单号 "channel": "DODO", //兑换通道 "platform": "", //NerveSwap兑换渠道 "txHash": null, //交易Hash "nerveTxHash": null, //Nerve通道链上兑换交易Hash "crossTxHash": null, //目标链地址接收兑换资产交易Hash "fromChain": "BSC", "fromAddress": "0x3b9A2911530a8FD6B3C7265E7d84117D70df845F", "toChain": "BSC", "toAddress": "0x3b9A2911530a8FD6B3C7265E7d84117D70df845F", "chainId": 102, "assetId": 1, "contractAddress": "", "decimal": 18, "symbol": "BNB", "assetIcon": "https://files.nabox.io/icon/BNB.png", "swapChainId": 102, "swapAssetId": 0, "swapContractAddress": "0x8cd6e29d3686d24d3c2018cee54621ea0f89313b", "swapDecimal": 8, "swapSymbol": "NULS", "swapAssetIcon": "http://nassets.oss-us-west-1.aliyuncs.com/NULS_1.png", "amount": "0.0001", //发起资产金额 "slippage": "0.5", //滑点 "toTokenAmount": "0.001", //实际兑换金额 "fee": "0", //兑换手续费 "crossFee": "0", //NerveSwap通道跨链手续费 "crossFeePrice": null, "swapType": 0, //1:Swap, 2:Liquidity, 3:Bridge "swapChildType": 0, "pairAddress": null, "status": 0, //1：用户已发送交易, 2：处理中， 3：兑换成功， 4：兑换失败 "nerveStatus": 0, "ipUrl": "" } ``` #### 更新订单交易Hash **详细描述：订单创建后，前端需要对路由接口返回的未签名的交易txHex进行签名并广播， 广播成功后，将交易hash更新到订单上** url: /api/bridge/tx/hash/update //post **参数：** ``` { "orderId": "4bab-2ad2……", //订单号 "txHash": "0x0795e96524373565……" //广播后的交易Hash "partnerOrderId": "123" //合作方通道交易订单号， 非必传 } ``` 返回：订单详情 #### 查询Swap和Bridge订单交易列表 **详细描述：根据订单时间倒叙查询用户的所有兑换订单交易记录** url: /api/swap/txs/query //post **参数：** ``` { "page": 1, //页数， 默认第一页 "limit": 10, //每页显示条数， 默认10条，最大值20条 "chain": "Ethernum", //用户当前连接的链（必填） "address": "0xc707e0854d……", //用户地址（必填） "swapType": 0, //交易类型：默认0查询所有， 1:Swap, 2:Liquidity, 3:Bridge "status": 0 //订单状态：默认0查询所有， 1：处理中，2：成功，3：失败 } ``` 返回：订单交易列表 #### 查询Swap和Bridge订单交易详情 **详细描述：根据订单号查询兑换交易详情** url: /api/swap/tx/query //post **参数：** ``` { "orderId": "4bab-2ad2……" //交易订单号 } ``` 返回：订单详情