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"
- fromCurrencyId - The currency ID of the token you wish to convert tokens from (i.e., the Origin Token).
- 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"
- toCurrencyId - The currency ID of the token you wish to convert tokens to (i.e., the Destination Token).
- 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:
- 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.
- 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.
- User address - the transaction is limited to a specific user.
- 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