Customize the DEX integration template

Change the DEX integration template’s slippage, tokens and routes, or move the swap widget into your own app.

Ready. This template is published in uzolabs/templates and has been deployed and verified on testnet. It’s a learning template and hasn’t been audited. Use test funds only.

What you’ll build

Your own swap scripts and widget on top of BDEX. Each change below is independent. The scripts and the widget share frontend/src/dex/, so most changes apply to both at once.

Prerequisites

A copy of the template that quotes, from Use a template.
The walkthrough, so you know how routes and approvals work.

Options per run

These need no code changes:

Terminal

npm run swap-v2 -- 1 BOT USDT --slippage 1
npm run swap-v3 -- 0.1 WBOT USDT --fee 500

--slippage 1 accepts up to 1% less than the quote, for this run only.
--fee 500, --fee 3000 or --fee 10000 picks a V3 pool. Without it, swap-v3 uses the pool with the best quote.

Change the code

Make your change

Slippage and deadline
More tokens
Multi-hop routes
Exact output
Remove liquidity

Edit the defaults in frontend/src/dex/math.ts. Values are in basis points, so 50 means 0.5%.

frontend/src/dex/math.ts

export const DEFAULT_SLIPPAGE_BPS = 50
export const MAX_SLIPPAGE_BPS = 500
export const DEADLINE_MINUTES = 20

Raising the maximum lets users accept worse prices by mistake. Keep it low unless you have a reason.

Tokens live in frontend/src/dex/routes.ts. To add one:

Add its symbol to the TokenSymbol type and the SYMBOLS list.
Add an entry to the object getTokens returns, with its address, its decimals and isNative: false.
Take the address from @uzolabs/sdk/contracts or an environment variable, not a hard-coded string, so testnet and mainnet both work.

Call the token’s decimals() on BOTScan before you add it. A wrong value makes every amount wrong by a power of ten.

The template trades directly between two tokens. To go from A to C through B:

On V2, pass a longer path, such as [A, B, C], to the Router02 swap functions.
On V3, use exactInput with an encoded path of tokens and fee tiers.

Quote the whole path first. V2’s getAmountsOut accepts the same path. For V3 use QuoterV2’s quoteExactInput.

To receive an exact amount, such as exactly 10 USDT, use swapTokensForExactTokens on V2 or exactOutputSingle on V3. Approve the most you’re willing to pay, and set that as the maximum input.

add-liquidity-v2 gives you the pair’s LP token. To take liquidity out, approve the LP token to Router02, then call removeLiquidity, or removeLiquidityETH to get BOT back instead of WBOT. See V2 liquidity.

Run the tests

Terminal

npm test
npm run typecheck

npm test covers the slippage maths and the failure reasons. Add a test for any new rule.

Try it on testnet

Terminal

npm run quote
npm run frontend

Quote first, then send a small swap from the widget and check the BOTScan link.

SwapCard in frontend/src/App.tsx is self-contained. To use it in your own wagmi app, copy:

SwapCard from App.tsx, with SwapResult.tsx.
The whole frontend/src/dex/ folder.
frontend/src/styles.css, and the variables from theme.css if you want the same look.

Your app must already have a WagmiProvider and a QueryClientProvider. See wagmi setup.

Change the look

Edit the variables at the top of frontend/src/theme.css for colours and fonts. The two background glows switch off for users who prefer reduced motion.

Mainnet

Mainnet uses real BOT and real USDT, and this template hasn’t been audited. Check the quote, the minimum received and the router address before you approve anything. Use a separate wallet.

Terminal

npm run quote -- 1 BOT USDT --mainnet

Every script that sends a transaction waits for you to type MAINNET. For the widget, set VITE_CHAIN_ID=677 in frontend/.env, run npm --prefix frontend run build, and host the frontend/dist folder on any static host.

Verify

There’s no contract to verify. After a swap, open the BOTScan link the script printed and check the token transfers match the “After” balances.

Troubleshooting

EXPIRED or Transaction too old

More than 20 minutes passed between building the swap and mining it, usually because the wallet popup stayed open. Swap again for a fresh deadline.

Too little received or INSUFFICIENT_OUTPUT_AMOUNT

The price moved past your slippage. Nothing was swapped and only gas was spent. Quote again, or raise slippage a little with --slippage 1.

No pool for a fee tier

Not every tier has a pool. On testnet there was no 0.01% WBOT/USDT pool when the template was tested. Run npm run find-pools to see which exist.

BOT and WBOT are 1:1 and need no pool

Use npm run wrap -- 1 or npm run wrap -- 1 --unwrap. In the widget, the button says Wrap or Unwrap.

The widget quotes nothing

A new token's amounts are wildly wrong

Its decimals in getTokens doesn’t match the contract. Read decimals() on BOTScan and fix the entry.

Overview

Templates

Contributing

Customize the DEX integration template

What you’ll build

Prerequisites

Options per run

Change the code

Embed the widget in your app

Change the look

Mainnet

Verify

Troubleshooting

Next steps

BDEX V3 swaps

Token template

​What you’ll build

​Prerequisites

​Options per run

​Change the code

​Embed the widget in your app

​Change the look

​Mainnet

​Verify

​Troubleshooting

​Next steps

BDEX V3 swaps

Token template

What you’ll build

Prerequisites

Options per run

Change the code

Embed the widget in your app

Change the look

Mainnet

Verify

Troubleshooting

Next steps