Below it will show you how to integrate the `@socket.tech/bungee` package into a React application with RainbowKit for wallet connection.
npm install @socket.tech/bungeeBelow it will show you how to integrate the @socket.tech/bungee package into a React application with RainbowKit for wallet connection.
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
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.
Add the Bungee styles to your application:
`tsx`
import "@socket.tech/bungee/styles.css";
import "@socket.tech/bungee/fonts.css";
`tsx
import { Bungee, type BungeeConfig } from "@socket.tech/bungee";
const config: BungeeConfig = {
apiKey: "your-api-key-here",
};
export default function App() {
return
}
`
The BungeeConfig interface provides extensive customization options:
#### Required Properties
- apiKey (string): Your Bungee API key
#### Optional Properties
- affiliateId (string): For integrator trackingbaseUrl
- (string): Custom API base URL. Defaults to public apitheme
- (Theme): Theming configurationrpcs
- (object): Custom RPC URLssolana
- (string): Solana RPC URLeip155
- (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 IDtoChain
- (number): Default destination chain IDinputTokens
- (string[]): Default input token addressesoutputTokens
- (string[]): Default output token addressesamount
- (string[]): Default amountsoutputRatio
- (number[]): Output ratioslocale
- (SupportedLocale): UI locale (currently only "en-US")sortPreference
- ("fast" | "best"): Route sorting preferenceswapSlippage
- (number): Default slippage tolerancesupportedTokens
- (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 chainsfrom
- (number[]): Available source chainsto
- (number[]): Available destination chainseventHandlers
- (EventHandlers): Event callbacksfeeParams
- (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 feefeeBps
- (number): Fee in basis points (e.g. 10 = 0.1%)features
- (object): Feature flagsinternalToasts
- (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 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 tokeninitialValues.fromChain
- To show a default source token, you must pass and initialValues.inputTokensisVerified
- The field should be set to true for all tokens in supportedTokens to avoid showing warnings to usersinputTokens
- The 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.
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.
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);
}
};
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
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
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.
- Web App: bungee.exchange
- Bungee Lite Package: @socket.tech/bungee
- Bungee Protocol Docs: docs.bungee.exchange/