SwapBox V2 API

SwapBox is a Intelligent Cross-chain DEX Aggregator, including native-chain Swap, cross-chain Swap, and cross-chain Bridge functionality.

Introduction

SwapBox is a Intelligent Cross-chain DEX Aggregator, including native-chain Swap, cross-chain Swap, and cross-chain Bridge functionality. SwapBox integrates multiple exchange channels to meet various user exchange needs.

This document primarily explains the Nerve relay network exchange channel. This chain facilitates cross-chain exchanges with other blockchain networks. Assets or tokens from other chains are registered on the Nerve chain and then cross-chain to the Nerve chain, where exchanges are completed through NerveSwap (AMM Swap & Multi-Routing) or directly cross-chained to the target chain via Nerve. The successfully exchanged assets are then cross-chained to the target chain's account address.

Currently, the Nerve exchange channel supports EVM-based chains and non-EVM chains, including BTC, Ethereum, BSC, Optimism, Arbitrum, Polygon, etc. More cross-chain support will be added as needed in the future.

The Nerve exchange channel allocates a chain ID (chainId) to each integrated blockchain on the Nerve chain and assigns asset IDs (assetId) to its assets and tokens. (Note: The chainId mentioned here is the chainId assigned by the Nerve chain to other integrated chains, which differs from the EVM chain's own chainId. The nativeId field in subsequent API documentation describes the EVM chain's chainId.)

Assets or tokens on each chain are considered as a type of asset, with each chain having a primary asset, such as Ethereum's ETH token. The primary asset is mainly used to pay transaction fees when assembling transactions.

We also provide the SwapBox js.sdk tool, allowing users to assemble cross-chain exchange transactions through js.sdk.

Request and Response

Domain: https://swapbox.io

RESTful access format: Add request headers:

  • language: en // English, cn // Chinese

  • Content-Type: application/json;charset=UTF-8

  • Accept: application/json

Response Format: Successful Example

{
  "code": 0,         // Return code, 0 indicates success, others indicate failure
  "msg": "Success",  // Return message
  "data": {          // Return data
    "xxxx": xxx
  }
}

Error Example

{
  "code": 1002,
  "msg": "xxxx Error",
  "data": null
}

API Endpoints

Get Chain Configuration

Description: Retrieve the configuration information of all supported chains in Nabox. All applications should call this API to get the chain configuration (chain information and primary asset information) and cache it locally when opening the DApp.

URL: /api/config/chains Method: GET

Parameters: None

Response: Chain Configuration List

{
  "id": 376,
  "nativeId": 1,                // EVM-based chain's chainId
  "chain": "Ethereum",          // Chain abbreviation
  "chainName": "Ethereum",      // Full chain name
  "prefix": "0x",               // Address format prefix
  "chainId": 101,               // ChainId allocated by Nerve chain
  "chainType": 2,               // Chain type: 1 NERVE, 2 EVM, 3 TRON, 4 COSMOS, 5 BTC
  "icon": "https://files.nabox.io/icon/Ethereum.png",  // Chain logo
  "rpcUrl": "https://eth1.lava.build/",               // Default node RPC address
  "apiUrl": null,                                      // Default node API address
  "scanUrl": "https://etherscan.io/",                  // Browser address
  "bridge": 1,                                         // Support cross-chain Bridge
  "swap": 1,                                           // Support exchange
  "sort": 1,
  "status": 1,
  "configs": {                                         // Additional chain configuration
    "multiCallAddress": "0x6899aa1……",  // EVM MultiCall contract address
    "crossAddress": "0xc707e0854d……",   // NerveSwap channel registered cross-chain multi-signature contract address
  },
  "mainAsset": { …… },               // Primary asset information, detailed asset configuration interface
  "recommendAssets": [ …… ],         // Recommended asset list, detailed asset configuration interface
  "rpcUrlList": [ …… ],              // Node RPC-URL list
  "apiUrlList": [ …… ]               // Default node API service URL list
}

Get Swap-able Assets List

Description: Retrieve the list of exchangeable assets supported by SwapBox for the current chain. Only the chain parameter is mandatory. To query a single asset (currency), NULS and NERVE chain assets are uniquely identified by chainId and assetId. For other chains (e.g., EVM chains), when querying the main token, set assetId to 1; for other ERC20 tokens, provide the contractAddress.

URL: /api/config/asset Method: POST

Parameters:

{
  "chain": "BSC",         // Chain abbreviation
  "bridge": "false",      // Whether to only query assets that can use the bridge for cross-chain exchange, default is false
  "chainId": 0,           // ChainId for NULS and Nerve chain assets
  "assetId": 0,           // AssetId for NULS and Nerve chain assets
  "contractAddress": ""   // Contract address for the asset
}

Response: Asset Information List

{
  "id": 174595,
  "nativeId": 56,                // EVM-based chain's original chainId
  "chain": "BSC",                // Chain abbreviation
  "chainType": 2,                // Chain type: 1 Nerve, 2 EVM, 3 TRON, 4 COSMOS
  "chainId": 102,                // ChainId allocated by Nerve chain
  "assetId": 1,                  // Asset ID, main asset ID for EVM chains is fixed at 1, other tokens are 0
  "contractAddress": "",         // Token contract address, required for EVM chain tokens
  "decimals": 18,                // Asset decimal places
  "assetName": "BNB",
  "symbol": "BNB",
  "assetType": 1,                // Asset type: 1 main asset, 2 token asset
  "icon": "https://files.nabox.io/icon/BNB.png",      // Asset logo
  "nerveChainId": 9,
  "nerveAssetId": 25,
  "nulsCross": true,
  "status": 1,
  "sort": 0,
  "source": "NerveSwap",         // Asset data source
  "bridgeInfoList": [ …… ]       // Information on cross-chain assets corresponding to other chains
}

Query Exchange Route (Supports Native-Chain Swap and Cross-Chain Swap)

Description: Based on user input for chain and asset information, this endpoint routes the exchangeable paths for various channels and returns the routing information. If fromChain and toChain parameters are the same, it is an on-chain exchange.

URL: /api/swap/route Method: POST

Parameters:

{
  "dex": "",     // Swap channel: NerveSwap, DODO, MetaPath, OKX, Owlto, Orbiter. Leave empty to query routes for all channels.
  "fromChain": "NERVE",    // Source chain
  "toChain": "NERVE",      // Target chain
  "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",    // Source chain address
  "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",      // Target chain address
  "chainId": 9,            // Chain ID of the source asset
  "assetId": 1,            // Asset ID of the source asset. For main assets on EVM chains, set this value to 1; for other tokens, set to 0.
  "contractAddress": "",   // Contract address of the source asset. Leave empty if the asset is a token.
  "swapChainId": 1,        // Chain ID of the target asset
  "swapAssetId": 1,        // Asset ID of the target asset. For tokens on EVM chains, set this value to 1; for other tokens, set to 0.
  "swapContractAddress": "", // Contract address of the target asset. Leave empty if the asset is a token.
  "amount": "10.25",       // Amount of the source asset
  "slippage": "0.5"        // Slippage
}

Response: List of routing channels

{
  "dex": "NerveSwap",                 // Channel name
  "channel": "NerveSwap",             // Channel path
  "icon": "https://files.nabox.io/icon/nerve-icon.png",    // Channel logo
  "best": 1,                          // Is it the best route? 1: Yes, 0: No
  "orderId": "4bab-2ad2……",           // Order ID for creating orders
  "priceImpact": "0",                 // Price impact
  "approveAddress": "",               // DEX approval contract address
  "fromTokenAmount": 10,              // Amount of the source asset
  "toTokenAmount": "0.33641594",      // Expected amount of the target asset
  "minReceiveAmount": "0.33473386",   // Minimum receivable amount
  "txHash": "1db57ebcc9d21d383a1502f4c1cef4……", // Transaction hash
  "txHex": "3f000795e965243735653264313466……",  // Unsigned transaction hex string
  "from": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",
  "to": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",
  "fee": "0",                         // Exchange fee
  "feeSymbol": "NVT",                 // Fee symbol
  "crossFee": "1.2",                  // Cross-chain fee, usually in the main asset of the source chain or USDT
  "crossFeeSymbol": "NVT",            // Cross-chain fee symbol
  "swapType": 1,                      // 1: Swap, 2: Liquidity, 3: Bridge
  "dodoCrossRoute": {}                // Routing information returned by DODO cross-chain channel, used as a parameter in subsequent interfaces
}

Create Swap Transaction (Supports Native-Chain Swap and Cross-Chain Swap)

Description: Based on user input for channel, chain, and asset information, this endpoint generates an unsigned transaction txHex for the source chain.

URL: /api/swap/tx/encode Method: POST

Parameters:

{
  "dex": "NerveSwap",       // Channel name
  "channel": "NerveSwap",   // Channel path
  "fromChain": "NERVE",     // Source chain
  "toChain": "NERVE",       // Target chain
  "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",    // Source chain address
  "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",      // Target chain address
  "chainId": 9,            // Chain ID of the source asset
  "assetId": 1,            // Asset ID of the source asset. For main assets on EVM and Tron chains, set this value to 1; for other tokens, set to 0.
  "contractAddress": "",   // Contract address of the source asset. Leave empty if the asset is a token.
  "swapChainId": 1,        // Chain ID of the target asset
  "swapAssetId": 1,        // Asset ID of the target asset. For tokens on EVM and Tron chains, set this value to 1; for other tokens, set to 0.
  "swapContractAddress": "", // Contract address of the target asset. Leave empty if the asset is a token.
  "amount": "10.25",       // Amount of the source asset
  "slippage": "0.5",       // Slippage
  "dodoCrossRoute": {      // DODO cross-chain route information, mandatory when the channel is DODO
    "encodeParams": {      // Route information returned by the route interface, encodeParams attribute
      "amount": "string",
      "depositContract": "string",
      "fromAddress": "string",
      "fromChainId": 0,
      "sign": "string",
      "toAddress": "string",
      "toChainId": 0,
      "tokenAddress": "string"
    }
  }
}

Response: Unsigned transaction txHex

{
  "dex": "NerveSwap",       // Channel name
  "channel": "NerveSwap",   // Channel path
  "orderId": "",            // Transaction order ID
  "txData": "",             // Unsigned transaction `txHex`
  "from": "",               // Transaction sender address
  "to": "",                 // Transaction receiver address
  "value": ""               // Amount to be sent by the user in this transaction
}

Submit Swap Order

Description

Check the legality of the chain and swap asset information based on user input and create an order.

URL

POST /api/swap/tx/save

Parameters

{
  "orderId": "4bab-2ad2……",             // Order number returned by the routing interface
  "channel": "",                        // Swap channel; if empty, query routing for all channels
  "platform": "",                       // NERVE channel; channel-specific configuration, default is empty
  "platformToken": "",                  // Channel token; must be provided if platform is not empty
  "fromChain": "NERVE",                 // Source chain
  "toChain": "NERVE",                   // Destination chain
  "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", // Source chain address
  "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",   // Destination chain address
  "chainId": 9,                         // Source chain asset chainId
  "assetId": 1,                         // Source chain asset ID; set to 1 for EVM chain tokens, 0 for others
  "contractAddress": "",                // Source chain asset contract address
  "swapChainId": 1,                     // Destination chain swap asset chainId
  "swapAssetId": 1,                     // Destination chain asset ID; set to 1 for EVM chain tokens, 0 for others
  "swapContractAddress": "",            // Destination chain asset contract address
  "amount": "10.25",                    // Amount of source asset
  "toTokenAmount": "97.113",            // Expected amount after swap
  "slippage": "0.5",                    // Slippage
  "crossFee": "0.003"                   // Cross-chain fee; required for NerveSwap channel swaps
}

Response

{
  "createDate": "2024-03-08 13:59:51",   // Order creation time
  "updateDate": "2024-03-08 13:59:51",
  "versionId": 0,
  "id": 3,
  "orderId": "5b5abad9-0894-43a7-950a-d593e20c8113",  // Order number
  "channel": "DODO",                       // Swap channel
  "platform": "",                          // NerveSwap channel
  "txHash": null,                          // Transaction hash
  "nerveTxHash": null,                     // NerveSwap channel on-chain swap transaction hash
  "crossTxHash": null,                     // Destination chain address receiving swap asset transaction 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",                    // Amount of source asset
  "slippage": "0.5",                     // Slippage
  "toTokenAmount": "0.001",              // Actual swapped amount
  "fee": "0",                            // Swap fee
  "crossFee": "0",                       // NerveSwap channel cross-chain fee
  "crossFeePrice": null,
  "swapType": 0,                         // 1: swap, 2: liquidity, 3: bridge     
  "swapChildType": 0,
  "pairAddress": null,
  "status": 0,                           // 1: User has sent transaction, 2: Processing, 3: Swap successful, 4: Swap failed
  "nerveStatus": 0,
  "ipUrl": ""
}

Update Order Transaction Hash

Description

After the order is created, the front end needs to sign and broadcast the unsigned transaction txHex returned by the routing interface. After successful broadcasting, update the transaction hash to the order.

URL

POST /api/swap/tx/hash/update

Parameters

{
  "orderId": "4bab-2ad2……",             // Order number
  "txHash": "0x0795e96524373565……",   // Broadcasted transaction hash
  "partnerOrderId": "123"              // Partner channel transaction order number, optional
}

Response

Order details

Query Bridge Route (Cross-Chain Bridge)

Description

Based on the user's input for the chain and source chain asset information, query the routing paths available for the Bridge channel and return the routing information.

URL

POST /api/bridge/route

Parameters

{
  "channel": "",                         // Swap channel; if empty, query routing for all channels
  "fromChain": "NERVE",                  // Source chain
  "toChain": "NERVE",                    // Destination chain
  "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", // Source chain address
  "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",   // Destination chain address
  "chainId": 9,                         // Source chain asset chainId
  "assetId": 1,                         // Source chain asset ID; set to 1 for EVM chain tokens, 0 for others
  "contractAddress": "",                // Source chain asset contract address
  "amount": "10.25",                    // Amount of source asset
  "slippage": "0.5"                     // Slippage
}

Response

{
  "channel": "NERVE",                  // Channel name
  "icon": "https://files.nabox.io/icon/nerve-icon.png", // Channel logo
  "best": 1,                           // Whether it is the optimal route; 1 for true, 0 for false
  "orderId": "4bab-2ad2……",           // Order number, used when creating a swap order
  "priceImpact": "0",                  // Price impact
  "approveAddress": "",                // Authorization contract address
  "fromTokenAmount": 10,               // Amount of source asset
  "toTokenAmount": "0.33641594",       // Expected amount after swap
  "minReceiveAmount": "0.33473386",    // Minimum amount to receive
  "txHash": "1db57ebcc9d21d383a1502f4c1cef4……", // Transaction hash
  "txHex": "3f000795e965243735653264313466……",  // Unsigned transaction hex string
  "from": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",
  "to": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",
  "fee": "0",                          // Swap fee
  "feeSymbol": "NVT",                  // Swap fee symbol
  "swapType": 1,                       // 1: Swap, 2: Liquidity, 3: Bridge  
  "dodoCrossRoute": {}                 // Routing information returned by DODO cross-chain channel; used in subsequent interfaces
}

Generate Bridge Transaction (Cross-Chain Bridge)

Description

Based on the user’s input for channel information, chain details, and swap asset information, generate an unsigned transaction txHex for the source chain.

URL

POST /api/bridge/tx/encode

Parameters

{
  "channel": "",                        // Swap channel; if empty, query routing for all channels
  "fromChain": "NERVE",                 // Source chain
  "toChain": "NERVE",                   // Destination chain
  "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", // Source chain address
  "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",   // Destination chain address
  "chainId": 9,                         // Source chain asset chainId
  "assetId": 1,                         // Source chain asset ID; set to 1 for EVM and Tron chain tokens, 0 for others
  "contractAddress": "",                // Source chain asset contract address
  "amount": "10.25",                   // Amount of source asset
  "slippage": "0"                      // Slippage
}

Response

{
  "channel": "",                        // Swap channel
  "orderId": "",                        // Transaction order number
  "txData": "",                         // Unsigned transaction txHex
  "from": "",                           // Transaction sender address
  "to": ""                              // Transaction recipient address
}

Submit Bridge Order

Description

Based on the user's input for the chain and swap asset information, validate the information and create an order.

URL

POST /api/bridge/tx/save

Parameters

{
  "orderId": "4bab-2ad2……",              // Order number, returned by the routing interface
  "channel": "",                         // Swap channel; if empty, query routing for all channels
  "platform": "",                        // NERVE channel; platform configuration, defaults to empty
  "platformToken": "",                   // Platform token; required if platform is not empty
  "fromChain": "NERVE",                  // Source chain
  "toChain": "NERVE",                    // Destination chain
  "fromAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8", // Source chain address
  "toAddress": "NERVEepb6G7qU3rC61x2Ruv3YPFdsHQ4ncyfp8",   // Destination chain address
  "chainId": 9,                         // Source chain asset chainId
  "assetId": 1,                         // Source chain asset ID; set to 1 for EVM chain tokens, 0 for others
  "contractAddress": "",                // Source chain asset contract address
  "amount": "10.25",                    // Amount of source asset
  "toTokenAmount": "97.113",            // Expected amount after swap
  "slippage": "0",                      // Slippage
  "crossFee": "0.003"                   // Cross-chain fee; required for NerveSwap channel
}

Response

{
  "createDate": "2024-03-08 13:59:51", // Order creation time
  "updateDate": "2024-03-08 13:59:51",
  "versionId": 0,
  "id": 3,
  "orderId": "5b5abad9-0894-43a7-950a-d593e20c8113", // Order number
  "channel": "DODO",                      // Swap channel
  "platform": "",                         // NerveSwap channel
  "txHash": null,                         // Transaction hash
  "nerveTxHash": null,                    // NerveSwap channel chain swap transaction hash
  "crossTxHash": null,                    // Destination chain address receive swap asset transaction 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",                   // Amount of source asset
  "slippage": "0.5",                    // Slippage
  "toTokenAmount": "0.001",             // Actual amount after swap
  "fee": "0",                           // Swap fee
  "crossFee": "0",                      // NerveSwap channel cross-chain fee
  "crossFeePrice": null,
  "swapType": 0,                        // 1: Swap, 2: Liquidity, 3: Bridge
  "swapChildType": 0,
  "pairAddress": null,
  "status": 0,                          // 1: User has sent transaction, 2: Processing, 3: Swap successful, 4: Swap failed
  "nerveStatus": 0,
  "ipUrl": ""
}

Update Order Transaction Hash

Description

After the order is created, the frontend needs to sign and broadcast the unsigned transaction txHex returned by the routing interface. Once broadcasting is successful, update the transaction hash to the order.

URL

POST /api/bridge/tx/hash/update

Parameters

{
  "orderId": "4bab-2ad2……",              // Order number
  "txHash": "0x0795e96524373565……",     // Transaction hash after broadcasting
  "partnerOrderId": "123"                // Partner channel transaction order number (optional)
}

Response

{
  // Order details
}

Query Swap and Bridge Order Transactions

Description

Query all swap and bridge order transaction records for the user, sorted in descending order by order time.

URL

POST /api/swap/txs/query

Parameters

{
  "page": 1,                            // Page number, defaults to the first page
  "limit": 10,                          // Number of records per page, defaults to 10, maximum 20
  "chain": "Ethernum",                  // Chain the user is currently connected to (required)
  "address": "0xc707e0854d……",         // User address (required)
  "swapType": 0,                        // Transaction type: defaults to 0 for all; 1: Swap, 2: Liquidity, 3: Bridge
  "status": 0                           // Order status: defaults to 0 for all; 1: Processing, 2: Successful, 3: Failed
}

Response

{
  // List of order transactions
}

Query Swap and Bridge Order Transaction Details

Description

Query the details of a swap or bridge transaction based on the order number.

URL

POST /api/swap/tx/query

Parameters

{
  "orderId": "4bab-2ad2……"    // Transaction order number
}

Response

{
  // Order details
}
PreviousSwapBox V1 SDKNextPayBox Open API

Last updated