Getting Started

Widget V2

The OpenOcean Widget V2 is the upgraded version of our plug-and-play swap & bridge component, now supporting both same-chain and cross-chain transactions in one unified interface.

This powerful widget is built for seamless integration, allowing any app or platform to easily offer secure, multi-chain token swaps and bridging directly to users - without redirecting them elsewhere.

With full customization options, the widget can be styled to match your app's UI, helping you enhance your multi-chain strategy and retain users across EVM ecosystems.

Key Features

Unified cross-chain & same-chain swaps
Supports 35+ chains and 1,000+ tokens
Customizable UI to match your branding
Built-in OpenOcean swap routing for best price execution

Example Use Cases

dApps: Allow users to swap on chain and bring assets cross-chain to your protocol
DeFAI: Boost your AI agent's execution capabilities with optimized routing
DeFi tools: Add a seamless token entry point with best-rate execution
GameFi/Meme/Launchpad: Enable users fund wallets across chains without leaving your site

Install the widget

To get started, install the latest version of OpenOcean Widget and required packages.

Terminal

1 npm install @openocean.finance/widget wagmi @bigmi/react @solana/wallet-adapter-react @tanstack/react-query

Wagmi is type safe, extensible, and modular library for building Ethereum apps.
Bigmi is modular TypeScript library that provides reactive primitives for building Bitcoin applications.
@solana/wallet-adapter-react is modular TypeScript wallet adapters and components for Solana applications.
TanStack Query is an async state manager that handles requests, caching, and more. It is recommended to use version ^5.72.0 or above.

Basic example

Below is a basic example using OpenOcean Widget with container customization.

Terminal

1 import { OpenOceanWidget } from '@openocean.finance/widget';
2 const widgetConfig = {
3     fromChain: 8453,  // Source chain ID
4     toChain: 8453,    // Destination chain ID (same as source in this case)
5     fromToken: '0x0000000000000000000000000000000000000000', // Address of the token you are sending (e.g., native token like ETH)
6     toToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913',   // Address of the token you want to receive
7     fromAmount: '1',   // Amount to be swapped
8     subvariant: "bridge", // Set this only if you're enabling cross-chain functionality
9     theme: {
10       container: {
11         border: '1px solid rgb(234, 234, 234)',
12         borderRadius: '16px',
13       },
14     },
15   languages: {
16     allow: ['en'], // bn, de, en, es, fr, id, it, ja, ko, pt, th, tr, uk, vi, zh
17     // deny: ['uk'],
18   },
19   };
20   export const WidgetPage = () => {
21     return (
22       <OpenOceanWidget integrator="Your dApp/company name" config={widgetConfig} />
23     );
24 };

Example of loading the widget under a nested (second-level) route:

In the route configuration, change /trade to /trade/*:

<Route path="/trade/*" element={} />

Next Steps

Widget V2

Back to Widget V2 overview.

Swagger UI

Try API endpoints interactively.

1	import { OpenOceanWidget } from '@openocean.finance/widget';
2	const widgetConfig = {
3	fromChain: 8453, // Source chain ID
4	toChain: 8453, // Destination chain ID (same as source in this case)
5	fromToken: '0x0000000000000000000000000000000000000000', // Address of the token you are sending (e.g., native token like ETH)
6	toToken: '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913', // Address of the token you want to receive
7	fromAmount: '1', // Amount to be swapped
8	subvariant: "bridge", // Set this only if you're enabling cross-chain functionality
9	theme: {
10	container: {
11	border: '1px solid rgb(234, 234, 234)',
12	borderRadius: '16px',
13	},
14	},
15	languages: {
16	allow: ['en'], // bn, de, en, es, fr, id, it, ja, ko, pt, th, tr, uk, vi, zh
17	// deny: ['uk'],
18	},
19	};
20	export const WidgetPage = () => {
21	return (
22	<OpenOceanWidget integrator="Your dApp/company name" config={widgetConfig} />
23	);
24	};