@dextopus/deposit-widget

v0.1.1

Published

a month ago

A plug-and-play React component for cross-chain crypto deposits. Works with Next.js, Vite, and Create React App.

0High
0Medium
0Low

0xazach

react crypto deposit cross-chain web3 dextopus relay widget component

@dextopus/deposit-widget

A beautiful, production-ready React widget for cross-chain crypto deposits

A plug-and-play React component for cross-chain crypto deposits. Works seamlessly with Next.js, Vite, and Create React App.

✨ Features

🎨 Modern Portrait Design - Gold-accented (#FFB800) QR code interface
📱 Fully Responsive - Perfect on desktop and mobile (portrait layout)
🌐 Cross-Chain Support - Multiple networks and tokens via Relay integration
🔄 Auto-Clearing - Smart address updates when changing networks
🖼️ Logo Support - Displays token and network logos with white backgrounds
⚡ Real-time Updates - Live deposit status monitoring
🎯 TypeScript Ready - Full type definitions included
📦 Zero Config - Works out of the box with React, Next.js, Vite, and vanilla HTML
🌍 Multi-Chain - Solana, EVM, Bitcoin, Tron, and other blockchain support
🔒 Secure - Built-in refund address protection

Installation

npm install @dextopus/deposit-widget
# or
yarn add @dextopus/deposit-widget
# or
pnpm add @dextopus/deposit-widget

Quick Start

React / Vite

import { DepositWidget } from '@dextopus/deposit-widget';
import '@dextopus/deposit-widget/styles';

function App() {
  return (
    <DepositWidget
      mode="inline"
      apiKey="your-api-key"
      apiBaseUrl="https://api.dextopus.com"
      destinationAddress="0x7fB5d9B18197609Ab2e74Fb20452b8842AB3af02"
      destinationChainId={10} // Optimism
      destinationTokenAddress="0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85" // USDC
      refundAddresses="evm:0x...,svm:5Lrzn...,tvm:TrOn..."
    />
  );
}

Next.js (App Router)

'use client';

import { DepositWidget } from '@dextopus/deposit-widget';
import '@dextopus/deposit-widget/styles';

export default function DepositPage() {
  return (
    <div className="container mx-auto p-4">
      <DepositWidget
        mode="inline"
        apiKey={process.env.NEXT_PUBLIC_DEXTOPUS_API_KEY}
        apiBaseUrl="https://api.dextopus.com"
        destinationAddress="0x7fB5d9B18197609Ab2e74Fb20452b8842AB3af02"
        destinationChainId={10}
        destinationTokenAddress="0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85"
        refundAddresses="evm:0x...,svm:..."
      />
    </div>
  );
}

Next.js (Pages Router)

import { DepositWidget } from '@dextopus/deposit-widget';
import '@dextopus/deposit-widget/styles';

export default function Deposit() {
  return (
    <DepositWidget
      mode="inline"
      apiKey={process.env.NEXT_PUBLIC_DEXTOPUS_API_KEY}
      apiBaseUrl="https://api.dextopus.com"
      destinationAddress="0x..."
      destinationChainId={10}
      destinationTokenAddress="0x..."
      refundAddresses="evm:0x...,svm:..."
    />
  );
}

Vanilla JavaScript

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="node_modules/@dextopus/deposit-widget/dist/style.css">
</head>
<body>
  <div id="deposit-widget"></div>

  <script type="module">
    import { initDepositWidget } from '@dextopus/deposit-widget';

    initDepositWidget({
      containerId: 'deposit-widget',
      config: {
        mode: 'inline',
        apiKey: 'your-api-key',
        apiBaseUrl: 'https://api.dextopus.com',
        destinationAddress: '0x...',
        destinationChainId: 10,
        destinationTokenAddress: '0x...',
        refundAddresses: 'evm:0x...,svm:...'
      }
    });
  </script>
</body>
</html>

Widget Modes

Inline Mode

Embeds the widget directly in your page layout.

<DepositWidget mode="inline" {...config} />

Popup Mode

Opens the widget as a full-screen modal overlay.

<DepositWidget
  mode="popup"
  {...config}
  onClose={() => console.log('Widget closed')}
/>

Configuration Options

| Prop | Type | Required | Default | Description | |------|------|----------|---------|-------------| | mode | 'inline' \| 'popup' | No | 'inline' | Display mode | | apiKey | string | Yes | - | Your Dextopus API key | | apiBaseUrl | string | No | 'http://localhost:3000' | API endpoint URL | | destinationAddress | string | Yes | - | Wallet address to receive funds | | destinationChainId | number | No | - | Destination blockchain chain ID | | destinationTokenAddress | string | No | - | Token contract address on destination chain | | allowDestinationChange | boolean | No | false | Allow users to change destination | | refundAddresses | string | Yes | - | VM-prefixed refund addresses (see below) | | onClose | () => void | No | - | Callback when widget closes (popup mode) |

Refund Addresses Format

The refundAddresses prop accepts a comma-separated list of VM-type-prefixed addresses:

evm:0x7fB5d9B18197609Ab2e74Fb20452b8842AB3af02,svm:5LrznMTXfDBK4A7mzzZuGzwMVEu3nv2MLbtBE4dMsmc1,tvm:TrOnAdDrEsShErE,btc:bc1qrefundaddress

Supported VM types:

evm - Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, etc.
svm - Solana
tvm - Tron
btc - Bitcoin
ltc - Litecoin
doge - Dogecoin
And more...

Advanced Usage

Editable Destination

Allow users to configure their own destination settings:

<DepositWidget
  mode="inline"
  apiKey="your-api-key"
  apiBaseUrl="https://api.dextopus.com"
  destinationAddress="0x..."
  destinationChainId={10}
  destinationTokenAddress="0x..."
  allowDestinationChange={true}
  refundAddresses="evm:0x...,svm:..."
/>

Custom Default Selection

Pre-select a specific token and network:

<DepositWidget
  mode="inline"
  apiKey="your-api-key"
  destinationAddress="0x..."
  destinationChainId={10}
  destinationTokenAddress="0x..."
  defaultNetwork="ethereum"
  defaultCurrency="USDC"
  refundAddresses="evm:0x...,svm:..."
/>

Using the Imperative API

For more control over widget lifecycle:

import { initDepositWidget } from '@dextopus/deposit-widget';

const widget = initDepositWidget({
  containerId: 'my-widget',
  config: {
    mode: 'inline',
    apiKey: 'your-api-key',
    destinationAddress: '0x...',
    destinationChainId: 10,
    destinationTokenAddress: '0x...',
    refundAddresses: 'evm:0x...,svm:...'
  }
});

// Update configuration
widget.updateConfig({
  destinationAddress: '0xNewAddress...'
});

// Unmount widget
widget.unmount();

Supported Networks

The widget supports all networks available through the Relay protocol:

EVM: Ethereum, Base, Arbitrum, Optimism, Polygon, BSC, Avalanche, and more
Solana
Bitcoin
Tron
And many others...

🎨 Design

Portrait Layout

The widget uses a vertical stacking layout optimized for both desktop and mobile:

Max Width: 480px (mobile-first design)
Accent Color: Gold (#FFB800)
Background: Dark (#0a0a0a)
Border Radius: 24px (16px on mobile)
Layout: Portrait mode (vertical stacking)

QR Code Section

Large, scannable QR code (256x256px)
Gold background (#FFB800) for premium look
Token logo overlay at center with white background
High contrast for easy scanning

Smart Features

Auto-Clear: Wallet address and QR code automatically clear when network/currency changes
Logo Display: Actual logos for currencies and networks with fallback to letter badges
Loading States: Visual feedback during address generation
Copy Button: One-click address copying with visual confirmation
"Listening" Indicator: Animated indicator showing active deposit monitoring

Styling

The widget comes with built-in dark theme styling with gold accents. Import the CSS file:

import '@dextopus/deposit-widget/styles';

Custom Styling

Override styles using CSS custom properties:

.deposit-widget {
  --accent: #FFB800;        /* Gold accent */
  --bg: #0a0a0a;           /* Background */
  --text: #f5f5f0;         /* Text color */
  --surface: #161616;      /* Surface color */
  --line: #242424;         /* Border color */
}

TypeScript Support

The package includes full TypeScript definitions. Import types:

import type { DepositWidgetConfig } from '@dextopus/deposit-widget';

const config: DepositWidgetConfig = {
  mode: 'inline',
  apiKey: 'your-api-key',
  destinationAddress: '0x...',
  destinationChainId: 10,
  destinationTokenAddress: '0x...',
  refundAddresses: 'evm:0x...,svm:...'
};

API Reference

Component Props

interface DepositWidgetConfig {
  mode?: 'inline' | 'popup';
  apiKey: string;
  apiBaseUrl?: string;
  destinationAddress: string;
  destinationChainId?: number;
  destinationTokenAddress?: string;
  allowDestinationChange?: boolean;
  refundAddresses: string;
  defaultCurrency?: string;
  defaultNetwork?: string;
  className?: string;
  onClose?: () => void;
}

Init Function

function initDepositWidget(options: {
  containerId: string;
  config: DepositWidgetConfig;
}): {
  unmount: () => void;
  updateConfig: (newConfig: Partial<DepositWidgetConfig>) => void;
}

💻 Examples

Check out these files for complete working examples:

demo-deposit.html - Full-featured demo with all features
demo-simple.html - Minimal standalone example
EXAMPLES.md - Comprehensive integration examples for React, Next.js, TypeScript, and more
USAGE_EXAMPLE.md - Detailed usage guide with all configuration options

🚢 Production Ready

This widget is production-ready and includes:

✅ Built & Bundled - ES Module, CommonJS, and TypeScript definitions
✅ Optimized - Code-split and tree-shakeable
✅ Typed - Full TypeScript support with .d.ts files
✅ Documented - Comprehensive guides and examples
✅ Tested - Works with React 18+, Next.js 13+, Vite 5+
✅ Responsive - Mobile-first portrait design
✅ Accessible - WCAG compliant with proper contrast ratios

Package Contents

@dextopus/deposit-widget/
├── dist/
│   ├── index.js          # ES Module
│   ├── index.cjs         # CommonJS
│   ├── index.d.ts        # TypeScript definitions
│   ├── style.css         # Compiled styles
│   └── components/       # Component files
├── package.json
├── README.md
├── EXAMPLES.md
└── USAGE_EXAMPLE.md

💡 Use Cases

DeFi Platforms - Enable users to deposit from any chain
NFT Marketplaces - Accept payments across multiple networks
Gaming - In-game currency deposits
E-commerce - Cross-chain crypto payments
Wallets - Integrated deposit functionality
Payment Gateways - Multi-chain payment acceptance

🛠️ Development

# Install dependencies
yarn install

# Start development server (with network access)
yarn dev

# Build for production
yarn build

# View demos
open http://localhost:5173/demo-deposit.html
open http://localhost:5173/demo-simple.html

Browser Support

Chrome/Edge (latest)
Firefox (latest)
Safari (latest)
Mobile browsers (iOS Safari, Chrome Mobile)

📚 Documentation

Full Usage Guide - Complete feature documentation
Integration Examples - Code examples for all frameworks
API Documentation - Full API reference
GitHub Repository - Source code

License

MIT License - See LICENSE file for details

🆘 Support

For issues and questions:

GitHub Issues: https://github.com/dextopus/dextopus/issues
Documentation: https://docs.dextopus.com
Website: https://dextopus.com
API: https://api.dextopus.com

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@dextopus/deposit-widget

✨ Features

Installation

Quick Start

React / Vite

Next.js (App Router)

Next.js (Pages Router)

Vanilla JavaScript

Widget Modes

Inline Mode

Popup Mode

Configuration Options

Refund Addresses Format

Advanced Usage

Editable Destination

Custom Default Selection

Using the Imperative API

Supported Networks

🎨 Design

Portrait Layout

QR Code Section

Smart Features

Styling

Custom Styling

TypeScript Support

API Reference

Component Props

Init Function

💻 Examples

🚢 Production Ready

Package Contents

💡 Use Cases

🛠️ Development

Browser Support

📚 Documentation

License

🆘 Support