Intermediate

Swap assets between different chains using Crosschain API

This API allows you to exchange assets between different blockchain networks. The current functionality of the API is:

Version: B0.1

This version allows you to convert BUSD on the Ethereum network to BUSD on the Binance network. We believe this is a valuable first step as it serves as a bridge for exchanging assets between the two networks.

The testnets required for running this version are:

Harmony Testnet (https://api.s0.b.hmny.io)
Ethereum Kovan (https://kovan.infura.io/v3/acb534b53d3a47b09d7886064f8e51b6)
Binance Smart Chain Testnet (https://docs.binance.org/smart-chain/developer/rpc.html)

Some Basic Instructions

You will find two folders: “webserver” and “testing”.
“webserver” contains the server that must be started to access the API locally on your machine (refer to detailed instructions for more information).
“testing” contains scripts in JavaScript and Postman that can be used to test the API endpoints once the webserver is running. It also includes examples of API calls.
You need to set up .env files in both folders. Sample files (env_file) are provided for your convenience. Simply rename them to .env.
If you plan to use the .js file in the “testing” folder, you will need to add your private key to the .env file in that folder. If you plan to use Postman, paste your key into the workspace, but make sure to create it outside of the repository.
Remember to add .env files to the .gitignore file and never paste your private keys in the code.

Scripts

Using the Scripts the API

These scripts will create the transactions necessary to call the Harmony production API. For detailed instructions on how to use the API, please refer to the webserver repository.
Please ensure that you rename the env_file to .env and add your private key.
To run a script, simply execute the node file. For example: “node bridge_eth_to_one.js”

The Scripts

bridge_eth_to_one.js This script bridges ethereum BUSD to Harmony’s ethereum BUSD
bridge_one_to_bsc.js This script bridges Harmony’s BSC BUSD to BSC BUSD
viper_swap.js This script swaps Harmony’s ethereum BUSD to Harmony’s BSC BUSD to BSC BUSD
end_to_end.js This script performs a full end-to-end swap from Ethereum BUSD to BSC BUSD

Testing

In order to test the API, you need to complete the following checklist:

Get tokens
Make sure that there is enough liquidity in the BSUD/bscBUSD pool in Viper and/or add liquidity
Start the webserver
Try the examples in this folder!

Getting tokens

You need the following tokens:
- BUSD in the Ethereum Kovan testnet
- Harmony’s ONE tokens (for paying gas)
- Harmony’s BUSD and bscBUSD for adding liquidity

Getting BUSD in the Ethereum Kovan testnet

You can get these tokens from Harmony’s Horizon Bridge Faucet

Getting Harmony’s ONE token

You can get these tokens from the Harmony testnet faucet

Getting Harmony’s BUSD and bscBUSD bridged tokens

For getting Harmony’s BUSD you need to bridge from Ethereum BUSD using Harmony’s Horizon Bridge
For getting Harmony’s bscBUSD you need to bridge from Harmony’s BUSD using ViperSwap

Webserver

This is a webserver using node and express, in order to start it you need to run the following commands in the terminal:

npm install
node index.js

We assume that it will run in port 3000 but feel free to change it. Don’t forget to update the scritps accordingly though.

Endpoints

The general architecture of the API is the following

Endpoints that receive signed transactions as inputs and they will complete the required transactions. This allow you to sign the transactions of the front end and it is safe to use on a production server because the private key is never sent to the endpoints. To sign the transactions you can see the examples in the scripts folder of this repo.
You can make and end-to-end swap using the /swap endpoints. But this is a multi-step process that will fail if one of the single steps fails. It uses Harmony’s Horizon Bridge and Viper DEX, so for example, the bridging part can work but if there is no liquidity in the pool so the who transaction will fail. Therefore use this enpoint only if you are sure that Viper’s LPs have enough liquidity.
If you prefer to do it setp-by-step, you should use the following end-points in the specified order:
- /swap/bridge-in – Bridges BUSD in ethereum to Harmony’s BUSD
- /swap/viper/ – Swaps Harmony’s BUSD to bscBUSD (Both are bridged assets in the Harmony network)
- /swap/bridge-out – Bridges bscBUSD into Binance’s BUSD

Right now the following endpoints are enabled, but we will keep adding more reguarly, so remember to pull once in a while.

`POST /swap`

This endpoint will swap balances between Ethereum BUSD and Binance BUSD, the body for this request should look like this:

Request

{
    "amount" : amount,
    "oneAddress" : oneAddress,
    "ethAddress" : ethAddress
    "lockApproveTxnHash" : approveTxnHash
    "lockTxnHash" : lockTxnHash
    "burnApproveTxnHash" : approveTxnHash
    "depositTxnHash" : depositTxnHash
    "burnTxnHash" : burnTxnHash
    "routerContract" : routerContract
    "fromTokenContract" : fromTokenContract
}

Response

{ 
    trx: "swap", 
    success: bool, 
    error_message: message, 
    error_body: body
}

amount: this is a string with the amount in decimals (e.g. “10.50”) that you want to swap
oneAddress: this is a string with the address of the wallet owned by the private key in the Harmony wallet format i.e. oneaxxxxxxxx
ethAddress: this is a string with the address of the wallet owned by the private key in the Ethereum wallet format i.e. Oxaxxxxxxxx
lockApproveTxnHash : this is a string with the hash of the contract manager’s approval for the lock transaction
lockTxnHash : this is a string with the hash of the lock transaction
burnApproveTxnHash : this is a string with the hash of the contract manager’s approval for the burn transaction
depositTxnHash : this is a string with the hash of the deposit transaction
burnTxnHash : this is a string with the hash of the burn transaction
routerContract : This is a string with the writing approval for Viper’s swap router contract
fromTokenContract : This is a string with the transaction approval for the account swapping in Viper

`POST /swap/bridge-in`

This enpoint will bridges BUSD in ethereum to Harmony’s BUSD, it is the first step of the step-by-step swap, the body for this request should look like this:

Request

{ "amount" : amount, "oneAddress" : oneAddress, "ethAddress" : ethAddress, "lockApproveTxnHash" : approveTxnHash, "lockTxnHash" : lockTxnHash }

Response

{ 
    trx: "bridge", 
    success: bool, 
    error_message: message, 
    error_body: body
}

amount: this is a string with amount in decimals (e.g. “10.50”) that you want to swap
oneAddress: the address of the wallet owned by the private key in the Harmony wallet format i.e. oneaxxxxxxxx
ethAddress: the address of the wallet owned by the private key in the Ethereum wallet format i.e. Oxaxxxxxxxx
lockApproveTxnHash : this is a string with the hash of the contract manager’s approval for the lock transaction
lockTxnHash : this is a string with the hash of the lock transaction

You can see an example of this call in the bridge_eth_to_one.js file in the scripts folder of the repo

`POST /swap/viper`

This enpoint will swap Harmony’s BUSD to bscBUSD (Both are bridged assets in the Harmony network), it is the second step of the step-by-step swap, the body for this request should look like this:

Request

{
    "amount" : amount,
    "oneAddress" : oneAddress,
    "ethAddress" : ethAddress
    "routerContract" : routerContract
    "fromTokenContract" : fromTokenContract
}

Response

{ 
    trx: "viper", 
    success: bool, 
    error_message: message, 
    error_body: body
}

amount: this is a string with amount in decimals (e.g. “10.50”) that you want to swap
wallet: this is the private key of the wallets with the funds, please use an .env or equivalent to store this key, never put it in your code
oneAddress: the address of the wallet owned by the private key in the Harmony wallet format i.e. oneaxxxxxxxx
routerContract : This is a string with the writing approval for Viper’s swap router contract
fromTokenContract : This is a string with the transaction approval for the account swapping in Viper

You can see an example of this call in the viper_swap.js file in the scripts folder of the repo

`POST /swap/bridge-out`

Request

{
    "amount" : amount,
    "oneAddress" : oneAddress,
    "ethAddress" : ethAddress,
    "burnApproveTxnHash" : approveTxnHash,
    "depositTxnHash" : depositTxnHash,
    "burnTxnHash" : burnTxnHash
}

Response

{ 
    trx: "bridge", 
    success: bool, 
    error_message: message, 
    error_body: body
}

amount: this is a string with amount in decimals (e.g. “10.50”) that you want to swap
oneAddress: the address of the wallet owned by the private key in the Harmony wallet format i.e. oneaxxxxxxxx
ethAddress: the address of the wallet owned by the private key in the Ethereum wallet format i.e. Oxaxxxxxxxx
burnApproveTxnHash : this is a string with the hash of the contract manager’s approval for the burn transaction
depositTxnHash : this is a string with the hash of the deposit transaction
burnTxnHash : this is a string with the hash of the burn transaction

You can see an example of this call in the bridge_one_to_bsc.js file in the scripts folder of the repo

Local Endpoints

`POST /local/swap`

This enpoint will swap balances between Ethereum BUSD and Binance BUSD, the body for this request should look like this:

Request

{
    "amount" : amount,
    "wallet" : wallet,
    "oneAddress" : oneAddress,
    "ethAddress" : ethAddress
}

Response

{ 
    trx: "swap", 
    success: bool, 
    error_message: message, 
    error_body: body
}

amount: this is a string with amount in decimals (e.g. “10.50”) that you want to swap
wallet: this is the private key of the wallets with the funds, please use an .env or equivalent to store this key, never put it in your code
oneAddress: the address of the wallet owned by the private key in the Harmony wallet format i.e. oneaxxxxxxxx
ethAddress: the address of the wallet owned by the private key in the Ethereum wallet format i.e. Oxaxxxxxxxx

You can see an example of this call in the swap.js file in the testing folder of the repo

`POST /local/swap/bridge-in`

This enpoint will bridges BUSD in ethereum to Harmony’s BUSD, it is the first step of the step-by-step swap, the body for this request should look like this:

Request

{
    "amount" : amount,
    "wallet" : wallet,
    "oneAddress" : oneAddress,
    "ethAddress" : ethAddress
}

Response

{ 
    trx: "bridge", 
    success: bool, 
    error_message: message, 
    error_body: body
}

amount: this is a string with amount in decimals (e.g. “10.50”) that you want to swap
wallet: this is the private key of the wallets with the funds, please use an .env or equivalent to store this key, never put it in your code
oneAddress: the address of the wallet owned by the private key in the Harmony wallet format i.e. oneaxxxxxxxx
ethAddress: the address of the wallet owned by the private key in the Ethereum wallet format i.e. Oxaxxxxxxxx

You can see an example of this call in the bridge-lock.js file in the testing folder of the repo

`POST /local/swap/viper`

Request

{
    "amount" : amount,
    "wallet" : wallet,
    "oneAddress" : oneAddress,
}

Response

{ 
    trx: "viper", 
    success: bool, 
    error_message: message, 
    error_body: body
}

amount: this is a string with amount in decimals (e.g. “10.50”) that you want to swap
wallet: this is the private key of the wallets with the funds, please use an .env or equivalent to store this key, never put it in your code
oneAddress: the address of the wallet owned by the private key in the Harmony wallet format i.e. oneaxxxxxxxx

You can see an example of this call in the viper.js file in the testing folder of this repo

`POST /local/swap/bridge-out`

This enpoint will bridges bscBUSD into Binance’s BUSD, it is the third step of the step-by-step swap, the body for this request should look like this:

Request

{
    "amount" : amount,
    "wallet" : wallet,
    "oneAddress" : oneAddress,
    "ethAddress" : ethAddress
}

Response

{ 
    trx: "bridge", 
    success: bool, 
    error_message: message, 
    error_body: body
}

amount: this is a string with amount in decimals (e.g. “10.50”) that you want to swap
wallet: this is the private key of the wallets with the funds, please use an .env or equivalent to store this key, never put it in your code
oneAddress: the address of the wallet owned by the private key in the Harmony wallet format i.e. oneaxxxxxxxx
ethAddress: the address of the wallet owned by the private key in the Ethereum wallet format i.e. Oxaxxxxxxxx

You can see an example of this call in the bridge-burn.js file in the testing folder of this repo

Learn

Swap assets between different chains using Crosschain API

Some Basic Instructions

Scripts

Using the Scripts the API

The Scripts

Testing

Getting tokens

Getting BUSD in the Ethereum Kovan testnet

Getting Harmony’s ONE token

Getting Harmony’s BUSD and bscBUSD bridged tokens

Webserver

Endpoints

POST /swap

POST /swap/bridge-in

POST /swap/viper

POST /swap/bridge-out

Local Endpoints

POST /local/swap

POST /local/swap/bridge-in

POST /local/swap/viper

POST /local/swap/bridge-out

Submit Code for Review

`POST /swap`

`POST /swap/bridge-in`

`POST /swap/viper`

`POST /swap/bridge-out`

`POST /local/swap`

`POST /local/swap/bridge-in`

`POST /local/swap/viper`

`POST /local/swap/bridge-out`