@socket.tech/bungee

Below it will show you how to integrate the @socket.tech/bungee package into a React application with RainbowKit for wallet connection.

What is Bungee?

Bungee is a swap and bridge widget that enables users to swap tokens across different blockchains. The @socket.tech/bungee package provides a React component that can be easily integrated into any web application.

• Live Product: bungee.exchange
• NPM Package: @socket.tech/bungee
• Documentation: docs.bungee.exchange

Installation & Setup

1. Install Dependencies

The Bungee package requires several peer dependencies that you must install manually:

pnpm install @socket.tech/bungee react react-dom wagmi viem @tanstack/react-query @solana/wallet-adapter-react

Note: Peer dependencies are NOT automatically installed. You must install them explicitly in your project.

2. Import Required CSS

Add the Bungee styles to your application:

import "@socket.tech/bungee/styles.css";
import "@socket.tech/bungee/fonts.css";

3. Basic Usage

import { Bungee, type BungeeConfig } from "@socket.tech/bungee";

const config: BungeeConfig = {
  apiKey: "your-api-key-here",
};

export default function App() {
  return <Bungee config={config} />;
}

Configuration Reference

BungeeConfig Interface

The BungeeConfig interface provides extensive customization options:

Required Properties

• apiKey (string): Your Bungee API key

Optional Properties

• affiliateId (string): For integrator tracking
• baseUrl (string): Custom API base URL. Defaults to public api
• theme (Theme): Theming configuration
• rpcs (object): Custom RPC URLs
  • solana (string): Solana RPC URL
  • eip155 (string): Ethereum Mainnet RPC URL to use for transactions. Integrators can provide custom RPC endpoints (e.g., QuickNode, Alchemy) for benefits such as faster transaction processing, better analytics, rate limits, or other infrastructure requirements.
• initialValues (object): Default values. See Token Configuration Details for usage with supportedTokens.
  • fromChain (number): Default source chain ID
  • toChain (number): Default destination chain ID
  • inputTokens (string[]): Default input token addresses
  • outputTokens (string[]): Default output token addresses
  • amount (string[]): Default amounts
  • outputRatio (number[]): Output ratios
  • locale (SupportedLocale): UI locale (currently only "en-US")
  • sortPreference ("fast" | "best"): Route sorting preference
  • swapSlippage (number): Default slippage tolerance
• supportedTokens (object): Restrict available tokens. See Token Configuration Details below for complete structure and usage.
  • from (object): Tokens by chain ID for source. Structure: { [chainId: string]: Token[] }
  • to (object): Tokens by chain ID for destination. Structure: { [chainId: string]: Token[] }
• supportedChains (object): Restrict available chains
  • from (number[]): Available source chains
  • to (number[]): Available destination chains
• eventHandlers (EventHandlers): Event callbacks
• feeParams (object): Integrator fee configuration. When provided, these are sent with quote requests so the API can apply your fee.
  • feeTakerAddress (string): Wallet address that receives the fee
  • feeBps (number): Fee in basis points (e.g. 10 = 0.1%)
• features (object): Feature flags
  • internalToasts (boolean): Show/hide internal toasts (default: true)
  • internalTxHistory (boolean): Show/hide transaction history (default: true)
  • autoRouting (boolean): Auto-routing feature (not implemented)
  • refuel (boolean): Refuel feature (not implemented)

Token Configuration Details

Token Interface

When using supportedTokens, tokens must follow this structure:

interface Token {
  address: string;
  chainId: number;
  decimals: number;
  logoURI: string;
  name: string;
  symbol: string;
  isVerified?: boolean; // Must be true to avoid warnings
}

Using supportedTokens

Important Notes:

• When supportedTokens are provided, the widget will not automatically set a default token
• To show a default source token, you must pass initialValues.fromChain and initialValues.inputTokens
• The isVerified field should be set to true for all tokens in supportedTokens to avoid showing warnings to users
• The inputTokens addresses must match tokens from your supportedTokens.from[chainId] list

Fetching Token Data

When using supportedTokens, you can fetch token data from the Bungee API endpoints:

• /tokens/list: Returns a curated list of trending tokens (verified) or the complete token list
• /tokens/search: Search for tokens by address, name, or symbol

Tokens fetched from these endpoints will include the isVerified field. For detailed information about these endpoints, including request parameters and response formats, see the Bungee API token endpoints documentation.

Theme Configuration

Customize the widget appearance with the theme property:

const theme = {
  width: 420, // or "full" for full width
  borderRadius: "base", // "none" | "sm" | "base" | "md" | "lg"
  fonts: {
    primary: "Inter, sans-serif",
    secondary: "Roboto, sans-serif"
  },
  colors: {
    text: {
      primary: "#FFFFFF",
      secondary: "#A0A0A0",
      button: "#000000",
      theme: "#3B82F6",
      accent1: "#10B981",
      accent2: "#F59E0B",
      accent3: "#EF4444",
      accent4: "#8B5CF6"
    },
    bg: {
      layer1: "#1F2937",
      layer2: "#374151",
      layer3: "#4B5563",
      accent1: "#10B981",
      accent3: "#EF4444",
      accent4: "#8B5CF6",
      main: "#111827",
      theme: "#3B82F6"
    },
    border: {
      strong: "#6B7280",
      theme: "#3B82F6"
    },
    icon: {
      primary: "#FFFFFF",
      secondary: "#A0A0A0",
      theme: "#3B82F6"
    }
  }
};

Color Format Support: Colors support both hex (#FFFFFF) and RGB (rgb(255, 255, 255)) formats.

Event Handlers

Handle user interactions and widget events:

const eventHandlers = {
  onFromTokenChange: (token: Token) => {
    console.log("Source token changed:", token);
  },
  onToTokenChange: (token: Token) => {
    console.log("Destination token changed:", token);
  },
  onFromChainChange: (chain: Chain) => {
    console.log("Source chain changed:", chain);
  },
  onToChainChange: (chain: Chain) => {
    console.log("Destination chain changed:", chain);
  },
  onEvent: (eventType: "success" | "error" | "warning", eventData: EventData) => {
    console.log("Widget event:", eventType, eventData);
  },
  onOpenWalletConnect: (network: "solana" | "eip155") => {
    // Open your custom wallet connection modal
    openWalletModal(network);
  },
  onSwapInitiated: (data: { chainId: number; hash: string; type: OrderFlowType }) => {
    console.log("Swap initiated:", data);
  },
  logEvent: (log: { event: Event; error: unknown; context?: Record<string, unknown> }) => {
    // Handle analytics and error logging
    console.log("Analytics event:", log);
  }
};

Imperative API

The imperative API is used for external controls, allowing parent components to interact with the widget components programmatically. This enables you to control the widget's state and behavior from outside the widget itself.

Use Case Example: In the Bungee app, when you click on a history item in the sidebar, it opens the inflight screen in the widget. This interaction is facilitated by the imperative API, where the parent sidebar component communicates with the widget to navigate to a specific screen.

import { useRef } from "react";
import { Bungee, type BungeeImperativeAPIType } from "@socket.tech/bungee";

export default function App() {
  const bungeeRef = useRef<BungeeImperativeAPIType>(null);

  const handleSetInflightData = (data: OrderData) => {
    // Parent component can control widget state externally
    bungeeRef.current?.setInflightData(data);
  };

  return <Bungee config={config} ref={bungeeRef} />;
}

Available Methods:

• setInflightData(data: OrderData): Track pending transactions and navigate to inflight screen

Type Exports

The package exports several TypeScript types:

import type {
  BungeeConfig,
  BungeeImperativeAPIType,
  Token,
  Chain
} from "@socket.tech/bungee";

Token Type: The Token type includes fields such as address, chainId, decimals, logoURI, name, symbol, and isVerified. When using tokens in supportedTokens, ensure isVerified is set to true to avoid warnings being displayed to users.

Links

• Web App: bungee.exchange
• Bungee Lite Package: @socket.tech/bungee
• Bungee Protocol Docs: docs.bungee.exchange/