Skip to main content
This guide will walk you through cloning, configuring, and running the OneBalance Chain-Abstracted Swap application. You’ll perform your first cross-chain token swap in under 10 minutes.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 18+ installed
  • pnpm package manager (or npm/yarn)
  • A OneBalance API key (get one here)
  • A Privy account for Web3 authentication (sign up here)

​
Installation

1

Clone the repository

Clone the project from GitHub to your local machine:
git clone https://github.com/dzimiks/onebalance-chain-abstracted-swap
cd onebalance-chain-abstracted-swap
2

Install dependencies

Install all required packages using pnpm (or your preferred package manager):
pnpm install
The application uses these key dependencies:
  • Next.js 15 with App Router and Turbopack
  • Privy for Web3 authentication and embedded wallets
  • Wagmi & Viem for Ethereum interactions
  • Tailwind CSS with shadcn/ui components
  • TanStack Query for data fetching and caching
3

Configure environment variables

Create a .env file in the root directory with your API credentials:
.env
NEXT_PUBLIC_API_URL=https://be.onebalance.io
NEXT_PUBLIC_API_KEY=your_onebalance_api_key_here
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id_here
The example .env.example file includes demo credentials. For production use, replace these with your own API keys from OneBalance and Privy.
4

Start the development server

Launch the application with Turbopack for fast refresh:
pnpm dev
The app will be available at http://localhost:3000

​
Your first swap

Once the application is running, follow these steps to execute your first chain-abstracted token swap:
1

Connect your wallet

Click Login in the top-right corner. You can:
  • Sign in with email (no wallet needed)
  • Use a passkey for passwordless login
  • Connect an existing Web3 wallet
Privy will automatically create an embedded wallet for you if you don’t have one.
2

Select tokens

On the Swap page:
  1. Choose the token you want to sell (e.g., USDC)
  2. Choose the token you want to buy (e.g., ETH)
The application supports 100+ tokens across 15+ blockchains including Ethereum, Arbitrum, Base, Optimism, Polygon, Avalanche, and more.
3

Enter amount

Type the amount you want to swap, or click the percentage buttons (25%, 50%, 75%, 100%) to quickly select a portion of your balance.The app will automatically:
  • Fetch a real-time quote from OneBalance
  • Show the exchange rate and estimated output
  • Display any applicable fees
4

Review the quote

Check the quote details:
  • Exchange rate: Current rate between the two tokens
  • Estimated output: How much you’ll receive
  • Expiration: Quotes are valid for 30 seconds
If the quote expires before you execute, the app will automatically fetch a new one.
5

Execute the swap

Click Swap to execute the transaction. OneBalance will:
  1. Route your tokens across the optimal chains
  2. Handle all cross-chain bridging automatically
  3. Execute the swap at the best available rate
  4. Deliver tokens to your wallet
You can track the transaction status in real-time as it progresses through the blockchain.

​
Available scripts

The project includes several useful scripts defined in package.json: 
# Start dev server with Turbopack
pnpm dev

​
Project structure

Here’s an overview of the key directories: 
onebalance-chain-abstracted-swap/
├── app/                    # Next.js App Router pages
│   ├── (trading)/         # Trading-related pages (swap, transfer, history)
│   ├── layout.tsx         # Root layout with providers
│   └── page.tsx           # Home page (redirects to /swap)
├── components/            # React components
│   ├── ui/               # shadcn/ui components (Button, Card, etc.)
│   ├── onboarding/       # Interactive tutorial components
│   ├── SwapForm.tsx      # Main swap interface
│   └── TransferForm.tsx  # Token transfer interface
├── lib/                   # Core utilities and APIs
│   ├── api/              # OneBalance API client
│   ├── hooks/            # React hooks for data fetching
│   ├── types/            # TypeScript type definitions
│   └── utils/            # Helper functions
└── public/               # Static assets

​
Next steps

Core Features

Explore all 8 key features of the application

API Integration

Learn how OneBalance API powers chain abstraction

Authentication

Understand Privy’s embedded wallet system

Customization

Customize the UI to match your brand

Build docs developers (and LLMs) love

Get started for freeTalk to us