@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
  • 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
  • from (object): Tokens by chain ID for source
  • to (object): Tokens by chain ID for destination
• supportedChains (object): Restrict available chains
  • from (number[]): Available source chains
  • to (number[]): Available destination chains
• eventHandlers (EventHandlers): Event callbacks
• 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)

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";

Links

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