> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enso.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Widget

> A React component for seamless cryptocurrency deposits with wallet and exchange integration

export const date_0 = "2025-09-23"

The Checkout Widget supports multiple funding sources including wallet transfers and exchange deposits, with built-in cross-chain routing and DeFi token swapping capabilities.

<CardGroup cols={2}>
  <Card title="Try the Demo" icon="play" href="https://checkout.enso.build/">
    Try out the checkout flow
  </Card>

  <Card title="Integration Guide" icon="hammer" href="#integrate">
    Add to your app
  </Card>
</CardGroup>

Key features include:

* **Multiple funding sources**: Connect wallets (MetaMask, Rabby) or exchanges (Binance)
* **Cross-chain deposits**: Automatic routing between different blockchain networks
* **Real-time quotes**: Live pricing and gas estimates
* **Customizable theming**: Full control over appearance and branding
* **Transaction tracking**: Real-time status updates with block explorer links

<img src="https://mintcdn.com/enso/LXMmUdnNCqUooVis/images/templates/checkout-widget.png?fit=max&auto=format&n=LXMmUdnNCqUooVis&q=85&s=b4f2c6dd4c6d17f57a518707cd8a34c9" alt="Route Widget Flow" className="mx-auto" width="300px" noZoom={true} data-path="images/templates/checkout-widget.png" />

## How it Works

The widget provides multiple deposit flows depending on the user's preferred funding source:

1. **Wallet Flow**: Connect existing wallets and transfer tokens directly
2. **Exchange Flow**: Link exchange accounts (Binance) for seamless withdrawals
3. **Card Deposits**: Traditional payment methods (coming soon)

## Integrate

<Steps>
  <Step title="Install the package">
    Install the widget:

    ```
    npm i @ensofinance/checkout-widget
    ```
  </Step>

  <Step title="API key">
    You can get an API key from the [Developer Portal](https://developers.enso.build).
  </Step>

  <Step title="Basic implementation">
    Import and configure the widget.

    To enable Binance deposits, add the `enableExchange` configuration.

    <Info>
      Any of the [tokens](/api-reference/tokens/tokens) or [nontokenized positions](/api-reference/tokens/nontokenized-positions) can be used as `tokenOut`
    </Info>

    <Note>
      **Domain whitelisting required**: Contact [Enso support](https://t.me/enso_shortcuts) to whitelist your domain(s) before enabling exchange integration.
    </Note>

    <Tabs>
      <Tab title="Checkout Modal">
        ```tsx theme={null}
          import { CheckoutModal } from '@ensofinance/checkout-widget';

          export function MyCheckoutComponentModal() {
            const [isCheckoutActive, setIsCheckoutActive] = useState(false);

            return (
              <CheckoutModal 
                config={{
                  apiKey: "YOUR_API_KEY",
                  tokenOut: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  chainIdOut: 8453,
                  enableExchange: ["binance"] // Enable Binance integration
                }}
                isActive={isCheckoutActive}
                setIsActive={setIsCheckoutActive}
              />
            );
          }
        ```
      </Tab>

      <Tab title="Standalone Checkout">
        ```tsx theme={null}
        import { Checkout } from '@ensofinance/checkout-widget';

        export function MyCheckoutComponent() {
          return (
            <div className="checkout-container">
              <Checkout 
                config={{
                  apiKey: "YOUR_API_KEY",
                  tokenOut: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
                  chainIdOut: 8453
                }}
              />
            </div>
          );
        }
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Setup Web3 providers">
    The widget requires Wagmi and React Query providers. Set up your app's root component:

    ```tsx theme={null}
    import { WagmiProvider, createConfig, http } from 'wagmi';
    import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
    import { base, mainnet, arbitrum } from 'wagmi/chains';
    import { injected, walletConnect } from 'wagmi/connectors';

    // Configure supported chains and connectors
    const config = createConfig({
      chains: [mainnet, base, arbitrum],
      connectors: [
        injected(), // MetaMask, Rabby, etc.
        walletConnect({
          projectId: 'YOUR_WALLETCONNECT_PROJECT_ID'
        }),
      ],
      transports: {
        [mainnet.id]: http(),
        [base.id]: http(),
        [arbitrum.id]: http(),
      },
    });

    const queryClient = new QueryClient();

    function App() {
      return (
        <WagmiProvider config={config}>
          <QueryClientProvider client={queryClient}>
            {/* Your app components */}
            <MyCheckoutComponent />
          </QueryClientProvider>
        </WagmiProvider>
      )
    }
    ```
  </Step>

  <Step title="Theme customization">
    The widget accepts a complete Chakra UI v3 `SystemConfig` for theming.

    <Tip>
      For advanced theming, refer to the [Chakra UI theming documentation](https://v3.chakra-ui.com/docs/theming/semantic-tokens).
    </Tip>

    ```tsx theme={null}
    import { CheckoutModal, type WidgetTheme } from '@ensofinance/checkout-widget';
    const customTheme: WidgetTheme = {
      theme: {
        semanticTokens: {
          colors: {
            // Background colors
            bg: { value: "#ffffff" },
            "bg.subtle": { value: "#f8fafc" },
            "bg.emphasized": { value: "#f1f5f9" },
            // Foreground/text colors  
            fg: { value: "#0f172a" },
            "fg.muted": { value: "#64748b" },
            "fg.subtle": { value: "#94a3b8" },
            
            // Border colors
            border: { value: "#e2e8f0" },
            "border.emphasized": { value: "#cbd5e1" },
            
            // Primary accent color
            primary: { value: "#3b82f6" },
            "primary.emphasis": { value: "#2563eb" },
            
            // Status colors
            success: { value: "#10b981" },
            warning: { value: "#f59e0b" },
            error: { value: "#ef4444" },
          },
        },
        // Custom button variants
        recipes: {
          button: {
            variants: {
              solid: { 
                bg: "primary", 
                color: "white",
                _hover: { bg: "primary.emphasis" }
              }
            }
          }
        }
      }
    };
    function App() {
      return (
        <CheckoutModal
          config={{
            apiKey: "YOUR_API_KEY",
            tokenOut: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
            chainIdOut: 8453,
            cexBridgeChainMapping: {[999]: 42161} // target-to-intermediate
            theme: customTheme
          }}
          isActive={isCheckoutActive}
          setIsActive={setIsCheckoutActive}
        />
      );
    }
    ```
  </Step>
</Steps>

## Configuration Props

### CheckoutConfig Properties

The following checkout config exists:

| Parameter               | Type                     | Description                                                | Required |
| ----------------------- | ------------------------ | ---------------------------------------------------------- | -------- |
| `apiKey`                | `string`                 | Your Enso API key                                          | Yes      |
| `tokenOut`              | `string`                 | Destination token address                                  | Yes      |
| `chainIdOut`            | `number`                 | Destination chain ID                                       | Yes      |
| `recipient`             | `string`                 | Recipient address for the output tokens                    | No       |
| `theme`                 | `WidgetTheme`            | Custom Chakra UI theme config                              | No       |
| `enableExchange`        | `SupportedExchanges[]`   | Enable exchange integrations (`["binance"]`)               | No       |
| `cexBridgeChainMapping` | `Record<number, number>` | Intermediate chain mapping if direct withdraw not possible | No       |

### CheckoutModalProps

The `CheckoutModal` expands `CheckoutConfig` with modal-related properties and callbacks:

| Parameter     | Type                        | Description                                                | Required |
| ------------- | --------------------------- | ---------------------------------------------------------- | -------- |
| `config`      | `CheckoutConfig`            | Widget [configuration object](#checkout-config-properties) | Yes      |
| `isActive`    | `boolean`                   | Controls modal visibility                                  | Yes      |
| `setIsActive` | `(active: boolean) => void` | Modal state setter                                         | Yes      |
| `onClose`     | `() => void`                | Close callback function                                    | No       |

## Supported Networks

The widget supports deposits across all networks:

* Ethereum (Chain ID: 1)
* Base (Chain ID: 8453)
* Arbitrum (Chain ID: 42161)
* Optimism (Chain ID: 10)
* Polygon (Chain ID: 137)
* Avalanche (Chain ID: 43114)
* BSC (Chain ID: 56)
* And [many more](/pages/build/reference/supported-networks)

## Learn more

* [Crosschain routing](/pages/build/get-started/crosschain-routing)
* [Use Cases](/pages/use-cases)

<div className="text-right text-xs gray-200 font-semibold w-full" style={{marginTop: '0'}}>
  <p style={{
        color: "#b2b2b2"  
    }}>Updated {date_0}</p>
</div>