Advanced - Integrating SwapKit API
Unlock cross-chain swaps in your application
The best way to integrate the SwapKit API is through the SwapKit SDK. For more information about that, refer to our other guide.
If you want to integrate the API directly, this guide is for you!
In this guide we will walk you through:
- 1.Fetching a quote
- 2.Setting a token allowance (EVM only)
- 3.Performing a swap
The code examples in this guide are written in
TypescriptTo 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. For more info about the endpoint look at
Let's create a function
fetchBestQuote that will retrieve a quote from the API and pick the best route available.const fetchBestQuote = async ({
amount,
fromAsset,
toAsset,
senderAddress,
recipientAddress,
provider,
}) => {
try {
const THORSWAP_QUOTE_BASE_URL =
'https://api.thorswap.net/aggregator/tokens/quote'
const thorswapApiUrl = new URL(THORSWAP_QUOTE_BASE_URL)
thorswapApiUrl.searchParams.append('sellAsset', fromAsset)
thorswapApiUrl.searchParams.append('buyAsset', toAsset)
thorswapApiUrl.searchParams.append('sellAmount', amount)
thorswapApiUrl.searchParams.append('senderAddress', senderAddress)
thorswapApiUrl.searchParams.append('recipientAddress', recipientAddress)
thorswapApiUrl.searchParams.append('providers', provider)
thorswapApiUrl.searchParams.append('providers', 'THORCHAIN')
const response = await fetch(thorswapApiUrl.toString())
const data = await response.json()
const bestRoute = data.routes[0]
return bestRoute
} catch (error) {
console.error(error)
}
}
This will return a quote like we have seen in Requesting a Quote. 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 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 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 Partially Signed Bitcoin Transaction (PSBT).The following table shows what the transaction object is for all of the blockchains supported by SwapKit API:
Sell Asset | Buy Asset | Scenario | What is Transaction? |
|---|---|---|---|
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:
- Cosmos / THORChain / Binance Beacon Chain - The Cosmos based chains rely on the Cosmos Client library.
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.
This step is only required if you are swapping from an EVM chain. For example, ETH.CRV -> ETH.UNI, and ETH.THOR -> BTC.BTC, etc.
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:
All ARC20/BEP20/ERC20 tokens adhere to the same standard, and must implement the approve(address spender, uint256 amount) 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.So let's do it:
import Web3 from 'web3';
const web3 = new Web3(Web3.givenProvider);
const erc20abi = [...];
const fromTokenAddress = bestRoute.calldata.token;
const ERC20TokenContract = new web3.eth.Contract(erc20abi, fromTokenAddress);
Now let's set the approval amount:
//
const maxApproval = new BigNumber(2).pow(256).minus(1);
const approveTxEncoded = await ERC20TokenContract.methods.approve(
bestRoute.approvalTarget,
maxApproval,
).encodeABI();
const approveTx = {
to: fromTokenAddress,
data: approveTxEncoded,
gas: 300000,
type: 0,
};
const signedApproveTx = await web3.eth.accounts.signTransaction(approveTx, ETH_PRIVATE_KEY);
const approveTxHash = await web3.eth.sendSignedTransaction(signedApproveTx.rawTransaction);
Great, we've approved our token for trading! Now let's perform the swap.
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 transaction objects the SwapKit API will return.
First, let's finish off the example where the
sellAsset is an EVM chain, and make a swap from ETH.CRV -> BTC.BTCAs mentioned in 'Inspecting the Transaction', the transaction object returned by the SwapKit API for this scenario is a valid Ethereum transaction. We will use the web3js library to sign and broadcast the transaction from our wallet.
The
transaction for this quote will look like the following:// Example transaction object
{
"to": "0xd31f7e39afECEc4855fecc51b693F9A0Cec49fd2",
"from": "0xA58818F1cA5A7DD524Eca1F89E2325e15BAD6cc4",
"value": "0x0",
"gas": "273217",
"gasPrice": "18000000000",
"nonce": "272",
"data": "0x0701c374000000000000000000000000d37bbe5744d730a1d98d8dc97c42f0ca46ad7146000000000000000000000000ff772b437e0c20d46722d67fdb973d70fd46cece00000000000000000000000000000000000000000000000000000000000001000000000000000000000000001f9840a85d5af5bf1d1762f925bdaddc4201f9840000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000001111111254fb6c44bac0bed2854e76f90643097d000000000000000000000000000000000000000000000000000000000000018000000000000000000000000000000000000000000",
}
The transaction object includes suggested
gas (the gas limit) & gasPrice.// doSwapIn.ts
import Web3 from 'web3'
import { Transaction } from '@ethereumjs/tx'
...
// Initialize web3 instance
const web3 = new Web3(new Web3.providers.HttpProvider(INFURA_HTTP_URL))
// This buffer will be used to sign the transaction
const privateKeyBuffer = Buffer.from(ETH_PRIVATE_KEY, 'hex')
// Create Transaction object
const tx = new Transaction(transaction)
// Sign it
const signedTx = tx.sign(privateKeyBuffer)
// Serialize it
const serializedTx = signedTx.serialize()
// Send it & log the receipt
await web3.eth.sendSignedTransaction('0x' + serializedTx.toString('hex')).on('receipt', console.log);
console.log('Swap complete!')
And that's all! We have successfully made a swap from ETH.CRV to native Bitcoin 🥳
As mentioned in 'Inspecting the Transaction', the transaction object returned by the SwapKit API for this scenario is a valid hexadecimal string of a Partially Signed Bitcoin Transaction (PSBT). We will use the bitcoinjs-lib library to rehydrate the object, sign, and broadcast the transaction from our Bitcoin wallet.
First, let's rehydrate the PSBT:
// doSwapBtc.ts
import { Psbt } from 'bitcoinjs-lib'
// Fetch the quote and pick the transaction property
const bestRoute = await fetchBestQuote({
amount,
fromAsset,
toAsset,
senderAddress,
recipientAddress,
provider,
})
const bestRouteTransaction = bestRoute.transaction
// Use Psbt utils to rehydrate
const psbt = Psbt.fromHex(bestRouteTransaction)
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 ecpair and tiny-secp256k libraries.
// doSwapBtc.ts
import * as ECPair from 'ecpair'
import * as tinysecp256k1 from 'tiny-secp256k1';
...
const ec = ECPair.ECPairFactory(tinysecp256k1)
const ecpair = ec.fromWIF(BTC_PRIVATE_KEY, btcNetwork)
Great! Now we have the wallet's keypair in code, we can sign the inputs for the PSBT, and finalize it!
...
// Sign the inputs of the PSBT & finalize
const signedPsbt = psbt.signAllInputs(ecpair)
const finalizedPsbt = signedPsbt.finalizeAllInputs()
Then we must extract the transaction object from the PSBT, and broadcast our transaction to the network.
...
// Extract the transaction
const tx = finalizedPsbt.extractTransaction()
// Broadcast the hex of the transaction
const txHash = await broadcastTx({ txHex: tx.toHex(), chain: 'bitcoin' })
console.log('Transaction Broadcasted!')
console.log(`Transaction hash: ${txHash}`)
There are different public endpoints available to broadcast your transaction to, below is a snippet using Blockchair's API
const broadcastTx = async ({ txHex, chain }: { txHex: string; chain: string; }) => {
try {
const url = new URL(`https://api.blockchair.com/${chain}/push/transaction`)
const response = await fetch(url.toString(), {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
data: txHex
})
})
console.log('Response: ', response)
const data = await response.json();
if (data.context.code !== 200) throw new Error('Fail to broadcast')
return data
} catch (error) {
console.error('Failed to broadcast transaction : ', error)
}
}
Now we have successfully broadcasted a transaction to swap native BTC on the Bitcoin network, through THORChain, to CRV on Ethereum!
As mentioned in 'Inspecting the Transaction', the transaction object returned by the THORSwap API for this scenario is a Cosmos TxBody. We will use the Cosmos Client library to build the rest of the transaction, sign, and broadcast the transaction to the blockchain!
First, let's initialize the CosmosSDK, then get the private keys for our Cosmos wallet, and fetch our address.
// doSwapAtom.ts
import { cosmosclient, proto, rest } from '@cosmos-client/core';
// Call fetchBestQuote above
const bestRoute = await fetchBestQuote({
amount,
fromAsset,
toAsset,
senderAddress,
recipientAddress,
provider,
})
// Pick the transaction body
const txBody = bestRoute.transaction
// Init SDK
const sdk = new cosmosclient.CosmosSDK(`https://cosmos-mainnet-rpc.allthatnode.com:1317`, 'cosmoshub-4')
// Get private key from mnemonic phrase
const privKey = new proto.cosmos.crypto.secp256k1.PrivKey({
key: await cosmosclient.generatePrivKeyFromMnemonic(MNEMONIC)
})
const pubKey = privKey.pubKey()
// Get the wallet address
const address = cosmosclient.AccAddress.fromPublicKey(pubKey)
// Fetch account details
const account = await rest.auth
.account(sdk, address)
.then((res) => cosmosclient.codec.protoJSONToInstance(cosmosclient.codec.castProtoJSONOfProtoAny(res.data.account)))
.catch((_) => undefined);
if (!(account instanceof proto.cosmos.auth.v1beta1.BaseAccount)) {
console.log('Something went wrong');
return;
}
Now we can create the AuthInfo object which is required to complete the TxBuilder.
...
// Create AuthInfo details required in TxBuilder
const authInfo = new proto.cosmos.tx.v1beta1.AuthInfo({
signer_infos: [
{
public_key: cosmosclient.codec.instanceToProtoAny(pubKey),
mode_info: {
single: {
mode: proto.cosmos.tx.signing.v1beta1.SignMode.SIGN_MODE_DIRECT,
},
},
sequence: account.sequence,
},
],
fee: new proto.cosmos.tx.v1beta1.Fee({
amount: [{ denom: 'uatom', amount: '5000' }],
gas_limit: Long.fromString('200000'),
}),
});
// Create the TxBuilder object.
const txBuilder = new cosmosclient.TxBuilder(sdk, txBody, authInfo)
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.
...
// Sign the transaction using private key
const signDocBytes = txBuilder.signDocBytes(account.account_number)
txBuilder.addSignature(privKey.sign(signDocBytes))
// Broadcast the transaction to RPC
const res = await rest.tx.broadcastTx(sdk, {
tx_bytes: txBuilder.txBytes(),
mode: rest.tx.BroadcastTxMode.Block,
})
console.log(`Transaction broadcasted!`)
console.log(`Transaction hash: ${res.data.tx_response.txhash}`)
Whoop! Now we have successfully broadcasted a transaction from the Cosmos blockchain, swapping our ATOM, through THORChain, to RUNE.
As mentioned in 'Inspecting the Transaction', 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 Transaction Builder of the bitcoincashjs-lib.
As before, we will fetch a quote from the API, specifying our desired trade. In this example, we will be swapping 10 BCH -> BTC.
// doSwapBch.ts
// Fetch JSON response from /quote endpoint
const bestRoute = await fetchBestQuote({
amount: 10,
fromAsset: 'BCH.BCH',
toAsset: 'BTC.BTC',
senderAddress: '<my BCH address>',
recipientAddress: '<my BTC address>',
provider: 'THORCHAIN'
})
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.
import * as bitcoincash from "bitcoincashjs-lib"
import coininfo from "coininfo"
...
const { inputs, outputs } = bestRoute.transaction
// Get the BCH Network details
const bchNetwork = coininfo.bitcoincash.main.toBitcoinJS()
const builder = new bitcoincash.TransactionBuilder(bchNetwork)
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.
...
import { toLegacyAddress } from 'bchaddrjs';
...
// Add inputs to builder
inputs.forEach((input) =>
builder.addInput(
bitcoincash.Transaction.fromBuffer(Buffer.from(input.txHex, "hex")),
input.index
)
);
// Add outputs to builder
outputs.forEach((output) => {
let out = undefined;
if (!output.address) {
//an empty address means this is the change address
out = bitcoincash.address.toOutputScript(
toLegacyAddress(senderAddress),
bchNetwork
);
} else if (output.address) {
out = bitcoincash.address.toOutputScript(
toLegacyAddress(output.address),
bchNetwork
);
}
builder.addOutput(out, output.value);
});
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.
import * as ECPair from "ecpair";
import * as tinysecp256k1 from "tiny-secp256k1";
...
// Recreate wallet keys
const ec = ECPair.ECPairFactory(tinysecp256k1);
const ecpair = ec.fromWIF(BCH_PRIVATE_KEY, bchNetwork);
// Sign inputs
inputs.forEach((utxo, index) => {
builder.sign(index, ecpair, undefined, 0x41, utxo.witnessUtxo.value);
});
// Build TransactionBuilder
const tx = builder.build().toHex();
// // Broadcast the hex of the transaction
const txHash = await broadcastTx({ txHex: tx, chain: "bitcoin-cash" });
console.log("Transaction Broadcasted!");
console.log(`Transaction hash: ${txHash}`);
There are different public endpoints available to broadcast your transaction to, below is a snippet using Blockchair's API
const broadcastTx = async ({ txHex, chain }: { txHex: string; chain: string; }) => {
try {
const url = new URL(`https://api.blockchair.com/${chain}/push/transaction`)
const response = await fetch(url.toString(), {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify({
data: txHex
})
})
console.log('Response: ', response)
const data = await response.json();
if (data.context.code !== 200) throw new Error('Fail to broadcast')
return data
} catch (error) {
console.error('Failed to broadcast transaction : ', error)
}
}
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.
Last modified 1mo ago