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

# SwapBox V2 API

## 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**

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

**Error Example**

```json
{
  "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

```json
{
  "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:**

```json
{
  "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

```json
{
  "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**:

```json
{
  "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

```json
{
  "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**:

```json
{
  "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`

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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**

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

**Response**

```json
{
  // 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**

```json
{
  "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**

```json
{
  // 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**

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

**Response**

```json
{
  // Order details
}
```
