Articles in this section

Convert API - Ethereum, EOS and Cross Convert

Bancor provides public API methods which take HTTPS requests and return JSON.

Please note that making more than 6 calls per second to the public API, or repeatedly and needlessly fetching excessive amounts of data, can result in your IP being banned.

What is the “Convert” API?

At the very heart of the Bancor Protocol is Bancor's conversion functionality. This unique feature allows you to convert any token to any token in a single and simple action.

You can now access this functionality in a simple API that will build the blockchain transaction. All you need to do with the transaction is use any service to transmit it to the blockchain, such as mycrypto for ethereum or eostoolkit for eos transactions.

 

Basic URL format: 

(POST) https://api.bancor.network/0.1/transactions/convert

 

Request BODY data:

When calling this POST API you will need to pass the transaction information in the call in order to build the correct and valid transaction and send it to the blockchain.

 

Required Data:

  • From currency - we support two options for this value
    • fromCurrencyId - The currency ID of the token you wish to convert tokens from (i.e., the Origin Token). 
      Sample value: "5937d635231e97001f744267"
    • fromCurrencyCode - the currency code for the token you wish to convert from (i.e. the Origin Token). 
      Sample value: "BNT", "ETH", "EOS"
  • To currency - we support two options for this value
    • toCurrencyId - The currency ID of the token you wish to convert tokens to (i.e., the Destination Token). 
      Sample value: "59d745ff90509add31e9db14"
    • toCurrencyCode - the currency code for the token you wish to convert to (i.e. the Destination Token). 
      Sample value: "BNT", "ETH", "EOS"
  • Amount - The number of tokens you wish to convert. This value needs to be a true representative of the units of token you wish to receive. 
    Sample value: 
    • To convert 1 ETH, value=1
    • To convert 0.001 ETH, value=0.001
    • To convert 1 ethereum Wei, value=0.000000000000000001
  • MinimumReturn - The minimum amount of destination tokens you are willing to accept in return for the transaction. If you are using affiliate fee, make sure you are taking the fee into consideration when calculating the minimum return value.
    This safety mechanism serves the user as a protection tool to prevent from executing transactions when conditions change dramatically between the time the transaction was created to the time it got minded on the blockchain.
    This value needs to be a true representative of the units of token you wish to receive. 
    Sample value: 
    • To receive at least (minimum) 1 ETH, value=1
    • To receive at least (minimum) 0.001 ETH, value=0.001
    • To receive at least (minimum) 1 ethereum Wei, value=0.000000000000000001
  • OwnerAddress - The address of the wallet executing the transaction. The address of the wallet that contains the "Origin Tokens" that you wish to convert. The converter will return the "Destination Tokens" back to this address at the end of the process.
    We support addresses of both ethereum and EOS blockchain
    Sample value:
    • Ethereum address: "0x5f7a009664b771e889751f4fd721adc439033ecd"
    • EOS address: "bnr111111213"
  • Format - "serialized"/"json" defines the output format of an EOS transaction. Default is "serialized".

Optional Data - Affiliate fee 

Bancor convert API now supports the option to collect affiliate fees from activity on the Bancor Liquidity Network. By adding these two values to the API call, you will be able to collect fees from every transaction you generate using the API. The fee will be transferred to the defined wallet address as BNT tokens.

  • affiliateFee - the fee you wish to take from the transaction as an affiliate. Value should be passed as a decimal between 0-3.0000. For example, pass 1.5 if the fee is set to 1.5%.
  • affiliateAccount - the recipient account that collects the affiliate fee from the transaction. Currently we support an Ethereum wallet address in this field. Please pass a valid Ethereum wallet. You will see an error if the wallet format is not valid.

Important - if you use the Value API to calculate price estimation before calling the Convert API, make sure you calculate the fee in the values you receive. This is also true for the minimum return value you pass.

How to send "Required Data" & "Optional Data"?

Include the values in the body of the API call.

Sample Ethereum convert:

{
 "fromCurrencyId": "5c9a078447a87f2e3cf10787",
 "toCurrencyId": "5c9a078447a87f2e3cf107dc",
 "amount": "1.0",
 "minimumReturn": "1.28353582031457",
 "ownerAddress": "0xfe3cff57b8c01b3ec244e4f62fee038eb94214af",
 "format": "json"
 "affiliateFee": "1.5",
 "affiliateAccount":"0x5f7a009664B771E889751f4FD721aDc439033ECD" 
}

Sample Eos convert:

{
 "fromCurrencyId": "5c9a078447a87f2e3cf108d1",
 "toCurrencyId": "5c9a078c47a87f2e3cf10a98",
 "amount": "1.0",
 "minimumReturn": "28.1726",
 "ownerAddress": "bnr453553512",
 "format": "serialized"
}

Sample Ethereum convert using token code:

{
 "fromCurrencyCode": "ETH",
 "toCurrencyCode": "BNT",
 "amount": "1.0",
 "minimumReturn": "0.005780243088916663",
 "ownerAddress": "0xfe3cff57b8c01b3ec244e4f62fee038eb94214af",
 "format": "serialized"
 "affiliateFee": "1.5",
 "affiliateAccount":"0x5f7a009664B771E889751f4FD721aDc439033ECD" 
}

 

Sample API Response:

After calling the "Convert" API with the correct values, you will receive the transaction that can now be sent to the relevant blockchain.

 

{
 "data": [{
 "blockchain":

{
 "type": "ethereum"
 },
 "data": {
 "transaction":

{
 "from": "0xfe3cff57b8c01b3ec244e4f62fee038eb94214af",
 "to": "0xbeb2cd9f1c3eac46335e5e1e2a132ce253591d74",
 "value": "0xde0b6b3a7640000",
 "data": "0x2274256400000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000de0b6b3a764000000000000000000000000000000000000000000000000000011d009073256ed10000000000000000000000000000000000000000000000000000000000000b969000000000000000000000000000000000000000000000000000000000000001c1bebd4ac5a368185804156f15b18947acb8f9b8cb0bfdbb85e77ca3319ce421a4a9820e6a586e895227dce3a7fc292caf43bee4060c0e1d135db8159cbc1d4520000000000000000000000000000000000000000000000000000000000000003000000000000000000000000065447995a0df677f8c488bffcf80a85314d62070000000000000000000000004c10eb409210ff75ac5bb108b794ee31a84ab7610000000000000000000000004c10eb409210ff75ac5bb108b794ee31a84ab761",
 "gasPrice": "0xb2d05e00",
 "gas": "0x5b954",
 "nonce": "0x1"
 },
 "chainId": "mainnet"
 },
 "_id": "5cab0b0ee6de2549ee371853"
 }]
}

Values and meanings:

  • Blockchain - Indicates the relevant blockchain the transaction is based on. The response can be "ethereum" or "eos"
  • Data - This is the data of the transaction you will need to use on the blockchain. The structure and information is slightly different for each blockchain.

 

Hashed Values

Bancor uses a prioritization mechanism to enable transactions to be executed in the correct and valid order. Changing any of these values will cause the transaction to fail:

  1. Block number - we initiate a transaction life of X blocks. Meaning, from the moment you create the transaction you have X amount of blocks to execute it. Executing it after the transaction lifetime will cause the transaction to fail.
  2. Gas price - the gas price received is part of the transaction's hard-coded values. Changing the gas price will cause the transaction to fail.
  3. User address - the transaction is limited to a specific user.
  4. Nonce - transaction is limited to a specific nonce.

Send the transaction to the blockchain:

At this stage, you have the correct transaction created by our server and you will need to transmit it into the relevant blockchain.

 

-----

Keep in mind:

The Bancor API is currently in alpha and may experience downtime, be upgraded, or suffer from high latency.

We offer several developer APIs, for more information please visit our API Documentation

 

Was this article helpful?
3 out of 4 found this helpful
Have more questions? Submit a request
Return to top
Disclaimer: When reading this article, please keep in mind the following: (1) Important to notice that wherever referring to any sensitive information of yours, including private keys, key-pairs or other account information, that information is yours. We can only make limited suggestions to how such information may be treated and protected, but the responsibility is yours. You should always make sure your information is protected and kept private, in the best available way; (2) that the information contained herein is a simplified extract of detailed information and sources generally available on the internet. This basic information was collected and displayed in attempt to provide you with better understanding of certain processes and aspects which relate to content and applications on Bancor’s site. Although we do our best to keep this information up-to-date, we cannot always guaranty that. This is since the information originates from third parties or relates to third party services, applications and technologies (such as Metamask, Scatter, EOSToolkit, or EOS), which are unrelated or unaffiliated with Bancor. These third parties’ applications, services and technologies are available on the internet, and may be subjected to applicable terms and conditions. Accordingly, though the said information and third applications, services and technologies (“Third Parties Content”) are believed to be reliable, Bancor provides no warranties regarding them (including their accuracy or completeness). IN NO EVENT WILL BANCOR BE LIABLE FOR ANY SPECIAL, INDIRECT, INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING, WITHOUT LIMITATION, LOST REVENUES, LOST PROFITS OR LOSS OF PROSPECTIVE ECONOMIC ADVANTAGE RESULTING FROM THE USE OF THE THIRD PARTIES CONTENT EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANOTHER PARTY.

Related articles