@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

$3

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

``bash
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.

$3

Add the Bungee styles to your application:

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

$3

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

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

export default function App() {
return ;
}
`

Configuration Reference

$3

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)

$3

#### Token Interface

When using supportedTokens, tokens must follow this structure:

`typescript
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.

$3

Customize the widget appearance with the theme property:

`tsx
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.

$3

Handle user interactions and widget events:

`tsx
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 }) => {
// Handle analytics and error logging
console.log("Analytics event:", log);
}
};
`

$3

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.

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

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

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

return ;
}
`

Available Methods:
- setInflightData(data: OrderData): Track pending transactions and navigate to inflight screen

$3

The package exports several TypeScript types:

`tsx
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/