> For the complete documentation index, see [llms.txt](https://docs.wheelx.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wheelx.fi/sdk-and-widget/widget/quick-start.md).

# Quick Start

An open-source, framework-agnostic React widget for cross-chain token swaps and bridges. Built-in wallet connection support (EVM + Solana), configurable theme system, and ready-to-use demo application.

### Features

* 🔄 **Cross-chain Swap & Bridge** — Full trading flow with quote polling, gas estimation, approval handling
* 👛 **Built-in Wallet Connection** — Dynamic SDK + Wagmi v2 supporting EVM (MetaMask, OKX, etc.) and Solana (Phantom)
* 🎨 **Configurable Theme** — 14 color tokens for custom skinning
* ⚛️ **Framework Agnostic** — Works with any React framework (Next.js, Vite, Create React App, etc.)
* 📦 **Tree-shakeable** — ESM + CJS builds with TypeScript declarations
* 🔌 **Configurable Default Tokens** — Set default from/to chains and tokens
* 📱 **Deep Link Support** — Wallet app launch support in WebView (React Native) — see Deep Link Guide

### Installation

```
npm install @wheelx-widget/widget @chakra-ui/react @emotion/react
```

Note: `@chakra-ui/react` and `@emotion/react` are required peer dependencies.

### Quick Start

```
// main.tsx — wrap with ChakraProvider
import { ChakraProvider, defaultSystem } from '@chakra-ui/react'
import { createRoot } from 'react-dom/client'
import App from './App'

createRoot(document.getElementById('root')!).render(
  <ChakraProvider value={defaultSystem}>
    <App />
  </ChakraProvider>
)
```

```
// App.tsx
// Import the CSS for animations (required!)
import '@wheelx-widget/widget/dist/index.css'
import { WheelXProvider, WheelXWidget } from '@wheelx-widget/widget'

function App() {
  return (
    <WheelXProvider>
      <WheelXWidget />
    </WheelXProvider>
  )
}
```

### Configuration

#### Theme Customization

Customize 14 visual tokens:

```
<WheelXProvider config={{
  theme: {
    defaultTextColor: '#1A1D26',
    highlightTextColor: '#007B9D',
    weakTextColor: '#5D6270',
    defaultBgColor: '#FFFFFF',
    highlightBgColor: '#E6F7FB',
    assistBgColor: '#F5F6F8',
    defaultBorderColor: '#E2E4E8',
    highlightBorderColor: '#007B9D',
    highlightButtonBg: '#007B9D',
    highlightButtonText: '#FFFFFF',
    normalButtonBg: '#F5F6F8',
    normalButtonText: '#1A1D26',
    disabledButtonBg: '#E2E4E8',
    disabledButtonText: '#A0A4AE'
  }
}}>
  <WheelXWidget />
</WheelXProvider>
```

#### Default Chain/Token Configuration

```
<WheelXProvider config={{
  from: {
    chains: [8453, 1],           // Only show Base and Ethereum as from chains
    defaultChainId: 8453          // Default to Base
  },
  to: {
    chains: [1868],               // Only show Soneium as to chain
    defaultChainId: 1868          // Default to Soneium
  }
}}>
  <WheelXWidget />
</WheelXProvider>
```

#### Custom Dynamic Environment ID

```
<WheelXProvider config={{
  dynamicEnvironmentId: 'your-dynamic-environment-id'
}}>
  <WheelXWidget />
</WheelXProvider>
```

#### API Base URL

Override the default WheelX API endpoint. Useful for testing against a staging or development environment.

```
<WheelXProvider config={{
  apiBaseUrl: 'https://dev-api.wheelx.fi'  // Default: 'https://api.wheelx.fi'
}}>
  <WheelXWidget />
</WheelXProvider>
```

#### Fixed Recipient Address (Different Address)

Configure fixed recipient addresses for EVM or Solana chains. When set, the widget will:

* **Display the configured address** in the To field instead of showing "Connect Wallet"
* **Query the token balance** of the configured address
* **Skip wallet connection** for the target chain (only the source chain wallet is required for signing)
* **Show GetGas** when the configured address has insufficient native token balance

This is useful for exchange or merchant scenarios where funds should always be sent to a specific address regardless of which wallet the user connects.

**Priority order for recipient address:**

1. Configured fixed address (`evmDifferentAddress` / `solanaDifferentAddress`)
2. User manually entered different address (via Different Address dialog)
3. Connected wallet address

```
<WheelXProvider config={{
  evmDifferentAddress: '0xAbCdEf1234567890...',  // Fixed recipient for EVM chains (0x format)
  solanaDifferentAddress: '9zQX...'               // Fixed recipient for Solana chains (base58 format)
}}>
  <WheelXWidget />
</WheelXProvider>
```

**Note:** You can configure one, both, or neither. The widget will only use the relevant one based on the selected To chain.

### API Reference

#### `<WheelXProvider>`

The root provider component that sets up wallet connections, React Query, and theme.

#### `<WheelXWidget>`

The main trading widget component.

#### `WidgetConfig`

```
interface WidgetConfig {
  theme?: Partial<WidgetTheme>

  /** API base URL. Default 'https://api.wheelx.fi' */
  apiBaseUrl?: string

  from?: {
    chains?: number[]
    defaultChainId?: number
    chainTokens?: Record<number, TokenConfig[]>
    defaultToken?: { chainId: number; address: string }
  }
  to?: {
    chains?: number[]
    defaultChainId?: number
    chainTokens?: Record<number, TokenConfig[]>
    defaultToken?: { chainId: number; address: string }
  }
  routerCallback?: {
    onPathnameChange?: (pathname: string) => void
    onRouteLeave?: () => void
    getCurrentPathname?: () => string
  }
  dynamicEnvironmentId?: string
  onDeepLink?: (url: string) => void  // See Deep Link Guide for WebView environments

  /** Fixed recipient address for EVM chains (0x format). Takes priority over wallet address and manual different address */
  evmDifferentAddress?: string
  /** Fixed recipient address for Solana chains (base58 format). Takes priority over wallet address and manual different address */
  solanaDifferentAddress?: string
}
```

#### `WidgetTheme`

```
interface WidgetTheme {
  defaultTextColor: string
  highlightTextColor: string
  weakTextColor: string
  defaultBgColor: string
  highlightBgColor: string
  assistBgColor: string
  defaultBorderColor: string
  highlightBorderColor: string
  highlightButtonBg: string
  highlightButtonText: string
  normalButtonBg: string
  normalButtonText: string
  disabledButtonBg: string
  disabledButtonText: string
  /** Color palette for the GetGas switch component. e.g. 'purple', 'blue', 'green'. Default: 'purple' */
  getGasSwitchColorPalette?: string
}
```

### Demo

A demo `https://widget.wheelx.fi`

### API Endpoint

This widget connects to the WheelX API at `https://api.wheelx.fi`. The API domain is not configurable.

### React Native / WebView Integration

If you embed the Widget into a React Native WebView, additional configuration is required to properly launch wallet apps.

Please refer to: **Mobile Wallet Launch Guide (DEEP\_LINK\_GUIDE.md)**

In short, three things are required:

1. Add `onMessage` listener in the WebView
2. Configure `<queries>` declaration in Android's `AndroidManifest.xml`
3. Configure `LSApplicationQueriesSchemes` in iOS's `Info.plist`

### License

MIT


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.wheelx.fi/sdk-and-widget/widget/quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.