Skip to main content

​
Quick Start

​
Installation

Install the Layerswap Widget along with the Starknet provider. 
npm install @layerswap/widget zustand @layerswap/wallet-starknet
If you want to customize the wallet provider selection, please refer to the Widget Quickstart.

​
Initial Configuration

Set up the providers and widget in your main component: 
import { Swap, LayerswapProvider } from '@layerswap/widget'
import { createStarknetProvider } from "@layerswap/wallet-starknet"
import "@layerswap/widget/index.css"

const PageComponent = () => {
  const starknetProvider = createStarknetProvider({ walletConnectConfigs: {
      projectId: "YOUR_WALLETCONNECT_PROJECT_ID",
      name: "Your App Name",
      description: "Your app description",
      url: "https://yourapp.com",
      icons: ["https://yourapp.com/logo.png"]
    }
  })

  return (
      <LayerswapProvider
          config={{
              apiKey: {LAYERSWAP_API_KEY}, //optional
              version: 'mainnet',
              initialValues: {
                  to: 'STARKNET_MAINNET',
                  toAsset: 'USDC',
                  lockTo: true
              },
          }}
          walletProviders={[starknetProvider]}
      >
          <Swap />
      </LayerswapProvider>
  )
}
For a complete list of configuration options, see Configurations. You can generate an API key from the Partner Dashboard to track swaps done through the widget.

​
Wallet Management

The Widget’s wallet management is modular, allowing to extend or override it based on your needs. If you want to control wallet states internally, refer to the guide on Dynamic Labs SDK implementation.

​
Customization

​
Interactive Playground

The Layerswap Widget is fully customizable, letting you adjust its appearance and behavior to match your application. You can play around with colors, layout, border radius, and more in our interactive Playground:

Try the Customization Playground

Experiment with all customization options in real-time. Test colors, layouts, styles, and configurations with live preview before implementing in your application.

​
Theme Configuration

You can customize the widget’s appearance to match your application’s branding: Custom Theme Apply a custom theme configuration: 
import '@layerswap/widget/index.css';
import { LayerswapProvider, Swap } from '@layerswap/widget';
import { starknetTheme } from './themeConfigs';

export default function App() {

  return (
    <LayerswapProvider
      config={{
        theme: starknetTheme,
      }}
    >
      <Swap />
    </LayerswapProvider>
  );
}
Light theme example

Customized theme example

Theme Properties
​
primary
object
Primary color palette for buttons, links, and key UI elements. Colors are specified as RGB values (e.g., ‘243, 243, 243’).
​
secondary
object
Secondary color palette for backgrounds, cards, and supporting UI elements.
​
tertiary
string
Tertiary color for subtle UI elements and borders (RGB format).
​
buttonTextColor
string
Text color for buttons (RGB format).
​
cardBackgroundStyle
object
Custom CSS styles for card background.
​
header
object
Header visibility controls:
  • hideMenu: Hide the menu button
  • hideTabs: Hide navigation tabs
  • hideWallets: Hide wallet connection display
All colors use RGB format without the rgb() wrapper (e.g., ‘243, 243, 243’ instead of ‘rgb(243, 243, 243)’). The widget internally applies the appropriate formatting.
Customize the entire color palette of the widget to match your brand. Learn more in the Color Customization section.

​
Testnet Configuration

Here’s how to test your integration on Testnet before going live: 
const config = {
  apiKey: 'YOUR_TESTNET_API_KEY',
  version: 'testnet',
  initialValues: {
    to: 'STARKNET_SEPOLIA',
    toAsset: 'USDC'
  },
}