This guide outlines how to use the Swap API to execute a swap.
The full source code of this guide can be found in this Github repository.
Follow these steps to complete a swap:
1
Obtain API Key
Get an API key by reaching out to a member of our team.
2
Check Allowances
Check the current allowances for the tokens involved in the swap.
3
Set Allowances
Use an approval transaction to set the required allowances for the swap.
4
Execute Swap
Initiate the swap transaction.
1. Obtain an API Key
The API is currently available by request only. To obtain API keys, contact the team directly on Telegram: @whoiskevinn or @beranoulli.
2. Check Allowances
Before initiating trades with the Swap API, it is crucial to approve the ERC20 token intended for the swap (the input token) against the router. Ensure there is sufficient allowance granted to OBRouter. You can verify this programmatically or manually by calling the allowance function directly on the ERC20's contract on-chain.
The example code is written using bun and viem. But it should be equally simple to integrate using other runtimes such as node.js and other EVM libraries such as ether.js
Setting up the environment:
import {
http,
type Address,
createWalletClient,
maxUint256,
parseEther,
publicActions,
zeroAddress,
} from "viem"; // Main library used to interface with the blockchain
import { privateKeyToAccount } from "viem/accounts";
import { berachainTestnetbArtio } from "viem/chains";
if (!process.env.PRIVATE_KEY) throw new Error("PRIVATE_KEY is required");
if (!process.env.PUBLIC_API_URL) throw new Error("PUBLIC_API_URL is required");
if (!process.env.API_KEY) throw new Error("API_KEY is required");
const PRIVATE_KEY = process.env.PRIVATE_KEY as Address; // Private key of the account to make the trade
const PUBLIC_API_URL = process.env.PUBLIC_API_URL;
const API_KEY = process.env.API_KEY;
Setting the account and initializing the EVM libraries:
Defining the swap parameters (this example uses a 0.01 HONEY to BERA swap):
// Bartio token addresses
const NATIVE_TOKEN: Address = zeroAddress; // Default address for Bera native token
const HONEY: Address = "0x0E4aaF1351de4c0264C5c7056Ef3777b41BD8e03"; //
const swapParams = {
tokenIn: HONEY, // Address of the token swapping from (HONEY)
tokenOut: NATIVE_TOKEN, // Address of the token swapping to (BERA)
amount: parseEther("0.02"), // Amount of tokenIn to swap
to: account.address, // Address to send tokenOut to (optional and defaults to `from`)
slippage: 0.01, // Range from 0 to 1 to allow for price slippage
};
type SwapParams = typeof swapParams;
The Swap API also allows developers to query the allowances directly instead of doing on-chain.
If you are trading the native token no allowance is required. In this example, for simplicity, the allowance is set to maxUint256 in the native token case.
const headers = {
Authorization: `Bearer ${API_KEY}`,
};
const getAllowance = async (token: Address, from: Address) => {
// Native token does not require approvals for allowance
if (token === NATIVE_TOKEN) return maxUint256;
const publicApiUrl = new URL(`${PUBLIC_API_URL}/v1/approve/allowance`);
publicApiUrl.searchParams.set("token", token);
publicApiUrl.searchParams.set("from", from);
const res = await fetch(publicApiUrl, {
headers,
});
const json = await res.json();
return json.allowance;
};
Everytime the Swap API is queried, the API_KEY has to be provided on the fetch call.
getAllowance fits into the main execution body likeso:
The amount parameter can be left out, generating a transaction to approve unlimited amounts for the given token to the router. This is useful to save gas on subsequent swap requests.
Once the necessary allowances are in place, you can call the final API endpoint to generate a quote. If the quote meets your expectations, proceed to execute the trade.
The swap query doubles as a quote, providing essential details about the trade. Comprehensive information about the quote can be found in the API reference.
Additionally, the quote endpoint generates the complete transaction body, ready to be signed and submitted directly on-chain.
If the tokenIn is the native token, ensure that a value is passed. This will automatically wrap the native token into WBERA, enabling it to be traded.
If BERA is the tokenOut then it will be returned unwrapped.
Theres object can be printed to view the complete routing path and detailed information about the swap. For a comprehensive breakdown of the response, refer to the API Reference.