Skip to main content
Proper configuration is essential for connecting to the OneBalance API and enabling Privy authentication. This guide covers all required environment variables and configuration options.

​
Environment variables

Create a .env file in your project root with the following variables:
.env
NEXT_PUBLIC_API_URL=https://be.onebalance.io
NEXT_PUBLIC_API_KEY=your_onebalance_api_key
NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id
All environment variables are prefixed with NEXT_PUBLIC_ to make them accessible in the browser. This is required for client-side API calls.

​
Required variables

​
NEXT_PUBLIC_API_URL
string
required
The base URL for the OneBalance API. Use https://be.onebalance.io for production.Example: https://be.onebalance.io
​
NEXT_PUBLIC_API_KEY
string
required
Your OneBalance API key for authentication. Obtain this from the OneBalance Dashboard.Format: 64-character hexadecimal string
​
NEXT_PUBLIC_PRIVY_APP_ID
string
required
Your Privy application ID for wallet authentication. Get this from the Privy Dashboard.Format: cm[a-z0-9]+

​
API configuration

The application uses a proxy pattern to securely handle API requests. API credentials are managed in lib/constants.ts:
lib/constants.ts
export const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL || 'https://be.onebalance.io';
export const API_KEY = process.env.NEXT_PUBLIC_API_KEY;

​
API route handler

All OneBalance API calls are proxied through a Next.js API route at app/api/[...path]/route.ts. This pattern:
  • Centralizes API key management
  • Adds authentication headers automatically
  • Handles errors consistently
  • Supports both GET and POST requests
export async function GET(request: NextRequest, { params }) {
  const { path } = await params;
  const pathString = path.join('/');
  const searchParams = request.nextUrl.searchParams;

  const apiUrl = new URL(`/api/${pathString}`, API_BASE_URL);
  searchParams.forEach((value, key) => {
    apiUrl.searchParams.append(key, value);
  });

  const response = await fetch(apiUrl.toString(), {
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': API_KEY,
    },
  });

  const data = await response.json();
  return NextResponse.json(data);
}

​
Provider configuration

All application providers are configured in app/providers.tsx. This includes:
app/providers.tsx
import { PrivyProvider } from '@privy-io/react-auth';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ThemeProvider } from '@/components/ThemeProvider';
import { PredictedAddressProvider } from '@/lib/contexts/PredictedAddressContext';

const queryClient = new QueryClient();

export const Providers = ({ children }: ProvidersProps) => (
  <PlausibleProvider domain="onebalance-chain-abstracted-swap.vercel.app">
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      <QueryClientProvider client={queryClient}>
        <PrivyProvider
          appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID || ''}
          config={{
            embeddedWallets: {
              createOnLogin: 'users-without-wallets',
            },
            loginMethods: ['email', 'passkey', 'wallet'],
            appearance: {
              theme: 'light',
              accentColor: '#FFAB40',
            },
          }}
        >
          <PredictedAddressProvider>
            {children}
          </PredictedAddressProvider>
        </PrivyProvider>
      </QueryClientProvider>
    </ThemeProvider>
  </PlausibleProvider>
);

​
Provider hierarchy

The providers are nested in this order:
1

PlausibleProvider

Analytics tracking for user interactions
2

ThemeProvider

Light/dark theme management with system detection
3

QueryClientProvider

TanStack Query for async state management
4

PrivyProvider

Web3 authentication and wallet management
5

PredictedAddressProvider

OneBalance account address prediction

​
Axios client configuration

The base API client is configured in lib/api.ts to use the Next.js API proxy:
lib/api.ts
import axios from 'axios';

export const apiClient = axios.create({
  baseURL: '/api',
  headers: {
    'Content-Type': 'application/json',
  },
});
The baseURL is set to /api to route through the Next.js API handler, which adds authentication headers automatically.

​
Obtaining API credentials

​
OneBalance API key

  1. Visit the OneBalance Dashboard
  2. Sign up or log in to your account
  3. Navigate to API Keys section
  4. Generate a new API key for your application
  5. Copy the key and add it to your .env file
Keep your API key secure. Never commit it to version control or expose it in client-side code outside of the Next.js environment variable system.

​
Privy App ID

  1. Visit the Privy Dashboard
  2. Create a new application or select an existing one
  3. Copy your App ID from the settings page
  4. Add it to your .env file

​
Verify configuration

After setting up your environment variables, verify the configuration: 
pnpm dev
Check the browser console for:
  • ✅ No authentication errors
  • ✅ Privy wallet provider initializes
  • ✅ API calls to OneBalance succeed
If you see errors, double-check that:
  • All environment variables are set correctly
  • The .env file is in the project root
  • You’ve restarted the development server after adding variables

​
Next steps

OneBalance API

Learn how to use the OneBalance API for chain abstraction

Privy wallet

Configure Privy for Web3 authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us