Quickstart

Get the OneBalance Chain-Abstracted Swap application running locally in minutes

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:

Development

# 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