Advanced - Integrating SwapKit API
Unlock cross-chain swaps in your application
Last updated
Was this helpful?
Unlock cross-chain swaps in your application
Last updated
Was this helpful?
This documentation is outdated and doesn't correspond to the current release of SwapKit. For the correct documentation please visit
If you want to integrate the API directly, this guide is for you!
In this guide we will walk you through:
Fetching a quote
Setting a token allowance (EVM only)
Performing a swap
You will first need to get a free API key. Please see the page to get in touch.
Those credentials should be added to each request to our services by adding the following to your request headers:
The production API key works for all api.thorswap.net
endpoints, while the development API key works for dev-api.thorswap.net
endpoints. Both environements point at mainnet and real assets, with the dev environement getting new feature requests shipped early for testing.
The code examples in this guide are written in Typescript
To follow along with this guide, you also need to have:
npm
node
private keys for a wallet with some funds
The SwapKit API /quote
endpoint will return an array of quotes for a given trade, ordered by the best return amount.
Let's create a function fetchBestQuote
that will retrieve a quote from the API and pick the best route available.
The quote response contains a lot of information, and we suggest checking out the [API reference], in order to see the full response and get the most out of your integration.
Within the /quote
response there is a transaction
property that can be used in order to make our swap.
The following table shows what the transaction object is for all of the blockchains supported by SwapKit API:
ETH.CRV
BTC.BTC
Swap In
A valid Ethereum transaction object.
BTC.BTC / LTC.LTC / DOGE.DOGE
ETH.CRV
Swap Out
GAIA.ATOM / THOR.RUNE / BNB.BNB
ETH.CRV
Swap Out
A Cosmos TxBody
BCH.BCH
BTC.BTC
THORChain only
The transaction objects different depending on the Sell Asset. It's possible to sign & send each transaction object using the core-libraries of each blockchain ecosystem:
A token allowance is required in order to allow a third-party, in this case a smart contract, to move funds on your behalf. You allow them to move your tokens.
In our case, we need to approve a smart contract to trade our ERC20/ARC20/BEP20 tokens for us. So we will need to approve an allowance (a specified amount) for the smart contract to move the tokens on our behalf. The /quote
response returns the contract that we have to approve in the approvalTarget
property.
The process to do this in code is as follows:
Set the approval amount to maxApproval
or pass in a lower limit.
Use approve()
to give our approvalTarget
an allowance for specified amount.
So let's do it:
Now let's set the approval amount:
Great, we've approved our token for trading! Now let's perform the swap.
First, let's finish off the example where the sellAsset
is an EVM chain, and make a swap from ETH.CRV -> BTC.BTC
The transaction
for this quote will look like the following:
And that's all! We have successfully made a swap from ETH.CRV to native Bitcoin 🥳
First, let's rehydrate the PSBT:
Great! Now we have the wallet's keypair in code, we can sign the inputs for the PSBT, and finalize it!
Then we must extract the transaction object from the PSBT, and broadcast our transaction to the network.
Now we have successfully broadcasted a transaction to swap native BTC on the Bitcoin network, through THORChain, to CRV on Ethereum!
First, let's initialize the CosmosSDK, then get the private keys for our Cosmos wallet, and fetch our address.
Now we can create the AuthInfo object which is required to complete the TxBuilder.
Great! We have built the transaction builder object. Now we can sign the builder using the private key we derived previously, and broadcast the transaction to the RPC we configured when instantiating the SDK.
Whoop! Now we have successfully broadcasted a transaction from the Cosmos blockchain, swapping our ATOM, through THORChain, to RUNE.
As before, we will fetch a quote from the API, specifying our desired trade. In this example, we will be swapping 10 BCH -> BTC.
Now let's pick the inputs & outputs from the 'transaction' property. Then, using bitcoincashjs-lib & coininfo libraries, we will create an instance of the TransactionBuilder.
With the builder, now we can add the inputs & outputs, returned from the API, into the builder. Bitcoincash has 2 different address types, so in order to support both possibilities, we will be using the 'bchaddrjs' library to convert BCH addresses to the legacy format.
Now let's get the private keys for our Bitcoincash wallet, and sign the inputs of our builder, before broadcasting this transaction to the Blockchair API.
Great! Now we have swapped from native BCH on the Bitcoin Cash network, to native BTC on the Bitcoin network; in a totally decentralised way, using THORChain.
This will return a quote like we have seen in . A summary of the trade will be returned, and a transaction object, only if there provided wallet addresses are able to execute the trade.
The SwapKit API returns a transaction
object valid from the blockchain of the sellAsset
. For example, if the sellAsset
is BTC.BTC
the transaction
property will be a hexadecimal string of a .
A hexadecimal string of a .
An object of inputs
and output
used to create a .
Avalanche / Ethereum / Binance Smart Chain - The EVM based chains use or .
Bitcoin / Dogecoin / Litecoin - These UTXO chains use .
Bitcoin Cash - This uses .
Cosmos / THORChain / Binance Beacon Chain - The Cosmos based chains rely on the library.
Connect with the ERC20/ARC20/BEP20 token's approve()
method using or .
All ARC20/BEP20/ERC20 tokens adhere to the same standard, and must implement the function. As mentioned above, this function sets amount
as the allowance of spender
over the caller's tokens; i.e your user's tokens. It returns a boolean value indicating whether the operation was successful.
Now let's take a look at executing the swap, and making our trade. We'll look at a few different examples, one for each of the different type of the SwapKit API will return.
All code examples for the swaps we will cover can be found in our .
As mentioned in , the transaction object returned by the SwapKit API for this scenario is a valid Ethereum transaction. We will use the library to sign and broadcast the transaction from our wallet.
Now we will use the and methods from the library.
As mentioned in , the transaction object returned by the SwapKit API for this scenario is a valid hexadecimal string of a (PSBT). We will use the library to rehydrate the object, sign, and broadcast the transaction from our Bitcoin wallet.
All code examples for the swaps we will cover can be found in our .
Now we'll use the private keys of our Bitcoin wallet to sign the PSBT. There are many methods to do this. I will create my wallets private key using and libraries.
There are different public endpoints available to broadcast your transaction to, below is a snippet using
As mentioned in 'Inspecting the Transaction', the transaction object returned by the THORSwap API for this scenario is a . We will use the library to build the rest of the transaction, sign, and broadcast the transaction to the blockchain!
All code examples for the swaps we will cover can be found in our .
As mentioned in , the 'transaction' object returned when BitcoinCash is the sell asset differs to other UTXO assets. The API returns an object of inputs and outputs in the transaction prop. These are used to create a of the .
All code examples for the swaps we will cover can be found in our .
There are different public endpoints available to broadcast your transaction to, below is a snippet using